Configure your site navigation
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:
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:
pageManually list your pages with names and corresponding file paths.folderAuto-discover pages from a directory and add them to your navigation.
You can combine folder-based navigation with manually defined pages.
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 page.
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.
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.
For the pages in a folder, Fern automatically converts filenames to titles and URL slugs, creates nested sections from subdirectories, and sorts pages alphabetically.
Control page order
Use frontmatter position to control page order. Pages with a position field are sorted numerically before alphabetically sorted pages.
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.
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.
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.
Folder slugs
Specify a custom URL slug for the folder section. If not provided, a slug will be generated from the folder name.
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.
Section overviews
To add an overview page to a section, add a path property to the section.
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:
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.
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.svgor../assets/icons/my-icon.png). Paths are relative to thedocs.ymlfile. - Inline SVG: Provide an SVG string wrapped in quotes (e.g.,
"<svg>...</svg>").
Links
You can add a link to an external page within your sidebar navigation with the following configuration:
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.
