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: 概述
3     contents:
4       - page: 欢迎
5         path: ./pages/welcome.mdx
6       - page: 快速开始
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 中的链接

链接格式

使用 / 字符开始一个指向文档网站上另一个页面的相对 URL。这会路由到 docs.yml 文件中定义的 url，例如 example-docs.buildwithfern.com。例如，如果您想链接到 https://example-docs.buildwithfern.com/overview/introduction，您可以在 Markdown 中这样写链接：

相对链接示例

1 阅读[介绍](/learn/sdks/overview/introduction)。

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    | 数据     | 数据     |

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

Fern 组件

Fern 具有内置组件库，您可以在 Markdown 中使用。探索组件。