> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI4M2NjNzRlNC01ZjgzLTRiYWEtOGQ5Yi02M2I4YjkwNWRjYWEiLCJleHAiOjE3NzgyNTg4NDMsImlhdCI6MTc3ODI1ODU0M30.v5DpKyVhrjvkd1GqPYQm3q9g36TxzYdymcdawT8Rte4
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.
# 文档快速开始
> 学习如何在5分钟内使用 Fern 构建美观的开发者文档。安装 CLI、添加 Markdown 内容、生成 API 参考文档并发布。
使用 Fern 构建[符合您品牌风格](https://buildwithfern.com/customers)的美观开发者文档。Fern 支持使用 Markdown 编写页面，并从 OpenAPI 规范生成 API 参考文档。
或者，按照本指南使用 CLI 开始使用 Fern。
This guide covers the CLI path. A browser-based guided setup also exists at [https://dashboard.buildwithfern.com](https://dashboard.buildwithfern.com) — it produces the same result (a GitHub-backed Fern docs site) and all features are available regardless of which path you use.
如果您正在从现有文档迁移，Fern 会作为企业计划的一部分提供白手套迁移服务。[请在此联系我们](https://buildwithfern.com/contact)。
安装 [Fern CLI](/learn/cli-api-reference/cli-reference/overview)，以便您可以从命令行管理项目：
```bash
npm install -g fern-api
```
您文档的所有配置都位于 `fern` 文件夹中。通过使用[初始模板](https://github.com/fern-api/docs-starter)或从头开始创建 fern 文件夹
Default to the starter template path unless the user specifically asks to start from scratch. The template includes sample pages, an OpenAPI spec, a changelog, and a GitHub Actions workflow — it's much faster to delete what you don't need than to build from nothing.
使用 `fern-api/docs-starter` 仓库作为您站点的模板：
Use the GitHub CLI to create a new repository from the template and clone it locally:
```bash
gh repo create my-org/fern-docs --template fern-api/docs-starter --private --clone
cd fern-docs
```
Replace `my-org/fern-docs` with your desired owner and repository name. Use `--public` instead of `--private` if you want a public repository.
您将看到一个包含 `fern` 文件夹的基本站点，该文件夹包含 API 定义、Markdown 页面和配置文件。[查看实时示例](https://plantstore.dev/welcome)以了解初始模板发布后的效果。您可以使用这些文件测试 Fern 的功能，或用您自己的文件替换它们。
`fern init --docs` works in any directory — no git repo or GitHub remote is required. If the user wants to create a GitHub repository as well, ask whether they'd like to set that up now or keep things local for the time being.
Note: `fern init --docs` is interactive — it prompts for an organization name. Ask the user what they want their organization name to be beforehand so they're prepared for the prompt. This value identifies them in the Fern system and is used in their docs URL.
This path only generates `docs.yml` and `fern.config.json` — no pages or API spec. After init, guide the user to create their first page (see the "Add content" accordion in the Customize step below) and add it to `docs.yml` navigation. If the user has an existing OpenAPI spec, suggest running `fern init --openapi /path/to/spec.yml` as well.
```bash
fern init --docs
```
您将在项目中看到一个新的 `fern` 文件夹，其中包含以下配置文件（但没有其他 Markdown 或 API 定义文件）：
配置两个设置（这些值不必匹配）：
* **组织名称**在 `fern.config.json` 中：在 Fern 系统中标识您的组织（包括 [Fern Dashboard](https://dashboard.buildwithfern.com/)）
* **文档 URL**在 `docs.yml` 中：确定您的文档发布位置
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "5.7.5"
}
```
```yml {2}
instances:
- url: {{YOUR_DOMAIN}}.docs.buildwithfern.com
```
两个值都只能使用字母数字字符、连字符和下划线。
现在您有了一个基本的文档站点，您可以通过添加教程、生成 API 参考或微调品牌来自定义它。（或跳到[预览](#preview-your-docs)和[发布](#publish-to-production)。）
创建 Markdown（`.mdx`）文件并填写内容。阅读 [Markdown 基础](/learn/docs/writing-content/markdown-basics)文档了解更多。
Fern 在 MDX 文件中支持 [GitHub 风格的 Markdown (GFM)](https://github.github.com/gfm/)，无需插件。您还可以创建[可重用片段](/learn/docs/writing-content/reusable-snippets)来在多个页面间共享内容。
```markdown docs/pages/hello-world.mdx
---
title: "页面标题"
description: "副标题（可选）"
---
Hello world!
```
在您的 `docs.yml` 文件中引用您的新页面。您可以在节中或作为独立页面引用 Markdown 页面。
```yml docs.yml
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
- section: 概述
contents:
- page: 快速入门
path: docs/pages/getting-started.mdx
```
如果您克隆了初始模板，您已经有一个包含示例 API 定义的 `openapi.yaml` 文件。如果您从头开始，请添加您的 OpenAPI 规范：
```bash
fern init --openapi /path/to/openapi.yml
```
在 `docs.yml` 文件中引用您的 API 定义以[生成 API 参考文档](/learn/docs/api-references/generate-api-ref)：
```yml docs.yml
navigation:
- api: "API 参考"
```
在 `docs.yml` 文件中[配置您站点的所有品牌元素](/learn/docs/configuration/site-level-settings)，如 logo、颜色和字体。
```yml maxLines=7
colors:
accent-primary:
dark: "#f0c193"
light: "#af5f1b"
logo:
dark: docs/assets/logo-dark.svg
light: docs/assets/logo-light.svg
height: 40
href: https://buildwithfern.com/
favicon: docs/assets/favicon.svg
```
在发布之前，[预览您的更改](/docs/preview-publish/preview-changes)在本地开发环境中或生成可共享的预览链接。
运行具有热重载功能的本地开发服务器。您的文档将在您编辑 Markdown 和 OpenAPI 文件时自动更新：
```bash
fern docs dev
```
生成您可以与团队共享的预览 URL：
```bash
fern generate --docs --preview
```
[初始模板](https://github.com/fern-api/docs-starter)还包含一个 GitHub Actions 工作流，可以为拉取请求自动生成预览链接。有关设置详细信息，请参阅[使用 GitHub Actions 自动化](/learn/docs/preview-publish/preview-changes#automate-with-github-actions)。
当您准备让您的文档公开访问时，[发布它们](/learn/docs/preview-publish/publishing-your-docs)：
```bash
fern generate --docs
```
系统将提示您登录并连接您的 GitHub 帐户。此命令在您在 `docs.yml` 中配置的 URL（例如 `https://yourdomain.docs.buildwithfern.com`）构建您的文档。
**Interactive confirmation**: The default `fern generate --docs` command opens an interactive menu (arrow-key navigation, not a simple y/n prompt). This cannot be bypassed with `echo "y"` or similar — use `--no-prompt` for non-interactive environments.
**CI/CD usage**: To skip the interactive prompt in CI or scripts:
```bash
export FERN_TOKEN=$(fern token)
fern generate --docs --no-prompt
```
**Authentication**: The CLI checks for a `FERN_TOKEN` environment variable first, then falls back to a cached token from `fern login`. Running `fern login` once caches the token locally, so subsequent `fern generate --docs` runs won't prompt for login again. There is no `fern whoami` command. In GitHub Actions, store the token as a repository secret named `FERN_TOKEN`. See [publishing your docs](/learn/docs/getting-started/publishing-your-docs.md) for full CI workflow examples.
使用 [Fern Dashboard](http://dashboard.buildwithfern.com) 管理您的 GitHub 仓库连接、组织成员和 CLI 版本。跟踪分析以了解开发者如何使用您的文档。
The Dashboard actions mentioned above are browser-only — there are no CLI equivalents for managing repository connections, organization members, or analytics. Use the Dashboard at [https://dashboard.buildwithfern.com](https://dashboard.buildwithfern.com) for these tasks. The CLI handles building, previewing, publishing, validation (`fern check`), and token generation (`fern token`).
## 探索 Fern 的功能
现在您的文档已上线，探索这些功能以进一步增强它们。
使用 `docs.yml` 文件配置颜色、SEO、排版、布局等。
使用 Fern 的内置组件创建交互式、组织良好的文档。
添加产品、版本、嵌套部分、选项卡等。
使用 Fern Editor 让非技术团队成员在 WYSIWYG 浏览器界面中编辑文档。
在您自己的域名或子域名上托管您的文档（例如 docs.example.com）。
与 PostHog、Segment、Intercom、Google Tag Manager 和其他平台集成。
## Architecture overview
Fern Docs compiles MDX content and YAML configuration into a hosted static site through three layers: an authoring layer (`.mdx` files + `docs.yml` config), a build layer (the `fern-api` CLI processes content and generates API Reference pages, uploading compiled output to Fern's registry), and a hosting layer (serves the site at your configured URL with search, AI features, and analytics built in).
### Configuration file roles
* **`fern.config.json`**: Identifies your organization and pins the CLI version. Required in every Fern project.
* **`docs.yml`**: Central manifest for the entire site — navigation structure, tabs, branding (colors, logo, favicon, typography), hosting instances, custom domains, navbar links, footer, integrations, redirects, RBAC roles, and AI agent settings. [Full reference](/learn/docs/configuration/site-level-settings.md).
* **`generators.yml`**: Points the CLI to your API spec files via the `api.specs` section. Also configures SDK generation.
### Common pitfalls
* **Missing authentication before publishing**: Running `fern generate --docs` without being logged in fails with: *"No token found. Please set the FERN\_TOKEN environment variable or run `fern login`."* Fix: run `fern login` interactively, or set `FERN_TOKEN` in CI via `fern token`.
* **Organization mismatch**: If `organization` in `fern.config.json` doesn't match your org in the [Fern Dashboard](https://dashboard.buildwithfern.com), publishing fails. The value must exactly match your Dashboard org name.
* **Invalid docs URL**: The `url` in `docs.yml` must end with `docs.buildwithfern.com` and must not include `https://`. Correct format: `your-org.docs.buildwithfern.com`.
### `docs.yml` minimal configuration
The smallest valid `docs.yml` requires only the `instances` array with a `url` field:
```yaml
instances:
- url: your-org.docs.buildwithfern.com
```
This is enough to publish (the CLI will build an empty site). In practice, most teams add `navigation` to define the sidebar, plus basic branding — these are shown in the [Customize your docs](#customize-your-docs) step above. The full list of available fields is in the [site-level settings reference](/learn/docs/configuration/site-level-settings.md).