Tabs

Tabs split a product or version into parallel bodies of content, each with its own sidebar. Tab variants give a single tab more than one version of its content, such as REST versus GraphQL or beginner versus advanced.

Two tabs make sense when the content is unrelated, like guides and an API Reference. Variants of one tab make sense when it covers the same ground for a different reader.

To configure tabs:

Declare each tab under the top-level tabs key with a display-name and an icon.
Reference the tab in navigation with tab:. Each tab requires either a layout for its content, variants for tab variants, or an href pointing at an external URL.

docs.yml

tabs: # Declare each tab
  api: 
    display-name: API Reference
    icon: puzzle # Font Awesome icon
  help:
    display-name: Help center
    icon: ./assets/icons/help-icon.svg  # Custom image file
  github:
    display-name: GitHub
    icon: brands github # Font Awesome icon
    href: https://github.com/fern-api/fern
    target: _blank # Link opens in a new tab
    
navigation: # Reference each tab by its key
  - tab: api
    layout: 
      - section: Introduction
        contents: 
          - page: My page
            path: my-page.mdx
      - api: API Reference   
  - tab: help
    layout: 
      - section: Help center
        contents: 
          - page: Contact us
            path: contact-us.mdx
  - tab: github # External link, so no layout

Tab icons

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>").

Tabs placement and styling

Tabs display in the left sidebar by default. Use theme.tabs to control placement, style, and alignment.

docs.yml

theme:
  tabs:
    style: bubble        # "default" (underline) or "bubble" (pill-shaped)
    alignment: center    # "left" or "center" (center only applies to header tabs)
    placement: header    # "header" or "sidebar"

Tab properties

display-name

stringRequired

The name shown in the tab header

icon

string

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>").

slug

string

Custom URL slug for the tab

skip-slug

boolean

Exclude the tab slug from URLs

hidden

boolean

Hide the tab from navigation. See Hiding content for details.

layout

list

Navigation structure for the tab’s content. Required unless the tab uses variants or href.

variants

list

List of tab variants. Use instead of layout.

href

string

External URL. When set, clicking the tab redirects to this URL. Tabs with href must not include layout or variants.

target

string

Where the link opens. One of _blank, _self, _parent, or _top.

changelog

string

Path to a changelog folder, relative to the YAML file where it is set (e.g., docs.yml)

viewers

string | list

Role-based access control for the tab

orphaned

boolean

When true, roles don’t inherit from parent elements

feature-flag

string | object

Conditional display configuration

Tab variants

To add variants to a tab:

Replace the tab’s layout with a variants list. The declaration under tabs: doesn’t change.
Give each variant a title and its own layout.

Variants support RBAC, so a variant can be limited to readers holding a given role.

docs.yml

tabs: 
  api: 
    display-name: API Reference
    icon: puzzle
  help:
    display-name: Help center
    icon: home
  github:
    display-name: GitHub
    icon: brands github
    href: https://github.com/fern-api/fern
    
navigation: 
  - tab: api
    layout: 
      - section: Introduction
        contents: 
          - page: My page
            path: my-page.mdx
      - api: API Reference   
  - tab: help
    variants: # Replaces this tab's layout
      - title: For developers # Each variant has its own title and layout
        layout:
          - section: Getting started
            contents:
              - page: Quick start
                path: ./pages/dev-quickstart.mdx
      - title: For product managers
        layout:
          - section: Getting started
            contents:
              - page: Overview
                path: ./pages/pm-overview.mdx
  - tab: github

Variant properties

title

stringRequired

Display name for the variant

layout

listRequired

Navigation structure using the same format as regular tab layouts

subtitle

string

Text displayed below the variant title

icon

string

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>").

slug

string

Custom URL slug for the variant

skip-slug

boolean

Exclude the variant slug from URLs

hidden

boolean

Hide the variant from navigation. See Hiding content for details.

default

boolean

When true, this variant displays by default. If not specified, the first variant in the list is used.

viewers

string | list

Role-based access control for the variant

orphaned

boolean

When true, roles don’t inherit from parent elements

feature-flag

string | object

Conditional display configuration