> This page is for Docs.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For task-scoped instructions for coding agents working in a Fern project, see https://buildwithfern.com/learn/home/fern-instructions.md.

# Sections, pages, and folders

> Configure the sidebar navigation for your Fern documentation site, including sections, pages, folders, URL slugs, icons, and links.

A `page` points at a single Markdown file, a `section` groups entries and can nest more sections, and a `folder` pulls in every file in a directory.

## Add a section

Sections organize your documentation in the left-side nav bar. Each section has a name and a list of `contents`, which can include pages, folders, or nested sections.

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Another page
        path: ./pages/another-page.mdx
```

Sections can be nested to create multi-level navigation hierarchies.

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Learn
    contents:
      - section: Key concepts
        contents:
          - page: Embeddings
            path: ./docs/pages/embeddings.mdx
          - page: Prompt engineering
            path: ./docs/pages/prompts.mdx
      - section: Generation
        contents:
          - page: Command nightly
            path: ./docs/pages/command.mdx
          - page: Likelihood
            path: ./docs/pages/likelihood.mdx
```

![Result of above docs.yml example](https://fern-image-hosting.s3.amazonaws.com/fern/nested-sections.png)

To add an overview page to a section, add a `path` property pointing to an `.mdx` file.

**`Section with an overview page`**

```yaml Section with an overview page {3}
navigation:
  - section: Guides
    path: ./pages/guide-overview.mdx
    contents:
      - page: Simple guide
        path: ./pages/guides/simple.mdx
      - page: Complex guide
        path: ./pages/guides/complex.mdx
```

Sections also support [`slug` and `skip-slug`](/learn/docs/seo/configuring-slugs) to customize URL paths.

> **API Reference section**
>
> Use the special `api` key to create a [generated API Reference section](/learn/docs/api-references/overview).
>
> ```yaml docs.yml
> navigation:
>   - section: Introduction
>     contents:
>       - page: My page
>         path: ./pages/my-page.mdx
>   - api: API Reference
> ```

## Add a page

Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path.

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Another page
        path: ./pages/another-page.mdx
```

## Add a folder

Add a `folder` entry pointing to a directory. Fern auto-discovers all `.md` and `.mdx` files and adds them to the navigation.

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Introduction
    contents:
      - folder: ./pages/guides
        title: Guides # Optional, defaults to folder name
```

For the pages in a folder, Fern automatically:

* Derives titles and [URL slugs](#slugs-and-url-paths) from filenames
* Creates nested sections from subdirectories
* Sorts pages alphabetically
* Uses `index.mdx` or `index.md` files as section overview pages (case-insensitive)

#### Folder configuration options

Customize folder behavior with these options:

**`docs.yml`**

```yaml docs.yml
navigation:
  - folder: ./pages/guides
    title: Guides                  # Display name in sidebar
    slug: user-guides              # Custom URL path
    title-source: frontmatter      # Use frontmatter titles
```

**`title`** `string`

The title to display for this folder section. If not provided, the folder name is used.

---

**`title-source`** `'filename' | 'frontmatter'` — default: filename

Determines how page and section titles within the folder are derived. By default (`filename`), titles are derived from file names. Set to `frontmatter` to use the `title` field from each file's frontmatter instead (falls back to filename if not set). This per-folder setting overrides the global [`settings.folder-title-source`](/learn/docs/configuration/site-level-settings#settingsfolder-title-source) value.

---

**`slug`** `string`

Overrides the auto-generated URL slug for the folder.

---

**`skip-slug`** `boolean` — default: false

Omits the folder from the URL path, so pages appear at the parent level.

---

**`position`** `number`

Set in page frontmatter to control ordering within the folder. Pages with `position` appear first (sorted numerically), followed by the rest alphabetically.

**`page frontmatter`**

```yaml page frontmatter
---
title: Quickstart
position: 1
---
```

---

## Slugs and URL paths

Fern builds each page's URL by combining slugs from every level of its navigation hierarchy — section, folder, tab, version, and product. Each level gets an auto-generated slug from its display name, or from the filename for [folder-based navigation](#add-a-folder). You can [rename a slug, skip a level, or override the path in a page's frontmatter](/learn/docs/seo/configuring-slugs).

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Get Started        # slug renamed to "start"
    slug: start
    contents:
      - section: Guides         # skipped — omitted from the URL
        skip-slug: true
        contents:
          - page: Quickstart    # slug renamed to "quick"
            slug: quick
            path: ./pages/quickstart.mdx
```

The **Quickstart** page is hosted at `/start/quick`. The renamed section and page slugs apply, and the skipped **Guides** slug drops out of the path.

## Hiding content

To hide a page, folder, or section, add `hidden: true`. Hidden content (including all pages within a folder) is still accessible via direct URL but is excluded from search and won't be indexed.

**`docs.yml`**

```yaml docs.yml {7, 10, 12}
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Hidden page
        hidden: true
        path: ./pages/my-hidden-page.mdx
      - folder: .pages/features
        title: Hidden folder
        hidden: true
  - section: Hidden sections
    hidden: true
    contents:
      - page: Another hidden page
        path: ./pages/also-hidden.mdx
```

## Availability

Set availability badges on pages, sections, or folders to indicate their lifecycle status. The badge is shown in the page header; the value controls the badge label and style:

| Value                 | Badge                                               |
| --------------------- | --------------------------------------------------- |
| `beta`                | Yes                                                 |
| `pre-release`         | Yes                                                 |
| `in-development`      | Yes                                                 |
| `deprecated`          | Yes, and the title is struck through in the sidebar |
| `stable`              | No (default available state)                        |
| `generally-available` | No (default available state)                        |

To render availability badges in the sidebar navigation in addition to the page header, [set `layout.show-nav-availability-badges: true` in `docs.yml`](/learn/docs/configuration/site-level-settings#layoutshow-nav-availability-badges).

Pages inherit availability from their parent section or folder unless overridden by:

* A per-page `availability` setting in `docs.yml` (shown below)
* [Page frontmatter availability](/learn/docs/configuration/page-level-settings#availability), which takes precedence over all `docs.yml` availability

**`docs.yml`**

```yaml docs.yml {3, 11, 14}
navigation:
  - section: Developer resources
    availability: generally-available
    contents:
      - page: Code examples # Inherits generally-available
        path: ./pages/code-examples.mdx
      - folder: ./pages/cli-tools # Inherits generally-available
        title: CLI tools
      - page: Testing framework
        path: ./pages/testing-framework.mdx
        availability: beta # Overrides section-level availability
      - folder: ./pages/performance-monitoring
        title: Performance monitoring
        availability: in-development # Overrides section-level availability
```

> **Note**
>
> If you have different versions of your docs, section, folder, and page availability should be set in [the `.yml` files that define the navigational structure for each version](/learn/docs/configuration/versions#define-your-versions).

[API Reference sections and endpoints](/learn/docs/api-references/customize-api-reference-layout#adding-availability) render the same sidebar badges based on their availability.

## Collapsed sections or folders

By default, sections and folders are expanded and not collapsible. Use the `collapsed` property to control how they appear in the sidebar when the page loads.

| Value             | Behavior                                                                                      |
| ----------------- | --------------------------------------------------------------------------------------------- |
| `true`            | Collapsed on load. The user can expand it.                                                    |
| `open-by-default` | Expanded on load, but collapsible. The section displays a toggle so the user can collapse it. |

**`Example config with collapsed sections`**

```yaml {8, 10, 17} Example config with collapsed sections
navigation:
  - section: Getting started # expanded, not collapsible (default)
    contents:
      - page: Introduction
        path: ./pages/intro.mdx
      - folder: ./pages/features
        title: Features
        collapsed: true # Folder starts collapsed
  - section: Advanced topics
    collapsed: true # Section starts collapsed
    contents:
      - page: Custom CSS
        path: ./pages/advanced/css.mdx
      - page: Analytics
        path: ./pages/advanced/analytics.mdx
  - section: API guides
    collapsed: open-by-default # Section starts expanded, but can be collapsed by the user
    contents:
      - page: Authentication
        path: ./pages/api/auth.mdx
      - page: Pagination
        path: ./pages/api/pagination.mdx
```

## Sidebar icons

Add icons next to sections, pages, and folders using the `icon` key.

Icons can be in three formats:

* **Font Awesome icons**: Use icon names like `fa-solid fa-rocket`. Pro and Brand Icons from Font Awesome are supported.
* **Custom image files**: Use relative paths to image files (e.g., `./assets/icons/my-icon.svg` or `../assets/icons/my-icon.png`). Paths are relative to the YAML file where the icon is referenced (e.g., `docs.yml`). For example, if you set an icon in `fern/products/my-product.yml`, the path `./assets/icon.svg` resolves to `fern/products/assets/icon.svg`. If you set it in `fern/docs.yml`, the same path resolves to `fern/assets/icon.svg`.
* **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).

**`Example config with different icon files`**

```yaml Example config with different icon files {3, 6, 10-11, 14}
navigation:
  - section: Home
    icon: fa-regular fa-home  # Font Awesome icon
    contents:
      - page: Introduction
        icon: ./assets/icons/intro-icon.svg  # Custom image file
        path: ./pages/intro.mdx
      - folder: .pages/features
        title: Custom features
        icon: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z'/></svg>"  # Inline SVG
        path: ./pages/custom.mdx
  - api: API Reference
    icon: fa-regular fa-puzzle
```

## Links

You can add a link to an external page within your sidebar navigation with the following configuration:

**`docs.yml`**

```yaml title="docs.yml"
navigation:
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube channel
        href: https://www.youtube.com/
```

![An external link within navigation](/learn/_fern-files/_img/b43c1214e4ce8206db3e263383ae7ac7561ead361a4798021da237574b01ec9e.webp)

### Link target

Control where links open with the `target` property. Available for product, tab, navbar, and page links. For typical documentation sites, links can open in the same tab (`_self`) or new tab (`_blank`). For documentation embedded in a dashboard or iframe, links can open in the parent frame (`_parent`) or topmost frame (`_top`).

**`docs.yml`**

```yaml title="docs.yml" {8}
navigation:
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube channel
        href: https://www.youtube.com/
        target: _blank
```