fern-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fern docs authoring

Fern文档编写

Write and edit documentation on a Fern site.

SKILL.md

is the index: follow the principles below, then read the

references/

file that matches the task before writing. Don't work from this page alone when a reference exists.

Scope: this skill governs Fern docs content only — MDX pages, navigation,

docs.yml

and related config, snippets, changelog entries, custom components, and landing pages. It does not govern repo governance or tooling files that happen to live in the same repo, such as

CLAUDE.md

AGENTS.md

STYLE-GUIDE.md

, and contributor guides. Never apply the principles below — "one canonical home," "prefer editing over creating," consolidation — to those files. Leave them alone unless the user explicitly asks you to edit them.

在Fern站点上编写和编辑文档。

SKILL.md

是索引页：请遵循以下原则，然后在编写前阅读与任务匹配的

references/

目录下的文件。如果存在参考文档，不要仅依据本页面开展工作。

范围：本技能仅适用于Fern文档内容 —— 包括MDX页面、导航、

docs.yml

及相关配置、代码片段、更新日志条目、自定义组件和落地页。它不适用于同一仓库中的仓库治理或工具类文件，例如

CLAUDE.md

、

AGENTS.md

、

STYLE-GUIDE.md

以及贡献者指南。绝对不要将以下原则——“唯一规范归属”、“优先编辑而非创建”、内容整合——应用到这些文件上。除非用户明确要求编辑，否则不要改动它们。

Fern resources

Fern资源

Fern's configuration evolves. Look things up rather than guessing.

Docs: https://buildwithfern.com/learn/docs/getting-started/overview.md (append
```
.md
```
to any docs URL for clean markdown to fetch)
Page index: https://buildwithfern.com/learn/llms.txt
MCP server — connect your agent to Fern's live docs and query it for any syntax or behavior you're unsure of. The endpoint works with any MCP client; for Claude Code:
bash
```
claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server
```

Fern的配置在不断演进。请查阅官方资料，不要猜测。

文档： https://buildwithfern.com/learn/docs/getting-started/overview.md （可在任意文档URL后追加
```
.md
```
以获取纯净的Markdown内容）
页面索引： https://buildwithfern.com/learn/llms.txt
MCP服务器 —— 将你的Agent连接到Fern的实时文档，查询你不确定的任何语法或行为。该端点可与任何MCP客户端配合使用；对于Claude Code：
bash
```
claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server
```

Routing

任务路由

Task	Read
Writing or editing a changelog entry	`references/changelog.md`
Setting up a product switcher, adding a product, or refactoring nav into products	`references/products.md`
Moving, renaming, or deleting a page, or any edit that changes a published URL	`references/redirects.md`
Restricting pages or content by role (RBAC), or wiring docs into an auth method (password, SSO, JWT, OAuth)	`references/authentication.md`
Editing the same content across multiple pages, or adding generic/boilerplate content (e.g. "contact support")	`references/snippets.md`
Translating pages into another language, adding a language, or updating existing translations (multi-language Fern repo)	`references/translations.md`

任务	参考文档
编写或编辑更新日志条目	`references/changelog.md`
设置产品切换器、添加产品，或将导航重构为产品分类	`references/products.md`
移动、重命名或删除页面，或任何会更改已发布URL的编辑	`references/redirects.md`
按角色限制页面或内容（RBAC），或将文档接入身份验证方式（密码、SSO、JWT、OAuth）	`references/authentication.md`
跨多个页面编辑相同内容，或添加通用/模板化内容（例如“联系支持团队”）	`references/snippets.md`
将页面翻译为其他语言、添加语言，或更新现有翻译（多语言Fern仓库）	`references/translations.md`

Core principles

核心原则

Defer to the repo's own conventions. When a docs repo has an established pattern, voice, or structure — a
```
CLAUDE.md
```
, a style guide, or just the consistent practice of surrounding pages — follow it over the guidance here. This skill is the default, not an override.
Write what the reader needs to succeed — no more. Every sentence earns its place.
Prefer editing over creating. Search the repo for a page that already covers the topic and update it instead of adding a duplicate.
Make minimal, precise edits. Don't rewrite a page when a paragraph fix will do.
Push back when something seems wrong. Explain why rather than complying silently.
Ask when unclear. Don't fill gaps with assumptions.
Never fabricate. If you don't know a config key or behavior, look it up (MCP server or docs) or say so. Don't invent frontmatter or YAML fields.
Cross-reference. When you mention a concept documented elsewhere, link to it so readers can find their way.
Preserve URLs when they change. Any edit that moves, renames, or deletes a page — or changes a slug, section, or product — can change a published URL. When it does, set up redirects from the old path (see
```
references/redirects.md
```
) so inbound links and search rankings survive.

