版本管理 | Fern Documentation

版本管理在所有方案中均可使用：Hobby 最多 3 个版本，Team 最多 10 个版本，Enterprise 版本数量不限。如需更多信息，请联系 support@buildwithfern.com。

您的文档的每个版本都可以包含自己独特的选项卡、章节、页面和 API 参考。版本之间也可以共享内容。

要在单个页面内显示特定于版本的内容，请使用 <Versions> 组件。您可以独立使用站点级版本管理和 <Versions> 组件，也可以同时使用两者。

向文档添加版本

定义您的版本

在您的 fern 文件夹内创建一个 versions 文件夹。要指定每个版本的内容，请向 versions 文件夹添加一个 .yml 文件来定义该版本的导航结构。如果适用，请确保包含 navigation 和 tabs 属性。

$ fern/
$   ├─ fern.config.json
$   ├─ generators.yml
$   ├─ docs.yml
$   ├─ pages/
$     ├─ ...
$   └─ versions/
$     ├─ latest/pages/...
$     ├─ latest.yml
$     ├─ v2/pages/...
$     └─ v2.yml

特定于版本的 yml 文件：

1 navigation: 
2   - section: Introduction
3     contents: 
4       - page: My Page
5         path: ./latest/pages/my-page.mdx  # relative path to the file
6       - page: Shared Resource
7         path: ../shared-pages/shared-resource.mdx
8   - api: API Reference

您也可以有多个产品，一些有版本，一些没有版本。

添加您的版本配置

通过向 versions 列表添加项目并指定 display-name 和 path，在顶级 docs.yml 中定义版本。

docs.yml

1 versions: 
2   - display-name: Latest          # 在下拉菜单中显示
3     path: ./versions/latest.yml   # 版本文件的相对路径
4   - display-name: V2
5     path: ./versions/v2.yml

Default versions

Versions appear in a dropdown on your site in the order listed in docs.yml. The first version in your versions list is the default version and uses unversioned paths like example.com/getting-started. Other versions use versioned paths like example.com/v2/getting-started.

Fern automatically handles version routing by redirecting broken versioned links to the default version. Canonical URLs point to the unversioned path to consolidate SEO signals. To override this for version-specific pages, see SEO metadata.

指示可用性

You can optionally set the availability status for each version. Options are deprecated, ga, stable, and beta.

Version availability is distinct from section and page availability, with different options. If you want to set section and page availability, do so in your version-specific yml files.

docs.yml

1 versions: 
2   - display-name: Latest          
3     path: ./versions/latest.yml   
4     availability: beta
5   - display-name: v2
6     path: ./versions/v2.yml
7     availability: stable

从 docs.yml 中移除额外的导航

如果您的 docs.yml 文件包含 navigation 字段或 tabs 字段，请务必将其移除。这些字段现在应该属于特定于版本的 .yml 文件。

自定义版本行为

这些可选设置让您控制版本在 URL 中的显示方式以及谁可以访问它们。

更改版本别名

默认情况下，Fern 通过将 display-name 转换为小写并将空格替换为连字符来生成 URL 别名。例如，display-name: v3 (Deprecated) 的版本在 URL 路径中会得到别名 v-3-deprecated。

要自定义版本的 URL 别名，请使用 slug 属性：

docs.yml

1 versions:
2   - display-name: v4 (Latest)
3     path: ./versions/latest.yml
4     availability: stable
5   - display-name: v3 (Deprecated)
6     path: ./versions/v3.yml
7     slug: v3
8     availability: deprecated
9   - display-name: v2
10     path: ./versions/v2.yml
11     slug: v2
12     availability: deprecated

在这个例子中，设置 slug: v3 会产生像 /docs/v3/getting-started 这样的 URL。

添加实例受众

通过为版本打上受众标签，控制哪些版本显示在每个文档实例中。这使得可以为不同的用户群体（例如，内部开发者、beta 测试人员、公共客户）创建单独的站点。

内容基于受众标签进行过滤：

匹配：具有与实例受众匹配的受众的内容会被包含
不匹配：具有不匹配受众的内容会被排除
无受众：没有受众标签的内容默认被包含

在 docs.yml 中为实例和版本定义受众：

docs.yml

1 instances:
2   - url: internal.docs.buildwithfern.com
3     audiences:
4       - internal # 仅显示标记为 'internal' 的内容
5   - url: public.docs.buildwithfern.com
6     audiences:
7       - public # 仅显示标记为 'public' 的内容
8 versions:
9   - display-name: v3
10     path: ./versions/v3.yml
11     audiences:
12       - public # 此版本仅显示在公共实例上
13   - display-name: v2 (Internal)
14     path: ./versions/v2.yml
15     audiences:
16       - internal # 此版本仅显示在内部实例上

从导航中隐藏版本

您可以通过设置 hidden: true 从导航、搜索和索引中隐藏特定版本，同时保持它们可以通过直接 URL 访问。这对于弃用先前版本或维护仅限内部使用的版本而不完全删除它们很有用。

docs.yml

1 versions:
2   - display-name: v3
3     path: ./versions/v3.yml
4   - display-name: v2
5     path: ./versions/v2.yml
6   - display-name: v1 (Legacy)
7     path: ./versions/v1.yml
8     hidden: true

默认版本（versions 列表中的第一个版本）不能被隐藏。

有条件地渲染内容

要根据当前版本在页面内有条件地渲染内容，请使用 <If> 组件。

Markdown

1 <If versions={["v2"]}>
2   此内容仅在版本 v2 中显示。
3 </If>

自定义版本样式

使用自定义 CSS 来设置版本选择器的样式以匹配您的品牌。

选择器样式

您可以通过定位 fern-version-selector CSS 类直接自定义版本选择器的外观。

Adjusting positioning: Use transform: translateY(Npx) to adjust the vertical positioning of the selectors. This ensures that the selectors match the line height of your logo for better visual alignment.

Enhancing visual prominence: You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site’s design aesthetic.

1 .fern-version-selector {
2   transform: translateY(1px);
3   border-radius: 1000px;
4   border: 1px solid var(--border);
5 }

下拉菜单样式

版本选择器的下拉菜单可以使用 fern-version-selector-radio-group CSS 类进行自定义。