Configuration

Configure your site navigation

View as Markdown

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:

An example docs.yml
1# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
2navigation:
3  - section: Home
4    contents:
5      - page: Introduction
6        path: ./intro.mdx
7      - folder: ./auth # directory
8        title: Authentication
9  - api: API Reference
10navbar-links:
11  - type: secondary
12    text: Contact support
13    url: https://example.com/support
14  - type: primary
15    text: Login
16    url: https://example.com/login

Sections, pages, and folders

Build your navigation by combining sections, pages, and folders.

API Reference section

Use the special api key to create an automatically generated API Reference section. For more information, see Generate API Reference.

docs.yml
1navigation:
2  - section: Introduction
3    contents:
4      - page: My page
5        path: ./pages/my-page.mdx
6  - api: API Reference

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
1navigation:
2  - section: Introduction
3    contents:
4      - page: My page
5        path: ./pages/my-page.mdx
6      - page: Another page
7        path: ./pages/another-page.mdx

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

docs.yml
1navigation:
2  - section: Learn
3    contents:
4      - section: Key concepts
5        contents:
6          - page: Embeddings
7            path: ./docs/pages/embeddings.mdx
8          - page: Prompt engineering
9            path: ./docs/pages/prompts.mdx
10      - section: Generation
11        contents:
12          - page: Command nightly
13            path: ./docs/pages/command.mdx
14          - page: Likelihood
15            path: ./docs/pages/likelihood.mdx

Result of above docs.yml example

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

Section with an overview page
1navigation:
2  - section: Guides
3    path: ./pages/guide-overview.mdx
4    contents:
5      - page: Simple guide
6        path: ./pages/guides/simple.mdx
7      - page: Complex guide
8        path: ./pages/guides/complex.mdx

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
1navigation:
2  - section: Introduction
3    contents:
4      - page: My page
5        path: ./pages/my-page.mdx
6      - page: Another page
7        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.

pages
guides
index.mdx# Becomes the section overview page
quickstart.mdx
advanced
index.mdx# Becomes the nested section overview
auth.mdx
docs.yml
1navigation:
2  - section: Introduction
3    contents:
4      - folder: ./pages/guides
5        title: Guides # 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
  • Sorts pages alphabetically
  • Uses index.mdx or index.md files as section overview pages (case-insensitive)

Customize folder behavior with these options:

docs.yml
1navigation:
2  - folder: ./pages/guides
3    title: Guides                  # Display name in sidebar
4    slug: user-guides              # Custom URL path
5    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'Defaults to filename

Determines how page and section titles with 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).

slug
string

Overrides the auto-generated URL slug for the folder.

skip-slug
booleanDefaults to 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
1---
2title: Quickstart
3position: 1
4---

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
1navigation:
2  - section: Introduction
3    contents:
4      - page: My page
5        path: ./pages/my-page.mdx
6      - page: Hidden page
7        hidden: true
8        path: ./pages/my-hidden-page.mdx
9      - folder: .pages/features
10        title: Hidden folder
11        hidden: true
12  - section: Hidden sections
13    hidden: true
14    contents:
15      - page: Another hidden page
16        path: ./pages/also-hidden.mdx

Availability

Set availability badges on pages, sections, or folders. Options are: stable, generally-available, in-development, pre-release, deprecated, or beta.

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

docs.yml
1navigation:
2  - section: Developer resources
3    availability: generally-available
4    contents:
5      - page: Code examples # Inherits generally-available
6        path: ./pages/code-examples.mdx
7      - folder: ./pages/cli-tools # Inherits generally-available
8        title: CLI tools
9      - page: Testing framework
10        path: ./pages/testing-framework.mdx
11        availability: beta # Overrides section-level availability
12      - folder: ./pages/performance-monitoring
13        title: Performance monitoring
14        availability: in-development # Overrides section-level availability

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.

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.

Example config with collapsed section
1navigation:
2  - section: Getting started
3    contents:
4      - page: Introduction
5        path: ./pages/intro.mdx
6      - folder: ./pages/features
7        title: Features
8        collapsed: true
9  - section: Advanced topics
10    collapsed: true
11    contents:
12      - page: Custom CSS
13        path: ./pages/advanced/css.mdx
14      - page: Analytics
15        path: ./pages/advanced/analytics.mdx

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>").
Example config with different icon files
1navigation:
2  - section: Home
3    icon: fa-regular fa-home  # Font Awesome icon
4    contents:
5      - page: Introduction
6        icon: ./assets/icons/intro-icon.svg  # Custom image file
7        path: ./pages/intro.mdx
8      - folder: .pages/features
9        title: Custom features
10        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
11        path: ./pages/custom.mdx
12  - api: API Reference
13    icon: fa-regular fa-puzzle

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

docs.yml
1navigation:
2  - section: Home
3    contents:
4      - page: Introduction
5        path: ./intro.mdx
6      - link: Our YouTube channel
7        href: https://www.youtube.com/
An external link within navigation

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
1navigation:
2  - section: Home
3    contents:
4      - page: Introduction
5        path: ./intro.mdx
6      - link: Our YouTube channel
7        href: https://www.youtube.com/
8        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.

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.

Product switching

If you have multiple products in your documentation, you can introduce a dropdown product selector 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. For more information, see Product switching.