# Folders

Folders in `docs/` become sections of the navigation, nested as deep as your folders go. A folder only appears when it contains at least one page.

## Title, icon and order

A folder describes itself in an `index.md` inside it, with the same front matter as a page:

```tree
docs/guides/
  index.md       # the folder's title, icon and order
  setup.md
  deploying.md
```

```markdown [docs/guides/index.md]
---
title: Guides
icon: fa-solid fa-book-open
order: 3
---
```

| Field | Default | Purpose |
|-------|---------|---------|
| `title` | the first heading of `index.md`, then the folder name | Title in the sidebar, breadcrumbs and search |
| `icon` | `fa-solid fa-folder` | [Font Awesome](https://clay-doc.github.io/clay-example-repo/4.x/features/themes-and-icons.md) icon |
| `order` | none | Position among the pages and folders next to it |

Without an `index.md`, a folder is named after its folder name: `getting-started` becomes "Getting started".

## A page for the folder

When `index.md` has text below its front matter, that text is the folder's page, shown when readers open the folder at its URL (`/guides`). An `index.md` with only front matter just names the folder; its page then lists the pages in it. See [index pages](https://clay-doc.github.io/clay-example-repo/4.x/organizing/index-pages.md).

## Folders in other languages

Translate a folder like a page: `index.de.md` next to `index.md` gives the folder its German title and German page.

::: tabs
== index.md
```markdown
---
title: Guides
order: 3
---

# Guides

Step-by-step guides for …
```
== index.de.md
```markdown
---
title: Anleitungen
---

# Anleitungen

Schritt-für-Schritt-Anleitungen für …
```
:::

The order always comes from the original `index.md`.

> [!TIP]
> `clay edit` creates folders with their `index.md`, and writes the title, icon and order of existing ones. See [clay edit](https://clay-doc.github.io/clay-example-repo/4.x/organizing/clay-edit.md).

---

All pages of these docs, as Markdown for language models: https://clay-doc.github.io/clay-example-repo/4.x/llms.txt