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.
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.
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:
To add another section, add another section
to the navigation
. Example:
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:
Sidebar icons
For icons to appear next to sections and pages, add the icon
key. The value should be a valid FontAwesome icon name.
Navigation bar links
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.
navbar-link type
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.
navbar-link text
Set the link text that is displayed to the user.
navbar-link url
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 https://www.example.com/login
, set the url
to https://www.example.com/login?utm_source=docs&utm_medium=navbar
.
Tabs
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.
Here’s an example of what the Tabs implementation looks like:
Versions
If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the 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/
: