Markdown 基础 | Fern Documentation

学习如何使用 Markdown 和 MDX 为你的文档添加内容，包括标题、组件和链接。

术语

在整个文档中，“Markdown”既指 Markdown 也指 MDX。MDX 是 Markdown 的一个版本，扩展了对 JSX 组件的支持。

添加 Markdown 或 MDX 页面

通过创建 Markdown (.md) 或 MDX (.mdx) 文件手动为你的文档添加页面。初次接触 Markdown？查看 Markdown Guide: Getting started。

将你的页面放在 fern/ 文件夹内，并在 docs.yml 文件的导航设置中链接到它们。

在下面的例子中，MDX 文件放在名为 pages/ 的文件夹内。

文件夹结构示例

$ fern/
$ ├─ fern.config.json
$ ├─ docs.yml
$ └─ pages/
$   ├─ welcome.mdx
$   └─ quickstart.mdx

docs.yml

1 navigation:
2   - section: Overview
3     contents:
4       - page: Welcome
5         path: ./pages/welcome.mdx
6       - page: Quickstart
7         path: ./pages/quickstart.mdx

页面标题

Fern 使用 docs.yml 中的 page 值自动为每个页面生成 <h1> 页面标题。例如，以下条目为此页面设置页面标题为 “Markdown basics”：

docs.yml

1 - page: Markdown basics
2   path: ./pages/component-library/writing-content/markdown-basics.mdx

由于 <h1> 是自动生成的，你应该用 <h2> 标题开始页面内容，而不是 <h1>。

Markdown 中的链接

链接格式

要链接到文档站点上的另一个页面，请写目标的已发布站点路径，以 / 开头。Fern 从你的docs.yml 和产品 YAML 文件中的 slugs 构建此路径，而不是从磁盘上的文件位置构建。要链接到另一个页面的标题，请在路径后追加 #anchor。

内页链接不支持文件相对路径如 ./ 和 ../ — 请使用已发布的站点路径代替。（文件相对路径仍然适用于图片和其他媒体以及 YAML 配置中的 path: 引用。）

内部链接示例

1 了解 [Fern SDK 如何工作](/learn/sdks/overview/how-it-works)。
2 
3 配置[侧边栏图标](/learn/docs/configuration/navigation#sidebar-icons)为你的导航添加视觉提示。

在版本化文档中，相同的路径会根据你写的是无版本形式（默认版本）还是有版本形式（例如 /learn/docs/v2/getting-started）而跳转到不同版本。对于单个页面内的内联版本特定内容，请使用 <If versions=…> 或 <Versions>。

验证链接

Fern 提供两种捕获损坏链接的方法。broken-links 规则 — 由 fern check 运行，包括在 fern docs dev 期间 — 验证每个内部链接是否符合从你的本地 YAML 构建的导航树。要检查已发布站点上的链接，请使用 fern docs link check 或 Fern Dashboard。

	`fern check` broken-links 规则	`fern docs link check`
检查内容	你的本地 YAML 导航树中的内部链接	你的实时部署站点上的所有链接
外部链接	不检查	检查
是否需要已发布站点	否	是
使用场景	在 CI 中，发布前	发布后，捕获实时 404 和损坏的外部 URL

API 链接语法

Use api: link syntax to link to API endpoints or API Reference sections in any Markdown content. Fern resolves these links at build time, so you don’t need to hardcode slugs.

Link to an endpoint

Use api:METHOD/path, where METHOD is an HTTP method (GET, POST, PUT, PATCH, DELETE) and /path is the endpoint path from your API definition. Path parameters use curly braces, such as api:GET/v2/payments/{paymentId}.

For projects with multiple APIs, prefix with the API name: api:API-NAME:METHOD/path.

Markdown

1 View the [Current user information](api:mcp-tools:GET/api/fern-docs/whoami) endpoint.

Link to the root of an API Reference section

Use api:apiName, where apiName matches the API name in your generators.yml file. This is useful when your project has multiple APIs and you want to link to the root landing page of a specific API Reference.

Markdown

1 Explore the [Plant Store API](api:plant-store) reference.

链接目标

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

了解更多关于链接和其他导航元素。

表格

使用标准 Markdown 语法和管道符（|）及连字符（-）创建表格：

1 | 列 1 | 列 2 | 列 3 |
2 |----------|----------|----------|
3 | 行 1    | 数据     | 数据     |
4 | 行 2    | 数据     | 数据     |

对于更高级的表格功能，如为较长数据集提供粘性标题，请参阅 Table 组件文档。

Fern 组件

Fern 有一个内置的组件库，你可以在 Markdown 中使用。探索这些组件。