fern-docs

Fern 文档编写

在 Fern 网站上编写和编辑文档。SKILL.md 是索引：遵循以下原则，然后在编写前阅读与任务相符的 references/ 文件。存在参考文件时，不要只依据此页面开展工作。

此技能仅适用于 Fern 文档内容——MDX 页面、导航、docs.yml 及相关配置、代码片段、更新日志条目、自定义组件和着陆页。它不适用于恰好位于同一仓库中的仓库治理或工具文件，例如 CLAUDE.md、AGENTS.md、STYLE-GUIDE.md 和贡献者指南。切勿将以下原则——“唯一规范位置”“优先编辑而非创建”、整合——用于这些文件。除非用户明确要求编辑，否则不要改动这些文件。

Fern 资源

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：

  claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server
  

任务指引

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

核心原则

• 遵循仓库自身的惯例。 如果文档仓库已形成既定模式、语气或结构——例如 CLAUDE.md、风格指南，或相邻页面一贯采用的做法——请优先遵循这些惯例，而非此处的指导。本技能是默认准则，不是覆盖规则。
• 只写读者成功所需的内容，不多写。 每句话都要有存在的理由。
• 优先编辑而非创建。 在仓库中搜索是否已有涵盖该主题的页面，并更新它，而不是另建重复页面。
• 修改应精准且尽量少。 如果修正一段文字即可解决，就不要重写整页。
• 发现问题时应提出异议。 说明原因，不要默默照办。
• 不清楚时就提问。 不要凭假设填补空白。
• 绝不捏造。 如果不确定配置键或行为，请查阅资料（MCP 服务或文档），或坦言不确定。不要杜撰 frontmatter 或 YAML 字段。
• 添加交叉引用。 提及其他地方有文档说明的概念时，请添加链接，方便读者查找。
• URL 变更时保留旧 URL。 任何移动、重命名或删除页面，或更改 slug、章节或产品的编辑，都可能改变已发布的 URL。如有变更，请从旧路径设置重定向（参见 references/redirects.md），以保留入站链接和搜索排名。

链接

内部链接是 URL 路径，根据此仓库自身的 docs.yml 和页面 frontmatter生成，而不是磁盘上的文件路径或相对路径。几乎每次编辑都会涉及链接，因此每次都要确保处理正确。

页面 URL 格式为 <base-path>/<product-slug>/<rest>：

• 基础路径 — 文档 URL 中的前缀（例如 /learn、/docs；也可能为空）。
• 产品 slug — fern/docs.yml 中产品的 slug。没有 slug: 的产品（例如默认的单一 Home 产品）省略此项。
• <rest> — 按照下方步骤 1 或步骤 2 查找。

查找 <rest>：

1. 打开目标页面，检查其 frontmatter 中是否有 slug:。 frontmatter 中的 slug 在产品内是绝对路径：它本身就是 <rest>，并会替换整个 section／文件夹层级。section 的 slug 不会出现在路径中。不要沿着导航层级查找。
2. 否则，在产品内沿着 docs.yml 从 section 开始，经过各级文件夹，找到页面。 每一级都会贡献一个 slug：
   • 如果设置了显式的 slug:，则使用它。
   • 否则，根据显示名称自动生成：转为小写，将空格替换为连字符，并去除特殊字符（因此 v3 (Latest) 会变成 v-3-latest）。自动生成的结果不总是一目了然——请核实，不要想当然。
   • 对于基于文件夹的导航，页面的 slug 来自其文件名，而不是显示名称（quick-start.mdx 对应 quick-start）。
   • 省略设置了 skip-slug: true 的层级——它不会贡献路径片段。

示例 — 页面 ./pages/ai/overview.mdx 位于 section「AI features」下，属于产品 docs，基础路径为 /learn：

• frontmatter 中有 slug: ai-ai → /learn/docs/ai-ai（省略 ai-features section slug）
• frontmatter 中没有 slug → /learn/docs/ai-features/overview（section 自动生成的 slug ai-features + 页面自动生成的 slug overview）

Section slug 经常与文件夹名称不同，因此绝不要根据目录结构猜测 URL。如果无法通过 docs.yml 和页面 frontmatter 确定路径，请说明无法确定，而不是猜测。

锚点以 #heading 追加，且只适用于实际的 ##／### Markdown 标题，不适用于 JSX 标题属性，例如 <Step title>、<Tab title>、<Accordion title> 或 <Card title>。

不属于内部链接（保持原样）：外部 https:// URL、图片路径（./images/...）、代码片段引入（<Markdown src="/snippets/..." />）和同页锚点（#section）。

交叉引用

记录新功能时——无论是新页面，还是现有页面上的新行为——通常都需要在相关页面添加指向它的链接，否则读者很难从实际开始阅读的位置找到新内容。即使只是小改动，也适用这一原则，并非只针对新页面。

• 唯一的权威页面。 完整说明只放在一个页面上；其他涉及该主题的页面都链接到该页面，而不是重复说明。如果你要在其他页面复制超过一两句话，就应该把内容放到权威页面上。

• 查找目标页面。 在文档中搜索功能名称和一两个相关关键词，然后阅读每个匹配结果，判断是否需要添加指向该功能的链接：

  grep -rln "<feature>\|<keyword>" fern --include="*.mdx"
  

  常见目标：功能会影响其行为的页面、相邻功能页面，以及概览页或入口页。

• 采用满足需求的最轻形式： 先考虑在现有句子中添加行内链接，其次是用 <Note> 补充说明，再其次是新增 ## 章节，最后才是新建页面。行内链接和 Note 不会增加维护负担；新页面和章节则会。

• 让行内链接读起来自然——绝不要写“请参阅[页面]”。 将链接放在句子中已有的名词短语上，不要另起一句生硬地添加链接。不要把单独的链接放进 <Tip>，让它只起到承载链接的作用。

  • 好：“每个请求都会计入你的速率限制，并且每小时重置一次。”
  • 不好：“请求受到速率限制。详情请参阅速率限制参考。”
  • 不好：单独的 <Tip> 中只有“如需了解详情，请参阅速率限制。”

• 按功能而非底层实现来说明关系。 对比各项功能的作用（“X 决定 A；Y 决定 B”），不要强调它们共用某个配置键或位于同一目录。如果两项功能之间唯一的联系是使用了同一个 YAML 键，就不值得添加交叉引用。