章节、页面和文件夹 | Fern Documentation

docs.yml 中的 navigation 键定义了您的侧边栏结构。通过组合章节、页面和文件夹来构建它。

API 参考章节

使用特殊的 api 键创建一个生成的 API 参考章节。

docs.yml

1 navigation:
2   - section: 介绍
3     contents:
4       - page: 我的页面
5         path: ./pages/my-page.mdx
6   - api: API Reference

添加章节

章节在左侧导航栏中组织您的文档。每个章节都有一个名称和一个 contents 列表，可以包括页面、文件夹或嵌套章节。

docs.yml

1 navigation:
2   - section: 介绍
3     contents:
4       - page: 我的页面
5         path: ./pages/my-page.mdx
6       - page: 另一个页面
7         path: ./pages/another-page.mdx

章节可以嵌套以创建多级导航层次结构。

docs.yml

1 navigation:
2   - section: 学习
3     contents:
4       - section: 核心概念
5         contents:
6           - page: 嵌入
7             path: ./docs/pages/embeddings.mdx
8           - page: 提示工程
9             path: ./docs/pages/prompts.mdx
10       - section: 生成
11         contents:
12           - page: Command nightly
13             path: ./docs/pages/command.mdx
14           - page: 似然度
15             path: ./docs/pages/likelihood.mdx

要为章节添加概述页面，添加一个指向 .mdx 文件的 path 属性。

带有概述页面的章节

1 navigation:
2   - section: 指南
3     path: ./pages/guide-overview.mdx
4     contents:
5       - page: 简单指南
6         path: ./pages/guides/simple.mdx
7       - page: 复杂指南
8         path: ./pages/guides/complex.mdx

添加页面

创建一个 .md 或 .mdx 文件，然后在章节的 contents 中添加一个包含文件路径的 page 条目。

docs.yml

1 navigation:
2   - section: 介绍
3     contents:
4       - page: 我的页面
5         path: ./pages/my-page.mdx
6       - page: 另一个页面
7         path: ./pages/another-page.mdx

添加文件夹

添加一个指向目录的 folder 条目。Fern 会自动发现所有 .md 和 .mdx 文件并将它们添加到导航中。

pages

guides

index.mdx# 成为章节概述页面

quickstart.mdx

advanced

index.mdx# 成为嵌套章节概述

auth.mdx

docs.yml

1 navigation:
2   - section: 介绍
3     contents:
4       - folder: ./pages/guides
5         title: 指南 # 可选，默认为文件夹名称

对于文件夹中的页面，Fern 自动：

将文件名转换为标题和 URL 别名
从子目录创建嵌套章节
按字母顺序排序页面
使用 index.mdx 或 index.md 文件作为章节概述页面（不区分大小写）

文件夹配置选项

使用这些选项自定义文件夹行为：

docs.yml

1 navigation:
2   - folder: ./pages/guides
3     title: 指南                     # 在侧边栏中显示的名称
4     slug: user-guides              # 自定义 URL 路径
5     title-source: frontmatter      # 使用 frontmatter 标题

title

string

为此文件夹章节显示的标题。如果未提供，则使用文件夹名称。

title-source

'filename' | 'frontmatter'Defaults to filename

确定文件夹内的页面和章节标题如何生成。默认情况下（filename），标题从文件名生成。设置为 frontmatter 以使用每个文件 frontmatter 中的 title 字段（如果未设置则回退到文件名）。此单个文件夹设置会覆盖全局的 settings.folder-title-source 值。

slug

string

覆盖文件夹自动生成的 URL 别名。

skip-slug

booleanDefaults to false

从 URL 路径中省略文件夹，因此页面显示在父级别。

position

number

在页面 frontmatter 中设置以控制文件夹内的排序。具有 position 的页面首先出现（按数字排序），然后是其余的按字母顺序排列。

页面 frontmatter

1 ---
2 title: 快速开始
3 position: 1
4 ---

隐藏内容

