Tabs and tab variants | Fern Documentation

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 display-name and icon.

In the navigation section, each tab reference must include either a layout (for content) or variants (for tab variants). Tabs with an href property are external links and must not include layout or variants.

docs.yml

1 tabs: 
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     target: _blank # Link opens in a new tab
13     
14 navigation: 
15   - tab: api
16     layout: 
17       - section: Introduction
18         contents: 
19           - page: My page
20             path: my-page.mdx
21       - api: API Reference   
22   - tab: help
23     layout: 
24       - section: Help center
25         contents: 
26           - page: Contact us
27             path: contact-us.mdx
28   - 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 placement and styling

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

docs.yml

1 layout:
2   tabs-placement: header

You can also change the visual style of tabs using the theme.tabs setting.

docs.yml

1 theme:
2   tabs: bubble

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 docs.yml file.
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

layout

list

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

variants

list

List of tab variants for displaying different content perspectives. 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 fern directory

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

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

1 tabs: 
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     
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     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

orphaned

boolean

When true, roles don’t inherit from parent elements

feature-flag

string | object

Conditional display configuration