Building Your Docs

Configure your site navigation

Use docs.yml

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

An example docs.yml
2 - section: Home
3 contents:
4 - page: Introduction
5 path: ./intro.mdx
6 - page: Authentication
7 path: ./auth.mdx
8 - api: API Reference
10 - type: secondary
11 text: Contact support
12 url:
13 - type: primary
14 text: Login
15 url:

Sections, contents, and pages

The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each section has a name and a list of contents. The sections appear in the left-side nav bar in the order that they are listed in docs.yml.

In contents, list your pages with names and corresponding file paths. The supported file types for pages are .md or .mdx.

A basic navigation configuration with two sections is shown below. The first section is called Introduction and contains a single page called My Page. The second section is called API Reference. This is a special type of section that’s automatically generated by Fern, and you do not need to add any pages to it by hand. For more information, see the Generate API reference page.

Example navigation config
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: ./pages/my-page.mdx
6 - api: API Reference

If you want to add another page to an existing section, create an .md or .mdx file. Then in docs.yml, create a new page in the contents list for that section, providing the path to the .md or .mdx file you created. Example:

Example navigation config
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
8 - api: API Reference

To add another section, add another section to the navigation. Example:

Example navigation config with additional section
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: ./pages/my-page.mdx
6 - api: API Reference
7 - section: Help Center
8 contents:
9 - page: Contact Us
10 path: contact-us.mdx

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:

Example navigation config with nested sections
2 - tab: guides
3 layout:
4 - section: Learn
5 contents:
6 - section: Key Concepts
7 contents:
8 - page: Embeddings
9 path: ./docs/pages/embeddings.mdx
10 - page: Prompt Engineering
11 path: ./docs/pages/prompts.mdx
12 - section: Generation
13 contents:
14 - page: Command Nightly
15 path: ./docs/pages/command.mdx
16 - page: Likelihood
17 path: ./docs/pages/likelihood.mdx

Result of above docs.yml example

For icons to appear next to sections and pages, add the icon key. The value should be a valid FontAwesome icon name.

Example navigation config with icons
2 - section: Home
3 icon: fa-regular fa-home
4 contents:
5 - page: My Page
6 icon: fa-regular fa-file
7 path: ./pages/my-page.mdx
8 - api: API Reference
9 icon: fa-regular fa-puzzle

For links that you want to be easily accessible, you can specify a list of links in navbar-links. These links appear as buttons in the top right of your documentation website.

Example of navbar-links config
2 - type: secondary
3 text: Contact support
4 url:
5 - type: primary
6 text: Login
7 url:

Set the type to either primary or secondary. Primary links are designed to stand out and indicate that they are clickable with an arrow >. You can have one primary link.

Set the link text that is displayed to the user.

Set the target url for the link.

To use a relative URL, make sure that you use / to begin the URL instead of ./. This link opens in a new browser tab, regardless of whether it is a relative or absolute URL.

You can use a trackable link in your URL. For example, if using UTM parameters, instead of, set the url to


Within the navigation, you can add tabs. Tabs are used to group sections together. The example below shows tabs for Help Center, API Reference, and an external link to Github. Each tab has a title and icon. Browse the icons available from FontAwesome.

2 api:
3 display-name: API Reference
4 icon: puzzle
5 help:
6 display-name: Help Center
7 icon: home
8 github:
9 display-name: GitHub
10 icon: brands github
11 href:
13 navigation:
14 - tab: api
15 layout:
16 - section: Introduction
17 contents:
18 - page: My Page
19 path: my-page.mdx
20 - api: API Reference
21 - tab: help
22 layout:
23 - section: Help Center
24 contents:
25 - page: Contact Us
26 path: contact-us.mdx
27 - tab: github

Here’s an example of what the Tabs implementation looks like:

Screenshot showing two vertically stacked tabs labeled API Reference and Help Center


If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the versions.

A dropdown of the available versions

When adding an entry to the versions list, specify the version’s display-name, which is visible to users, and path, which is a file that must be in a folder called versions/:

2 - display-name: v1.0
3 path: v1-0.yml # must be in a `versions` folder
4 - display-name: v1.1
5 path: v1-1.yml
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: my-page.mdx
6 - api: API Reference
2 api:
3 title: API Reference
4 icon: puzzle
5 help:
6 title: Help Center
7 icon: home
9 navigation:
10 - tab: api
11 contents:
12 - section: Introduction
13 contents:
14 - page: My Page
15 path: my-page.mdx
16 - api: API Reference
17 - tab: help
18 contents:
19 - section: Help Center
20 contents:
21 - page: Contact Us
22 path: contact-us.mdx