快速开始（文档） | Fern Documentation

使用 Fern 构建符合您品牌风格的美观开发者文档。Fern 支持使用 Markdown 编写页面，并从 OpenAPI 规范生成 API 参考文档。

使用引导界面

或者，按照本指南使用 CLI 开始使用 Fern。

如果您正在从现有文档迁移，Fern 会作为企业计划的一部分提供白手套迁移服务。请在此联系我们。

安装 CLI

安装 Fern CLI，以便您可以从命令行管理项目：

$ npm install -g fern-api

初始化您的文档

您文档的所有配置都位于 fern 文件夹中。通过使用初始模板或从头开始创建 fern 文件夹

使用初始模板

使用 fern-api/docs-starter 仓库作为您站点的模板：

导航到 fern-api/docs-starter 并点击 Use this template 按钮（位于页面右上角）。您必须登录 GitHub。
选择 create a new repository 选项。将其命名为 fern-docs。
克隆您新创建的仓库并在您喜欢的代码编辑器中打开（例如 Cursor、VS Code）。

您将看到一个包含 fern 文件夹的基本站点，该文件夹包含 API 定义、Markdown 页面和配置文件。查看实时示例以了解初始模板发布后的效果。您可以使用这些文件测试 Fern 的功能，或用您自己的文件替换它们。

fern

docs# Markdown 内容和资源

docs.yml# 定义导航、主题和托管详细信息

fern.config.json# 指定组织名称和 CLI 版本

generators.yml# 配置 SDK 生成

openapi.yaml# API 定义

README.md

从头开始

$ fern init --docs

您将在项目中看到一个新的 fern 文件夹，其中包含以下配置文件（但没有其他 Markdown 或 API 定义文件）：

fern

docs.yml# 定义导航、主题和托管详细信息

fern.config.json# 指定组织名称和 CLI 版本

配置您的组织

配置两个设置（这些值不必匹配）：

组织名称在 fern.config.json 中：在 Fern 系统中标识您的组织（包括 Fern Dashboard）
文档 URL在 docs.yml 中：确定您的文档发布位置

fern.config.json

1 {
2   "organization": "{{YOUR_ORGANIZATION}}",
3   "version": "5.7.5"
4 }

docs.yml

1 instances:
2   - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com

两个值都只能使用字母数字字符、连字符和下划线。

自定义您的文档

现在您有了一个基本的文档站点，您可以通过添加教程、生成 API 参考或微调品牌来自定义它。（或跳到预览和发布。）

添加内容

创建 Markdown（.mdx）文件并填写内容。阅读 Markdown 基础文档了解更多。

Fern 在 MDX 文件中支持 GitHub 风格的 Markdown (GFM)，无需插件。您还可以创建可重用片段来在多个页面间共享内容。

docs/pages/hello-world.mdx

1 ---
2 title: "页面标题"
3 description: "副标题（可选）"
4 ---
5 
6 Hello world!

在您的 docs.yml 文件中引用您的新页面。您可以在节中或作为独立页面引用 Markdown 页面。

docs.yml

1 navigation:
2   - page: Hello World
3     path: docs/pages/hello-world.mdx
4   - section: 概述
5     contents:
6       - page: 快速入门
7         path: docs/pages/getting-started.mdx

添加 API 参考

如果您克隆了初始模板，您已经有一个包含示例 API 定义的 openapi.yaml 文件。如果您从头开始，请添加您的 OpenAPI 规范：

$ fern init --openapi /path/to/openapi.yml

在 docs.yml 文件中引用您的 API 定义以生成 API 参考文档：

docs.yml

1 navigation:
2   - api: "API 参考"

为您的文档添加品牌

在 docs.yml 文件中配置您站点的所有品牌元素，如 logo、颜色和字体。

docs.yml

1 colors:
2   accent-primary:
3     dark: "#f0c193"
4     light: "#af5f1b"
5 
6 logo:
7   dark: docs/assets/logo-dark.svg
8   light: docs/assets/logo-light.svg
9   height: 40
10   href: https://buildwithfern.com/
11 
12 favicon: docs/assets/favicon.svg