# Configure your site navigation

> Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.

Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site.

Here's a complete example of a `docs.yml` file:

<CodeBlock title="An example docs.yml">
  ```yaml
  # yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
  navigation:
    - section: Home
      contents:
        - page: Introduction
          path: ./intro.mdx
        - folder: ./auth # directory
          title: Authentication
    - api: API Reference
  navbar-links:
    - type: secondary
      text: Contact support
      url: https://example.com/support
    - type: primary
      text: Login
      url: https://example.com/login
  ```
</CodeBlock>

## Sections, contents, pages, and folders

Sections organize your documentation in the left-side nav bar. Each `section` has a name and a list of `contents`. Sections appear in the order listed in `docs.yml`.

In `contents`, you can add individual pages, folders, or both:

* `page` Manually list your pages with names and corresponding file paths.
* `folder` Auto-discover pages from a directory and add them to your navigation.

You can combine folder-based navigation with manually defined pages.

<Info title="API Reference section">
  Use the special `api` key to create an automatically generated API Reference section. You don't need to add any pages to it manually. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page.

  ```yaml docs.yml {6}
  navigation:
    - section: Introduction
      contents:
        - page: My page
          path: ./pages/my-page.mdx
    - api: API Reference
  ```
</Info>

<AccordionGroup>
  <Accordion title="Add a page">
    Create an `.md` or `.mdx` file. Then in `docs.yml`, add a new `page` to the `contents` list, providing the path to the file you created.

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

  <Accordion title="Add a folder">
    Create a directory with one or more `.md` or `.mdx` files. Add a `folder` key to your navigation configuration with the relative path to the directory you just created. Fern discovers all files in the directory and adds them to the navigation.

    ```yaml docs.yml {4-5}
    navigation:
      - section: Introduction
        contents:
          - folder: ./pages/getting-started
            title: Getting started # Optional, defaults to folder name
    ```

    For the pages in a folder, Fern automatically converts filenames to titles and URL slugs, creates nested sections from subdirectories, and sorts pages alphabetically.

    <Note title="Control page order">
      Use frontmatter `position` to control page order. Pages with a `position` field are sorted numerically before alphabetically sorted pages.

      ```jsx /pages/getting-started/quickstart.mdx
        ---
        title: Quickstart
        position: 1
        ---
      ```
    </Note>
  </Accordion>
</AccordionGroup>

## 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.

{/* <!-- vale off --> */}

```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
```

{/* <!-- vale on --> */}

## Availability

Set availability for individual pages, sections, or folders. Pages inherit availability from their parent section or folder unless explicitly overridden.

Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.

```yaml Availability {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).
</Note>

## Folder slugs

Specify a custom URL slug for the folder section. If not provided, a slug will be generated from the folder name.

```yaml docs.yml {4}
navigation:
  - folder: ./pages/guides
    title: Guides
    slug: user-guides
```

Skip adding the folder's slug to the URL path. This is useful when you want the pages to appear at the parent level in the URL structure.

```yaml docs.yml {4}
navigation:
  - folder: ./pages/guides
    title: Guides
    skip-slug: true
```

## Section overviews

To add an overview page to a section, add a `path` property to the section.

{/* <!-- vale off --> */}

```yaml Example section with an overview {7}
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - section: Guides
        path: ./pages/guide-overview.mdx
        contents:
          - page: Simple guide
            path: ./pages/guides/simple.mdx
          - page: Complex guide
            path: ./pages/guides/complex.mdx
```

{/* <!-- vale on --> */}

## Nested sections

If you'd like a section to toggle into more sections and pages, you can nest sections within sections. Here's an example:

```yaml Example navigation config with nested sections
navigation:
  - tab: guides
    layout:
      - 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
```

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

## Collapsed sections or folders

You can set sections or folders to be collapsed by default when the page loads by adding `collapsed: true`.
This helps keep the navigation tidy when you have many sections or want to highlight the most important sections by keeping others collapsed.

```yaml {8, 10} Example config with collapsed section
navigation:
  - section: Getting started
    contents:
      - page: Introduction
        path: ./pages/intro.mdx
      - folder: ./pages/features
        title: Features
        collapsed: true
  - section: Advanced topics
    collapsed: true
    contents:
      - page: Custom CSS
        path: ./pages/advanced/css.mdx
      - page: Analytics
        path: ./pages/advanced/analytics.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 `docs.yml` file.
* **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `"<svg>...</svg>"`).

{/* <!-- vale off --> */}

```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
```

{/* <!-- vale on --> */}

## Links

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

{/* <!-- vale off --> */}

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

{/* <!-- vale on --> */}

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/b43c1214e4ce8206db3e263383ae7ac7561ead361a4798021da237574b01ec9e/products/docs/pages/navigation/external-link.png" alt="An external link within navigation" />
</Frame>

### 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`).

```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
```

## Tabs

You can add tabs to group sections of content together. Tabs can contain different layouts and navigation structures, and you can use tab variants to show different content variations within a single tab. For more information, see [Tabs and tab variants](/learn/docs/configuration/tabs).

## Versions

If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out the [documentation on versioning](/learn/docs/building-your-docs/versioning).

## Product switching

If you have multiple products in your documentation, you can introduce a [dropdown product selector](/learn/docs/configuration/products) by creating separate product configuration files. Each product can contain its own distinct versions, tabs, sections, pages, and API References, though products can also share content.

<CodeBlock title="docs.yml">
  ```yaml {2-3, 7-8}
  products:
    - display-name: Product A
      path: ./products/product-a.yml
      icon: fa-solid fa-leaf # optional
      slug: product-a # optional
      subtitle: Product A subtitle # optional
    - display-name: Product B
      path: ./products/product-b/latest.yml # <-- default showing latest
      image: ./images/product-b.png # optional
      slug: product-b # optional
      subtitle: Product B subtitle # optional
  ```
</CodeBlock>