Sections, pages, and folders
Organize your sidebar navigation structure in docs.yml
Organize your sidebar navigation structure in docs.yml
The navigation key in docs.yml defines your sidebar structure. Build it by combining sections, pages, and folders.
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.
Sections can be nested to create multi-level navigation hierarchies.
To add an overview page to a section, add a path property pointing to an .mdx file.
Create an .md or .mdx file, then add a page entry to a section’s contents with the file path.
Add a folder entry pointing to a directory. Fern auto-discovers all .md and .mdx files and adds them to the navigation.
For the pages in a folder, Fern automatically:
index.mdx or index.md files as section overview pages (case-insensitive)Customize folder behavior with these options:
The title to display for this folder section. If not provided, the folder name is used.
Determines how page and section titles within 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). This per-folder setting overrides the global settings.folder-title-source value.
Overrides the auto-generated URL slug for the folder.
Omits the folder from the URL path, so pages appear at the parent level.
Set in page frontmatter to control ordering within the folder. Pages with position appear first (sorted numerically), followed by the rest alphabetically.
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.
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:
availability setting in docs.yml (shown below)docs.yml availabilityIf 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.
By default, sections and folders are expanded and not collapsible. Use the collapsed property to control how they appear in the sidebar when the page loads.
Add icons next to sections, pages, and folders using the icon key.
Icons can be in three formats:
fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported../assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg."<svg>...</svg>").You can add a link to an external page within your sidebar navigation with the following configuration:
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).