配置导航

选项卡和选项卡变体

将内容组织到可切换的选项卡中，支持可选变体

以 Markdown 格式查看

选项卡让您可以将文档的各个部分组织在一起，而选项卡变体允许您在单个选项卡中显示不同的内容视角。

选项卡

添加 tabs 来将部分组织在一起。下面的示例显示了 Help Center、API Reference 和指向 Github 的外部链接的选项卡。每个选项卡都有一个 display-name 和 icon。

在 navigation 部分中，每个选项卡引用必须包含 layout（用于内容）或 variants（用于选项卡变体）。带有 href 属性的选项卡是外部链接，不能包含 layout 或 variants。

docs.yml
1tabs: 
2  api: 
3    display-name: API Reference
4    icon: puzzle # Font Awesome 图标
5  help:
6    display-name: Help center
7    icon: ./assets/icons/help-icon.svg  # 自定义图像文件
8  github:
9    display-name: GitHub
10    icon: brands github # Font Awesome 图标
11    href: https://github.com/fern-api/fern
12    target: _blank # 链接在新标签页中打开
13    
14navigation: 
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
选项卡图标

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

以下是选项卡实现渲染效果的示例：

在侧边栏中显示的选项卡（默认）

选项卡位置和样式

选项卡默认显示在左侧边栏中。使用 theme.tabs 来控制位置、样式和对齐方式。

docs.yml
1theme:
2  tabs:
3    style: bubble        # "default"（下划线）或 "bubble"（药丸形状）
4    alignment: center    # "left" 或 "center"（center 仅适用于标题选项卡）
5    placement: header    # "header" 或 "sidebar"

选项卡属性

display-name
stringRequired

在选项卡标题中显示的名称

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

选项卡的自定义 URL slug

skip-slug
boolean

从 URL 中排除选项卡 slug

hidden
boolean

从导航中隐藏选项卡。详情请参见隐藏内容。

layout
list

选项卡内容的导航结构。除非选项卡使用 variants 或 href，否则为必需。

variants
list

用于显示不同内容视角的选项卡变体列表。用于替代 layout。

href
string

外部 URL。设置后，单击选项卡会重定向到此 URL。带有 href 的选项卡不能包含 layout 或 variants。

target
string

链接打开的位置。可选值为 _blank、_self、_parent 或 _top。

changelog
string

更新日志文件夹的路径，相对于设置它的 YAML 文件（例如 docs.yml）

viewers
string | list

选项卡的基于角色的访问控制

orphaned
boolean

当为 true 时，角色不从父元素继承

feature-flag
string | object

条件显示配置

选项卡变体

选项卡变体让您可以在单个选项卡中显示不同的内容变化，并支持 RBAC。这对于显示不同用户类型、实现方法或体验级别而不创建单独的选项卡非常有用。

何时使用变体与选项卡

对同一内容区域的不同视角使用变体（REST vs. GraphQL，初级 vs. 高级）。对完全不同的文档部分使用选项卡（指南 vs. API Reference）。

基本用法

定义一个带有 variants 属性而不是 layout 属性的选项卡。每个变体都有自己的标题和布局。下面的示例显示了 Help Center 选项卡的两个变体。

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

变体属性

title
stringRequired

变体的显示名称

layout
listRequired

使用与常规选项卡布局相同格式的导航结构

subtitle
string

显示在变体标题下方的文本

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

变体的自定义 URL slug

skip-slug
boolean

从 URL 中排除变体 slug

hidden
boolean

从导航中隐藏变体。详情请参见隐藏内容。

default
boolean

当为 true 时，此变体默认显示。如果未指定，则使用列表中的第一个变体。

viewers
string | list

变体的基于角色的访问控制

orphaned
boolean

当为 true 时，角色不从父元素继承

feature-flag
string | object

条件显示配置