遵循仓库自身的约定。 当文档仓库已有既定的模式、语气或结构——比如有
```
CLAUDE.md
```
、风格指南，或者周边页面有一致的实践——请优先遵循这些约定，而非本指南。本技能是默认规则，而非覆盖性规则。
只写读者成功完成任务所需的内容——不多写一句。 每一句话都要有其存在的价值。
优先编辑而非创建。 在仓库中搜索是否已有涵盖该主题的页面，更新它而不是添加重复内容。
进行最小化的精准编辑。 如果修改一个段落就能解决问题，就不要重写整个页面。
当内容有问题时要提出异议。 要解释原因，不要默默服从。
不清楚时要询问。 不要用假设填补信息空白。
绝不编造。 如果你不知道某个配置项或行为，请查阅资料（MCP服务器或文档），或者如实说明。不要虚构frontmatter或YAML字段。
交叉引用。 当你提到在其他地方有文档说明的概念时，请添加链接，方便读者找到相关内容。
URL变更时要保留旧链接。 任何移动、重命名或删除页面的编辑——或者更改slug、章节、产品的操作——都可能更改已发布的URL。发生这种情况时，请设置从旧路径跳转的重定向（参见
```
references/redirects.md
```
），以保留入站链接和搜索排名。

链接

Internal links are URL paths derived from this repo's own
docs.yml
and page frontmatter — not file paths on disk or relative paths. Nearly every edit touches a link, so get this right every time.

A page URL is

<base-path>/<product-slug>/<rest>

Base path — the prefix in your docs URL (e.g.
```
/learn
```
,
```
/docs
```
; may be empty).
Product slug — the product's
```
slug
```
in
```
fern/docs.yml
```
. Omitted for a product with no
```
slug:
```
(such as a default single Home product).
<rest>
— found by step 1 or step 2 below.

To find

<rest>

Open the target page and check its frontmatter for
slug:
. A frontmatter slug is absolute within the product: it is
```
<rest>
```
on its own, and it replaces the entire section/folder hierarchy. The section's slug does not appear. Do not walk the navigation.
Otherwise, walk
docs.yml
within the product, from section through any folders to the page. Each level contributes one slug:
- Its explicit
```
slug:
```
  if set.
- Otherwise auto-derived from the display name: lowercased, spaces to hyphens, special characters stripped (so
```
v3 (Latest)
```
  becomes
```
v-3-latest
```
  ). Auto-derivation isn't always obvious — verify, don't assume.
- In folder-based navigation, a page's slug comes from its filename, not a display name (
```
quick-start.mdx
```
  to
```
quick-start
```
  ).
- Omit any level with
  skip-slug: true
  — it contributes no segment.

Example — page

./pages/ai/overview.mdx

under section "AI features", in product

docs

, base path

/learn

with frontmatter
```
slug: ai-ai
```
→
```
/learn/docs/ai-ai
```
(the
```
ai-features
```
section slug is dropped)
with no frontmatter slug →
```
/learn/docs/ai-features/overview
```
(section auto-slug
```
ai-features
```
+ page auto-slug
```
overview
```
)

Section slugs frequently differ from folder names, so never guess the URL from the directory layout. If you can't resolve a path from

docs.yml

and the page's frontmatter, say so rather than guessing.

Anchors append

#heading

, and only resolve for real

##

###

Markdown headings — not for JSX title props like

<Step title>

<Tab title>

<Accordion title>

, or

<Card title>

Not internal links (leave as-is): external

https://

