Configuration

Tabs and tab variants

Tabs let you group sections of your documentation together, while tab variants allow you to display different content perspectives within a single tab.

Tabs

Add tabs 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.

docs.yml
1tabs: 
2  api: 
3    display-name: API Reference
4    icon: puzzle # Font Awesome icon
5  help:
6    display-name: Help center
7    icon: ./assets/icons/help-icon.svg  # Custom image file
8  github:
9    display-name: GitHub
10    icon: brands github # Font Awesome icon
11    href: https://github.com/fern-api/fern
12    
13 navigation: 
14  - tab: api
15    layout: 
16      - section: Introduction
17          contents: 
18            - page: My page
19                path: my-page.mdx
20        - api: API Reference   
21  - tab: help
22    layout: 
23      - section: Help center
24        contents: 
25          - page: Contact us
26              path: contact-us.mdx
27  - tab: github
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 docs.yml file.
  • Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").

Here’s an example of how a tabs implementation renders:

Tabs displayed in the sidebar (default)

Tabs placement

Tabs display in the left sidebar by default. To display them horizontally, set tabs-placement to header in your layout configuration.

docs.yml
1layout:
2  tabs-placement: header

Tab variants

Tab variants let you display different content variations within a single tab, and support RBAC. This is useful for showing different user types, implementation approaches, or experience levels without creating separate tabs.

When to use variants vs. tabs

Use variants for different perspectives on the same content area (REST vs. GraphQL, beginner vs. advanced). Use tabs for completely different documentation sections (guides vs. API Reference).

Basic usage

Define a tab with a variants property instead of a layout property. Each variant has its own title and layout. The example below shows two variants for the Help Center tab.

docs.yml
1tabs: 
2  api: 
3    display-name: API Reference
4    icon: puzzle
5  help:
6    display-name: Help center
7    icon: home
8  github:
9    display-name: GitHub
10    icon: brands github
11    href: https://github.com/fern-api/fern
12    
13navigation: 
14  - tab: api
15    layout: 
16      - section: Introduction
17        contents: 
18          - page: My page
19            path: my-page.mdx
20      - api: API Reference   
21  - tab: help
22    variants:
23      - title: For developers
24        layout:
25          - section: Getting started
26            contents:
27              - page: Quick start
28                path: ./pages/dev-quickstart.mdx
29      - title: For product managers
30        layout:
31          - section: Getting started
32            contents:
33              - page: Overview
34                path: ./pages/pm-overview.mdx
35  - 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 docs.yml file.
  • 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

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

feature-flag
string | object

Conditional display configuration