fern-api · devalog · May 5, 2026 · May 5, 2026
@@ -127,6 +127,7 @@ navigation:
       - page: 预览更改
       - page: 发布您的文档
       - page: 设置您的域名
+      - page: 多源文档
   - section: 自定义
     contents:
       - page: 公告横幅
@@ -185,6 +186,8 @@ navigation:
       - page: 设置 SEO 元数据
       - page: 配置 slug
       - page: 重定向
+      - page: 自定义 robots.txt
+        slug: robots-txt
   - section: 身份验证
     contents:
       - page: 概览
@@ -243,7 +246,6 @@ navigation:
       - page: Cursor
       - page: GitLab
       - page: Vale
-      - page: 查看 Markdown
       - page: 下载 OpenAPI 规范
         slug: openapi-spec
       - page: 下载 AsyncAPI 规范

@@ -0,0 +1,230 @@
+---
+title: 多源文档
+subtitle: 让多个团队从各自的仓库发布到同一个文档站点。
+description: 了解如何设置多源文档，让独立团队使用 Fern 在共享域名下发布，并保持品牌一致。
+sidebar-title: 多源文档
+---
+
+<Markdown src="/snippets/enterprise-plan.mdx" />
+
+多源文档将单个文档站点发布到一个自定义域名，并拆分为多个子路径。每个子路径来自各自的仓库，因此团队可以独立发布更新，同时由共享的[全局主题](/learn/docs/customization/global-themes)保持站点品牌一致。
+
+## 工作原理
+
+每个仓库在其 `docs.yml` 中声明共享域名下的唯一基础路径。从该仓库运行 `fern generate --docs` 仅更新它对应的子路径——其他子路径保持不变。
+
+要使其正常工作，需要三处配置：
+
+1. 在每个仓库 `docs.yml` 的实例上设置 **`multi-source: true`**，并使 `url` 和 `custom-domain` 以同一基础路径结尾。
+2. **[全局主题](/learn/docs/customization/global-themes)** 存放在专用的控制仓库中，并按名称从每个源仓库的 `docs.yml` 中引用。
+3. [Fern Dashboard](https://dashboard.buildwithfern.com) 中的**多仓库设置**控制该域名的默认路径以及搜索 / Ask AI 范围。
+
+例如，NVIDIA 的文档拆分到多个独立仓库中，每个仓库都发布到 `docs.nvidia.com` 上各自的子路径：
+
+- [docs.nvidia.com/nvcf](https://docs.nvidia.com/nvcf)
+- [docs.nvidia.com/brev](https://docs.nvidia.com/brev)
+- [docs.nvidia.com/aiperf](https://docs.nvidia.com/aiperf)
+- [docs.nvidia.com/nemo/curator](https://docs.nvidia.com/nemo/curator)
+
+每个子路径独立发布，但终端用户看到的是一个统一的站点。
+
+<Tip>
+  根域名 `docs.nvidia.com` 本身是 Fern 配置之外的独立站点——多源仅覆盖子路径。Fern 发布的着陆页是可选的（[示例](#example-a-live-multi-source-site)），任意数量的子路径组合都可以，包括只有两个。
+</Tip>
+
+## 设置多源文档
+
+<Steps>
+
+<Step title="为全局主题创建一个控制仓库">
+
+控制仓库是一个专门的 Fern 项目，用于存放您的全局主题——共享的 logo、颜色、字体、布局以及每个源仓库都会继承的站点级设置。在它的 `docs.yml` 中定义这些设置，然后导出并上传主题：
+
+```bash
+fern docs theme export
+fern docs theme upload --name my-org-theme
+```
+
+完整的设置指南以及主题控制的字段列表，请参阅[全局主题](/learn/docs/customization/global-themes)。
+
+</Step>
+
+<Step title="配置每个仓库">
+
+每个子路径都有自己的仓库（通常由不同团队拥有），与第一步中的控制仓库相互独立。在每个仓库的 `docs.yml` 中：
+
+- 通过名称引用全局主题：`global-theme: my-org-theme`。
+- 声明一个带 `multi-source: true` 的实例，并在共享域名上指定唯一的基础路径。该基础路径必须出现在 `url` 和 `custom-domain` 的末尾。
+
+例如，下面是同一共享域名上的两个仓库——一个在 `/product-a`，一个在 `/product-b`：
+
+<Tabs>
+<Tab title="Product A 仓库">
+```yaml docs.yml
+global-theme: my-org-theme
+
+instances:
+  - url: example.docs.buildwithfern.com/product-a
+    custom-domain: docs.example.com/product-a
+    multi-source: true
+```
+</Tab>
+<Tab title="Product B 仓库">
+```yaml docs.yml
+global-theme: my-org-theme
+
+instances:
+  - url: example.docs.buildwithfern.com/product-b
+    custom-domain: docs.example.com/product-b
+    multi-source: true
+```
+</Tab>
+</Tabs>
+
+</Step>
+
+<Step title="从每个仓库发布">
+
+每个仓库独立发布：
+
+```bash
+fern generate --docs
+```
+
+只更新该仓库拥有的子路径。其他子路径不受影响。
+
+</Step>
+
+<Step title="在 Dashboard 中配置域名设置">
+
+打开 [Fern Dashboard](https://dashboard.buildwithfern.com) 并选择您的顶级域名（例如 `docs.example.com`）——这些设置作用于整个域名，而不是单个子路径。在 **Settings** 标签页中，找到 **Multi-repo settings** 卡片。
+
+配置以下内容：
+
+- **Default path**（默认路径，*可选*）——设置用户访问域名根路径时被引导到哪里。当一个 Fern 管理的页面应作为根路径时设置此项。例如，如果您的主页位于 `/home` 子路径，则将默认路径设置为 `/home`，以便 `docs.example.com` 重定向到 `docs.example.com/home`。如果根路径不由 Fern 管理（如 NVIDIA 的 `docs.nvidia.com`，那是 Fern 配置之外的一个独立营销站点），请跳过此项。
+- **Search / Ask AI behavior**——控制 [Ask Fern](/learn/docs/ai-features/ask-fern/overview) 和搜索在子路径之间的工作方式。提供两种模式：
+  - **Hierarchical**（分层）——在 `/subpath` 下的搜索仅返回 `/subpath` 及其下的结果。当每个子路径覆盖不同的产品、用户期望范围受限的结果时使用。
+  - **Unified**（统一）——在任意子路径下的搜索都会返回所有子路径的结果。当各子路径属于同一产品的不同部分、用户希望获得跨范围的结果时使用。
+
+<Frame>
+![Fern Dashboard 中的多源设置](./images/multi-repo.png)
+</Frame>
+
+</Step>
+
+</Steps>
+
+## 示例：一个真实的多源站点
+
+<Tip>
+浏览实时站点 [multi-source.docs.buildwithfern.com](https://multi-source.docs.buildwithfern.com)，源代码位于 [fern-api/docs-examples/multi-source](https://github.com/fern-api/docs-examples/tree/main/multi-source)。
+</Tip>
+
+这是与 NVIDIA 设置不同的另一种形态：根路径是一个 Fern 管理的主页，下面是各团队的子路径。该示例在一个共享域名上使用六个独立的 `fern/` 项目——`/` 上的主页、带两个嵌套子项的 `/seeds` 团队中心，以及独立的 `/greenhouses` 和 `/nursery` 团队：
+
+<Files>
+  <Folder name="multi-source.docs.buildwithfern.com" defaultOpen>
+    <File name="/" comment="主页" />
+    <Folder name="/seeds" defaultOpen comment="Seeds 团队中心">
+      <File name="/seeds/sunflower" comment="Sunflower 子团队" />
+      <File name="/seeds/tomato" comment="Tomato 子团队" />
+    </Folder>
+    <File name="/greenhouses" comment="Greenhouses 团队" />
+    <File name="/nursery" comment="Nursery 团队" />
+  </Folder>
+</Files>
+
+<Note>
+单位是每个子路径一个 `fern/` 文件夹，而不是每个子路径一个仓库。每个子路径一个仓库（通常每个团队一个）的布局是最常见的形式，但在单个仓库中放置多个 `fern/` 文件夹也可以。
+</Note>
+
+这六个项目都共享 `global-theme: plantstore-theme` 并设置了 `multi-source: true`——它们仅在基础路径上有所不同。子路径本身可以包含嵌套子路径：`/seeds/sunflower` 和 `/seeds/tomato` 是位于 `/seeds` 之下的独立发布的项目。
+
+该示例使用 Fern 的预览域名（`*.docs.buildwithfern.com`），因此未设置 `custom-domain`。生产部署通常会为每个实例添加 `custom-domain: docs.example.com/...`。
+
+<Tabs>
+<Tab title="主页">
+```yaml homepage/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+  - url: multi-source.docs.buildwithfern.com
+    multi-source: true
+
+navigation:
+  - page: Home
+    path: ./pages/home.mdx
+```
+
+主页 `home.mdx` 可以使用卡片将用户引导到每个团队的文档：
+
+```jsx home.mdx
+<CardGroup>
+  <Card title="Seeds" icon="fa-regular fa-seedling" href="/seeds">
+    一个带嵌套子项的中心，子项位于 `/seeds/sunflower` 和 `/seeds/tomato`。
+  </Card>
+  <Card title="Greenhouses" icon="fa-regular fa-warehouse" href="/greenhouses">
+    气候控制和监测。
+  </Card>
+  <Card title="Nursery" icon="fa-regular fa-leaf" href="/nursery">
+    植物养护与繁殖。
+  </Card>
+</CardGroup>
+```
+</Tab>
+<Tab title="Seeds（中心）">
+```yaml seeds/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+  - url: multi-source.docs.buildwithfern.com/seeds
+    multi-source: true
+
+navigation:
+  - section: Getting started
+    contents:
+      - page: Overview
+        path: ./pages/overview.mdx
+```
+</Tab>
+<Tab title="Sunflower（嵌套）">
+```yaml seeds-sunflower/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+  - url: multi-source.docs.buildwithfern.com/seeds/sunflower
+    multi-source: true
+
+navigation:
+  - section: Getting started
+    contents:
+      - page: Overview
+        path: ./pages/overview.mdx
+```
+</Tab>
+<Tab title="Greenhouses">
+```yaml greenhouses/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+  - url: multi-source.docs.buildwithfern.com/greenhouses
+    multi-source: true
+
+navigation:
+  - section: Getting started
+    contents:
+      - page: Overview
+        path: ./pages/overview.mdx
+```
+</Tab>
+</Tabs>
+
+## 属性
+
+<ParamField path="instances.multi-source" type="boolean" required={false} default={false}>
+  设为 `true` 时，CLI 使用基础路径感知的发布方式，让多个仓库可以共存于同一个自定义域名下。启用此项时，`url` 和 `custom-domain` 必须共享相同的基础路径。
+</ParamField>
+
+<ParamField path="global-theme" type="string" required={false}>
+  要应用的[全局主题](/learn/docs/customization/global-themes)的名称。CLI 在发布时从 Fern 的注册表中获取该主题，并将其品牌字段合并到本地 `docs.yml` 中。完整字段列表请参阅[主题控制的内容](/learn/docs/customization/global-themes#what-the-theme-controls)。
+</ParamField>
@@ -0,0 +1,64 @@
+---
+title: 自定义 robots.txt
+description: 在文档站点根目录提供自定义 robots.txt，以控制搜索引擎和 AI 爬虫如何访问您的内容。
+sidebar-title: 自定义 robots.txt
+---
+
+默认情况下，Fern 在文档站点根目录提供自动生成的 `robots.txt`，允许所有爬虫并指向您的 `sitemap.xml`。使用 [`docs.yml` 中的 `agents.robots-txt` 键](/learn/docs/configuration/site-level-settings#agentsrobots-txt)以提供您自己的文件——这有助于选择允许或禁止特定的 AI 爬虫、限制敏感部分的访问，或通过 [Cloudflare 内容信号策略](https://blog.cloudflare.com/content-signals-policy/)表明偏好。
+
+`robots.txt` 仅是建议性的：遵守协议的爬虫会尊重您的 `Disallow` 和 `Allow` 指令，但忽略该协议的机器人仍可访问这些路径。对于必须保持私密的内容，请[使用身份验证](/learn/docs/authentication/overview)。
+
+<Note>
+  `robots.txt` 决定哪些爬虫可以访问您的站点以及您广播什么 AI 训练信号。它的搭档 [`llms.txt` 和 `llms-full.txt`](/learn/docs/ai-features/llms-txt) 决定 AI agent 在爬取后接收到的内容。
+</Note>
+
+## 配置
+
+<Steps>
+<Step title="在 `docs.yml` 中将 `agents.robots-txt` 指向您的文件">
+
+```yaml docs.yml
+agents:
+  robots-txt: ./robots.txt
+```
+
+路径相对于 `docs.yml`。
+
+</Step>
+
+<Step title="编写您的自定义 `robots.txt`">
+
+```txt robots.txt
+# 允许搜索引擎
+User-Agent: Googlebot
+Allow: /
+
+# 限制某个 AI 爬虫访问私有路径
+User-Agent: GPTBot
+Disallow: /private
+
+# 通过 Cloudflare 内容信号声明 AI 使用偏好
+Content-Signal: ai-train=yes, search=yes, ai-input=yes
+
+# 将爬虫指向您的 sitemap——Fern 默认的 robots.txt 包含此项，
+# 因此当您用自定义文件替换默认值时，请记得加回此行
+Sitemap: https://docs.example.com/sitemap.xml
+```
+<Tip>
+  请将命名机器人（如 `GPTBot`、`Googlebot`）放在任何通配符组之前——Fern 在提供文件时会追加自己的 `User-Agent: *` 块。
+</Tip>
+
+</Step>
+
+<Step title="Fern 提供您的文件">
+
+您的文件按原样在 `/robots.txt` 提供。Fern 在末尾追加一个受管理的块，禁止内部 API 路由：
+
+```txt
+# Fern 管理的路由——自动禁止
+User-Agent: *
+Disallow: /api/fern-docs/
+```
+
+</Step>
+</Steps>