URLs, image paths (

./images/...

), snippet includes (

<Markdown src="/snippets/..." />

), and same-page anchors (

#section

内部链接是基于本仓库自身的
docs.yml
和页面frontmatter生成的URL路径——而非磁盘上的文件路径或相对路径。几乎每一次编辑都会涉及链接，所以每次都要确保链接正确。

页面URL的格式为

<base-path>/<product-slug>/<rest>

：

基础路径（Base path） —— 文档URL的前缀（例如
```
/learn
```
、
```
/docs
```
；也可能为空）。
产品slug（Product slug） ——
```
fern/docs.yml
```
中产品的
```
slug
```
值。如果产品没有设置
```
slug:
```
（例如默认的单个首页产品），则省略该部分。
<rest>
—— 通过以下步骤1或步骤2得出。

要找到

<rest>

：

打开目标页面，检查其frontmatter中是否有
slug:
。 frontmatter中的slug在产品内是绝对路径：它本身就是
```
<rest>
```
，会替换整个章节/文件夹层级。章节的slug不会出现在路径中。不要通过导航层级拼接。
如果没有，则在产品内遍历
docs.yml
，从章节开始，经过所有文件夹到页面。每一层贡献一个slug：
- 如果设置了显式的
```
slug:
```
  ，则使用该值。
- 否则根据显示名称自动生成：转为小写，空格替换为连字符，特殊字符移除（因此
```
v3 (Latest)
```
  会变成
```
v-3-latest
```
  ）。自动生成的结果不一定直观——请验证，不要假设。
- 在基于文件夹的导航中，页面的slug来自其文件名，而非显示名称（
```
quick-start.mdx
```
  对应
```
quick-start
```
  ）。
- 省略所有设置了
  skip-slug: true
  的层级 —— 它们不会贡献路径段。

示例——产品

docs

下、章节“AI features”中的页面

./pages/ai/overview.mdx

，基础路径为

/learn

：

如果frontmatter为
```
slug: ai-ai
```
→ 路径为
```
/learn/docs/ai-ai
```
（
```
ai-features
```
章节的slug被省略）
如果没有frontmatter slug → 路径为
```
/learn/docs/ai-features/overview
```
（章节自动生成的slug
```
ai-features
```
+ 页面自动生成的slug
```
overview
```
）

章节的slug经常和文件夹名称不同，所以绝对不要根据目录结构猜测URL。如果你无法通过

docs.yml

和页面的frontmatter解析出路径，请如实说明，不要猜测。

锚点通过追加

#heading

的方式使用，且仅对真实的

##

###

Markdown标题生效——不适用于JSX的title属性，比如

<Step title>

、

<Tab title>

、

<Accordion title>

或

<Card title>

。

不属于内部链接的内容（保持原样）：外部

https://

URL、图片路径（

./images/...

）、代码片段引入（

<Markdown src="/snippets/..." />

）以及同页锚点（

#section

）。

Cross-referencing

交叉引用

When you document new functionality — a new page, or new behavior on an existing one — related pages usually need a pointer to it, or the new content is hard to find from where readers actually start. This applies to small edits too, not just new pages.

One canonical home. The full explanation lives on one page; every other page that touches the topic links to it instead of restating it. If you're copying more than a sentence or two onto another page, it belongs on the canonical page.
Find the targets. Grep the docs for the feature name and one or two related keywords, then read each hit and decide whether a pointer is warranted:
bash
```
grep -rln "<feature>\|<keyword>" fern --include="*.mdx"
```
Common targets: pages for behavior the feature affects, adjacent feature pages, and overview or landing pages.
Use the lightest form that works: an inline link inside an existing sentence, then a
```
<Note>
```
for a secondary aside, then a new
```
##
```
section, then a new page. Inline links and Notes add no maintenance surface; new pages and sections do.
Phrase inline links naturally — never "See [page]." Put the link on a noun phrase already in the sentence, not a tacked-on pointer sentence. Don't wrap a lone link in a
```
<Tip>
```
whose only job is to host it.
- Good: "Each request counts against your rate limit, which resets hourly."
- Bad: "Requests are rate limited. See the rate limits reference for details."
- Bad: a standalone
```
<Tip>
```
  containing only "For more, see rate limits."
Frame by function, not plumbing. Contrast what each feature does ("X decides A; Y decides B"), not that they share a config key or sit in the same directory. If the only thing linking two features is the same YAML key, it's not worth a cross-reference.

当你记录新功能时——无论是新页面，还是现有页面上的新行为——相关页面通常需要添加指向它的链接，否则读者从他们实际的起点出发很难找到新内容。这一点同样适用于小的编辑，不仅仅是新页面。

唯一规范归属。 完整的说明只放在一个页面上；所有其他涉及该主题的页面都链接到该页面，而不是重复陈述。如果你要把超过一两句的内容复制到另一个页面上，那这些内容应该放在规范页面中。
找到目标页面。 在文档中搜索功能名称和一两个相关关键词，然后阅读每个匹配结果，判断是否需要添加链接：
bash
```
grep -rln "<feature>\|<keyword>" fern --include="*.mdx"
```
常见的目标页面：受该功能影响的行为页面、相邻功能页面、概览页或落地页。
使用最轻量的可行形式： 先在现有句子中加入内联链接，然后是用于次要补充内容的
```
<Note>
```
，再然后是新增的
```
##
```
章节，最后是新增页面。内联链接和Note不会增加维护成本；新页面和新章节会。
内联链接的措辞要自然——绝对不要用“参见[页面]”。 把链接放在句子中已有的名词短语上，而不是额外加一句指向性的话。不要把单独的链接放在一个
```
<Tip>
```
里，而这个Tip的唯一作用就是承载这个链接。
- 好的例子：“每个请求都会占用你的速率限制额度，额度每小时重置一次。”
- 不好的例子：“请求有速率限制。参见速率限制参考了解详情。”
- 不好的例子：一个独立的
```
<Tip>
```
  里只有“更多信息请参见速率限制。”
按功能而非实现来组织表述。 要对比每个功能的作用（“X负责决定A；Y负责决定B”），而不是说它们共享某个配置键或者位于同一个目录下。如果两个功能唯一的关联是同一个YAML键，那就不值得做交叉引用。