Skip to navigation
ConfigurationNavigation

Sections, pages, and folders

Organize your sidebar navigation structure in docs.yml

View as Markdown

A page points at a single Markdown file, a section groups entries and can nest more sections, and a folder pulls in every file in a directory.

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
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Another page
        path: ./pages/another-page.mdx

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

docs.yml
navigation:
  - section: Learn
    contents:
      - section: Key concepts
        contents:
          - page: Embeddings
            path: ./docs/pages/embeddings.mdx
          - page: Prompt engineering
            path: ./docs/pages/prompts.mdx
      - section: Generation
        contents:
          - page: Command nightly
            path: ./docs/pages/command.mdx
          - page: Likelihood
            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
navigation:
  - section: Guides
    path: ./pages/guide-overview.mdx
    contents:
      - page: Simple guide
        path: ./pages/guides/simple.mdx
      - page: Complex guide
        path: ./pages/guides/complex.mdx

Sections also support slug and skip-slug to customize URL paths.

API Reference section

Use the special api key to create a generated API Reference section.

docs.yml
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
  - api: API Reference

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
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Another page
        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
navigation:
  - section: Introduction
    contents:
      - folder: ./pages/guides
        title: Guides # Optional, defaults to folder name

For the pages in a folder, Fern automatically:

  • Derives titles and URL slugs from filenames
  • 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
navigation:
  - folder: ./pages/guides
    title: Guides                  # Display name in sidebar
    slug: user-guides              # Custom URL path
    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 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.

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
---
title: Quickstart
position: 1
---

Slugs and URL paths

Fern builds each page’s URL by combining slugs from every level of its navigation hierarchy — section, folder, tab, version, and product. Each level gets an auto-generated slug from its display name, or from the filename for folder-based navigation. You can rename a slug, skip a level, or override the path in a page’s frontmatter.

docs.yml
navigation:
  - section: Get Started        # slug renamed to "start"
    slug: start
    contents:
      - section: Guides         # skipped — omitted from the URL
        skip-slug: true
        contents:
          - page: Quickstart    # slug renamed to "quick"
            slug: quick
            path: ./pages/quickstart.mdx

The Quickstart page is hosted at /start/quick. The renamed section and page slugs apply, and the skipped Guides slug drops out of the path.

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
navigation:
  - section: Introduction
    contents:
      - page: My page
        path: ./pages/my-page.mdx
      - page: Hidden page
        hidden: true
        path: ./pages/my-hidden-page.mdx
      - folder: .pages/features
        title: Hidden folder
        hidden: true
  - section: Hidden sections
    hidden: true
    contents:
      - page: Another hidden page
        path: ./pages/also-hidden.mdx

Availability

Set availability badges on pages, sections, or folders to indicate their lifecycle status. The badge is shown in the page header; the value controls the badge label and style:

ValueBadge
betaYes
pre-releaseYes
in-developmentYes
deprecatedYes, and the title is struck through in the sidebar
stableNo (default available state)
generally-availableNo (default available state)

To render availability badges in the sidebar navigation in addition to the page header, set layout.show-nav-availability-badges: true in docs.yml.

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

docs.yml
navigation:
  - section: Developer resources
    availability: generally-available
    contents:
      - page: Code examples # Inherits generally-available
        path: ./pages/code-examples.mdx
      - folder: ./pages/cli-tools # Inherits generally-available
        title: CLI tools
      - page: Testing framework
        path: ./pages/testing-framework.mdx
        availability: beta # Overrides section-level availability
      - folder: ./pages/performance-monitoring
        title: Performance monitoring
        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.

API Reference sections and endpoints render the same sidebar badges based on their availability.

Collapsed sections or folders

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.

ValueBehavior
trueCollapsed on load. The user can expand it.
open-by-defaultExpanded on load, but collapsible. The section displays a toggle so the user can collapse it.
Example config with collapsed sections
navigation:
  - section: Getting started # expanded, not collapsible (default)
    contents:
      - page: Introduction
        path: ./pages/intro.mdx
      - folder: ./pages/features
        title: Features
        collapsed: true # Folder starts collapsed
  - section: Advanced topics
    collapsed: true # Section starts collapsed
    contents:
      - page: Custom CSS
        path: ./pages/advanced/css.mdx
      - page: Analytics
        path: ./pages/advanced/analytics.mdx
  - section: API guides
    collapsed: open-by-default # Section starts expanded, but can be collapsed by the user
    contents:
      - page: Authentication
        path: ./pages/api/auth.mdx
      - page: Pagination
        path: ./pages/api/pagination.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 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.
  • Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").
Example config with different icon files
navigation:
  - section: Home
    icon: fa-regular fa-home  # Font Awesome icon
    contents:
      - page: Introduction
        icon: ./assets/icons/intro-icon.svg  # Custom image file
        path: ./pages/intro.mdx
      - folder: .pages/features
        title: Custom features
        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
        path: ./pages/custom.mdx
  - api: API Reference
    icon: fa-regular fa-puzzle

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

docs.yml
navigation:
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube channel
        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
navigation:
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube channel
        href: https://www.youtube.com/
        target: _blank