要隐藏页面、文件夹或章节，添加 hidden: true。隐藏的内容（包括文件夹内的所有页面）仍可通过直接 URL 访问，但会从搜索中排除且不会被索引。

docs.yml

1 navigation:
2   - section: 介绍
3     contents:
4       - page: 我的页面
5         path: ./pages/my-page.mdx
6       - page: 隐藏页面
7         hidden: true
8         path: ./pages/my-hidden-page.mdx
9       - folder: .pages/features
10         title: 隐藏文件夹
11         hidden: true
12   - section: 隐藏章节
13     hidden: true
14     contents:
15       - page: 另一个隐藏页面
16         path: ./pages/also-hidden.mdx

可用性

在页面、章节或文件夹上设置可用性徽章。选项有：stable、generally-available、in-development、pre-release、deprecated 或 beta。

页面从其父章节或文件夹继承可用性，除非被以下覆盖：

docs.yml 中的单个页面 availability 设置（如下所示）
页面 frontmatter 可用性，它优先于所有 docs.yml 可用性设置

docs.yml

1 navigation:
2   - section: 开发者资源
3     availability: generally-available
4     contents:
5       - page: 代码示例 # 继承 generally-available
6         path: ./pages/code-examples.mdx
7       - folder: ./pages/cli-tools # 继承 generally-available
8         title: CLI 工具
9       - page: 测试框架
10         path: ./pages/testing-framework.mdx
11         availability: beta # 覆盖章节级可用性
12       - folder: ./pages/performance-monitoring
13         title: 性能监控
14         availability: in-development # 覆盖章节级可用性

如果您有不同版本的文档，章节、文件夹和页面可用性应在定义每个版本导航结构的 .yml 文件中设置。

折叠的章节或文件夹

默认情况下，章节和文件夹是展开的且不可折叠。使用 collapsed 属性控制它们在页面加载时在侧边栏中的显示方式。

值	行为
`true`	加载时折叠。用户可以展开它。
`open-by-default`	加载时展开，但可折叠。章节显示一个切换按钮，用户可以折叠它。

带有折叠章节的示例配置

1 navigation:
2   - section: 快速入门 # 展开，不可折叠（默认）
3     contents:
4       - page: 介绍
5         path: ./pages/intro.mdx
6       - folder: ./pages/features
7         title: 功能特性
8         collapsed: true # 文件夹开始时折叠
9   - section: 高级主题
10     collapsed: true # 章节开始时折叠
11     contents:
12       - page: 自定义 CSS
13         path: ./pages/advanced/css.mdx
14       - page: 分析
15         path: ./pages/advanced/analytics.mdx
16   - section: API 指南
17     collapsed: open-by-default # 章节开始时展开，但用户可以折叠
18     contents:
19       - page: 身份验证
20         path: ./pages/api/auth.mdx
21       - page: 分页
22         path: ./pages/api/pagination.mdx

侧边栏图标

使用 icon 键为章节、页面和文件夹添加图标。

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

带有不同图标文件的示例配置

1 navigation:
2   - section: 首页
3     icon: fa-regular fa-home  # Font Awesome 图标
4     contents:
5       - page: 介绍
6         icon: ./assets/icons/intro-icon.svg  # 自定义图像文件
7         path: ./pages/intro.mdx
8       - folder: .pages/features
9         title: 自定义功能
10         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>"  # 内联 SVG
11         path: ./pages/custom.mdx
12   - api: API Reference
13     icon: fa-regular fa-puzzle

链接

您可以通过以下配置在侧边栏导航中添加指向外部页面的链接：

docs.yml

1 navigation:
2   - section: 首页
3     contents:
4       - page: 介绍
5         path: ./intro.mdx
6       - link: 我们的 YouTube 频道
7         href: https://www.youtube.com/

链接目标

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

1 navigation:
2   - section: Home
3     contents:
4       - page: Introduction
5         path: ./intro.mdx
6       - link: Our YouTube channel
7         href: https://www.youtube.com/
8         target: _blank