---
title: "Farm Docs 配置参考"
locale: "zh"
version: "current"
canonicalUrl: "https://farmfe.org/zh/docs/farm-docs/configuration"
publicationStatus: "prerelease"
---

<a id="farm-docs-配置参考"></a>
# Farm Docs 配置参考


**预发布参考。** 本页描述当前候选实现，不表示对应正式包已经发布。请先确认匹配的发行包，再按[使用指南](</zh/docs/farm-docs/usage>)运行。Rust 负责内容解析、配置校验和路由规划；Node 编排工作流，React 负责界面和 SSR。


<a id="两层配置"></a>
## 两层配置


` @farmfe/docs ` 的 ` defineDocsConfig(site, farm?) ` 接收站点 ` SiteConfig ` 和可选的 ` DocsFarmConfig `。站点字段不是 Farm 编译器字段；未知站点字段会被拒绝。类型来自 ` packages/docs/src/config.generated.ts `，包内 ` schema/input.json ` 描述 JSON 结构，Rust 还会验证 URL、真实文件路径和集合关系。


```ts
import { defineDocsConfig } from '@farmfe/docs';

export default defineDocsConfig({
  title: 'Example Docs',
  url: 'https://docs.example.com',
  docs: { collections: [{ id: 'main', dir: 'docs', routeBase: '/docs/' }] },
  theme: { navbar: [{ label: '指南', to: '/docs/' }] },
  build: { highlightRepresentation: 'static-html', targetConcurrency: 1 }
}, {
  compilation: { output: { path: 'build' } }
});
```


先创建 ` docs/index.md `。删除示例中的可选 ` build ` 后，引擎默认使用 ` jsx `，不会自动采用这里显式选择的静态 HTML。完整小项目见[主题定制](</zh/docs/farm-docs/theme-customization>)。


<a id="站点路由和文件"></a>
## 站点、路由和文件


| 字段 | 类型与默认值 | 约束和作用 |
| --- | --- | --- |
| ` schemaVersion ` | ` 1 ` | 当前只接受版本 1。 |
| ` title ` | 必填字符串 | 非空站点标题。 |
| ` url ` | 必填字符串 | HTTP(S) 源站 origin；不允许账号密码、非根路径、查询或片段。部署前缀放 ` basePath `。 |
| ` basePath ` | 字符串，` / ` | 绝对 URL 路径，规范化为末尾带 ` / `。 |
| ` trailingSlash ` | 默认 ` always `，可选 ` never ` | 公共路由规则；静态输出仍为 HTML，不要根据 URL 自行拼接磁盘文件名。 |
| ` canonicalOverrides ` | 数组，` [] ` | 精确的 ` { path, canonicalPath } ` 对，两者必须位于 ` basePath ` 内；不是通用重定向服务。 |
| ` staticDirs ` | 数组，` [] ` | ` { dir, routeBase?: '/' } `。必须是站点内专用现存目录；拒绝嵌套重叠、私有工具目录、静态源符号链接或 junction。 |
| ` linkExceptions ` | 数组，` [] ` | 精确的 ` { collection, id, target, code, reason } `。仅支持 ` DOCS_LINK_MISSING `、` DOCS_LINK_ANCHOR `；集合必须存在，原因不能为空。不是关闭链接校验的开关。 |


` basePath `、集合 ` routeBase ` 等 URL 路径必须以 ` / ` 开始，不允许目录穿越、重复斜杠、反斜杠、空白、` % `、查询或片段。` dir `、` sidebar `、` theme.components `、` theme.customCss ` 是站点根目录内、类型正确且已经存在的相对文件路径，不接受绝对路径或越界路径。静态目录会发布其允许的内容，不要放入密钥、缓存或其他私有资料。


<a id="文档和博客集合"></a>
## 文档和博客集合


` docs ` 默认 ` { defaultVersion: 'current', collections: [] } `。` blog ` 默认不存在，启用时同样包含 ` collections ` 数组。至少配置一个集合或 ` pages.dir `。


| 集合字段 | 类型与默认值 | 约束 |
| --- | --- | --- |
| ` id ` | 必填字符串 | 全局唯一集合标识；标识/版本标签使用 ASCII 字母、数字、` - `、` _ `、` . `，拒绝空值和 ` .. `。 |
| ` dir ` | 必填字符串 | 站点根目录内的现存内容目录。 |
| ` routeBase ` | 必填字符串 | 绝对 URL 路径，例如 ` /docs/ `；为公开变体分配不同路径。 |
| ` exclude ` | 字符串数组，` [] ` | 明确的相对源文件名，不是 glob 忽略语法。 |
| ` format ` | 默认 ` auto `；` markdown `、` mdx ` | ` auto ` 按 ` .md ` 区分 Markdown 和 MDX；显式设置作用于整个集合。 |
| ` locale ` | 默认 ` locales.default ` | 必须出现在 ` locales.items ` 中。 |
| ` version ` | 文档默认 ` docs.defaultVersion ` | 文档版本标签；博客集合不充当版本化文档集合。 |
| ` group ` | 可选字符串 | 将不同语言/版本中相同逻辑 ID 的文档关联起来。 |
| ` fallbackLocale ` | 可选字符串 | 需要显式 group、不同源语言，且源集合的类型/group/version 匹配；拒绝回退环。 |
| ` sidebar ` | 可选字符串 | 文档侧栏 JSON 路径；博客使用日期、标签和归档索引，不接受此字段。 |
| ` admonitionLabels ` | 对象 | 可覆盖 ` note `、` tip `、` info `、` warning `、` danger `、` caution `、` important `、` success `。默认分别为 ` note `、` tip `、` info `、` warning `、` danger `、` caution `、` important `、` success `；正文显式标题优先。 |
| ` blogListContent ` | 默认 ` links `，可选 ` full ` | 仅博客；` full ` 在列表复用已编译的原文章组件。 |
| ` blogLabels ` | 对象，仅博客 | 默认 ` title: 'Blog' `、` archive: 'Archive' `、` tags: 'Tags' `、` undated: 'Undated' `、` noPosts: 'No posts.' `，覆盖值必须为非空文本。 |


Frontmatter 可设置 ` id `、` slug `、` title `、` description `。未设置时 ID/slug 来自相对文件名，` index ` 对应所在目录；标题依次回退到第一个 H1 和 ID。Slug 是安全路由路径，不能是外部 URL。同集合重复逻辑 ID、输出路由冲突都会报错。博客作者、日期、标签等正文元数据请结合现有博客文档使用。


<a id="语言和版本"></a>
### 语言和版本


` locales ` 默认 ` { default: 'en', items: ['en'] } `。语言标签唯一，不接受 ` _ `、` . `；默认语言必须在列表内。` docs.defaultVersion ` 默认 ` current `；配置文档集合时，必须有集合提供该默认版本。


```json
{
  "locales": { "default": "en", "items": ["en", "zh"] },
  "docs": {
    "defaultVersion": "v2",
    "collections": [
      { "id": "en-v2", "group": "guide", "locale": "en", "version": "v2", "dir": "docs", "routeBase": "/docs/" },
      { "id": "zh-v2", "group": "guide", "locale": "zh", "version": "v2", "dir": "docs-zh", "routeBase": "/zh/docs/", "fallbackLocale": "en" }
    ]
  }
}
```


两个目录都要存在。翻译文件使用相同逻辑 ID；同 group 不能重复配置相同类型/语言/版本槽位。版本通过显式集合声明，不存在自动复制内容的版本命令。导航使用生成的 alternates/页面目标，不要字符串替换 URL 前缀。回退内容并不意味着已经完成翻译。


<a id="侧栏"></a>
## 侧栏


` sidebar ` 指向含必填 ` items `、可选 ` categories ` 复用字典的 JSON：


| ` type ` | 字段 |
| --- | --- |
| ` doc ` | ` id `，可选 ` label ` |
| ` category ` | ` label `、` items ` |
| ` categoryRef ` | 指向 ` categories ` 键的 ` id ` |
| ` link ` | ` label `、` href ` |
| ` autogenerated ` | 相对集合目录的 ` dir ` |


```json
{
  "items": [
    { "type": "doc", "id": "index", "label": "欢迎" },
    { "type": "category", "label": "指南", "items": [
      { "type": "autogenerated", "dir": "guides" }
    ] },
    { "type": "link", "label": "Farm", "href": "https://farmfe.org" }
  ]
}
```


该示例需要 ` docs/index.md ` 和真实的 ` docs/guides/ ` 文档子树。` categories ` 将引用 ID 映射到 ` { label, items } `。ID 是文档标识，不是 URL。缺失 ID、重复展示、无效或循环分类引用会被诊断。不配置文件时使用生成的导航。顶部栏目与侧栏过滤由 React 主题负责，` SiteConfig ` 没有 ` navbar.sections ` 字段。


<a id="独立页面"></a>
## 独立页面


` pages ` 默认不存在。` { dir: 'src/pages', format: 'auto' } ` 支持 Markdown/MDX 和 JS/JSX/TS/TSX 页面。脚本页面使用默认 React 组件及直接、静态的 ` export const metadata = { ... } `；不通过元数据重导出或动态表达式执行配置。默认语言位于 ` / `，其他语言位于 ` /<locale>/ `（在站点 base path 下），路径和冲突仍须校验。


```tsx
export const metadata = { title: '关于', slug: 'about' };
export default function About() {
  return <p>Documentation built with Farm.</p>;
}
```


脚本 ` metadata ` 支持 ` id `、` title `、` description `、` slug `、` layout `（` default ` 或 ` none `）及静态 ` titleByLocale ` 映射；语言必须已声明，标题非空。它们是页面元数据，不是任意浏览器表达式。


<a id="主题和导航"></a>
## 主题和导航


| 字段 | 默认值 | 作用 |
| --- | --- | --- |
| ` theme.logo ` | 无 | ` { src, alt?: '', href?: '/' } `；公共图片/链接，不是本地文件 URL。 |
| ` theme.navbar ` | ` [] ` | 平面的 ` { label, to } ` 列表；复杂菜单和图标放自定义 ` Navbar `。 |
| ` theme.footer ` | ` { links: [], copyright: null } ` | 链接也是 ` { label, to } `，copyright 为文本。 |
| ` theme.colorMode ` | ` system ` | ` system `、` light `、` dark `；可用存储中按 base path 保存用户选择。 |
| ` theme.customCss ` | ` [] ` | 站点内 CSS 文件，在框架样式之后导入。 |
| ` theme.components ` | 无 | 站点 React 主题模块，见[主题定制](</zh/docs/farm-docs/theme-customization>)。 |


JSON 不接受 Docusaurus ` themeConfig `、swizzle 路径、主题包名称选择器、任意导航对象或 JS 回调。组件组合才是扩展入口。公共导航/图片链接接受 HTTP(S) URL、站点绝对路径或非空片段，不是任意 URL scheme 白名单。


<a id="搜索"></a>
## 搜索


省略 ` search ` 表示未配置搜索。` { provider: 'none' } ` 不能带 ` options `。Algolia 必须提供三个非空公共字符串：


```ts
import type { SiteConfig } from '@farmfe/docs';

const search: NonNullable<SiteConfig['search']> = {
  provider: 'algolia',
  options: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_ONLY_KEY', indexName: 'YOUR_INDEX' }
};
```


这些配置会进入浏览器，禁止放管理密钥。配置不会自动创建账号、爬虫或 v2 索引，要验证实际 URL、语言/版本覆盖及允许域名。默认主题有 Algolia UI；站点可通过 React ` SearchProvider ` 接入 DocSearch，不存在 ` provider: 'docsearch' ` 这个枚举。


可选 ` search.openSearch ` 需要 ` pageId `、` shortName `、` description `，只可与 Algolia 配合，并要求真实的独立搜索页。` pageId ` 为逻辑页面 ID，不是 URL；短名称最多 16 字符、描述最多 1024 字符，文本需满足 XML 字符约束。这只生成发现元数据，不会自动创建页面的搜索界面。


<a id="seo404-与机器可读输出"></a>
## SEO、404 与机器可读输出


` seo.fallbackIndexing ` 默认 ` noindex `，显式 ` index ` 才允许搜索引擎索引回退页面。可选 ` seo.atom ` 为 ` { author, updated } `：作者非空，更新时间为带时区的 RFC3339 时间戳，年份 0001–9999；应使用明确的内容更新时间，不要随机采用每次构建时间。Canonical、alternates、站点地图和 feeds 依据真实路由计划生成，不是手工添加虚构路由。


` notFound.labels ` 为语言键到 ` { title?, description?, homeLabel? } ` 的映射，键必须对应已配置语言。默认英文为 ` Page not found `、` The requested page could not be found. `、` Return home `。布局变化通过 ` NotFound ` 槽位实现。


` ai ` 默认缺省、不导出。对象存在时 ` enabled ` 默认 ` true `，` publicationStatus ` 默认 ` prerelease `（或显式 ` stable `），` agentGuideUrl ` 可选。只有真实已发布内容才标 stable。符合条件的文档 Markdown、manifest、哈希和发现索引与 HTML 使用同一 snapshot；未知动态 MDX 明确失败，普通 TSX 页面不会生成伪 Markdown。输出协议和限制见 [AI 导出](</zh/docs/farm-docs/ai-exports>)。


<a id="构建和编译选项"></a>
## 构建和编译选项


| 字段 | 默认值 | 范围与作用 |
| --- | --- | --- |
| ` ssg.concurrency ` | ` 4 ` | 整数 1–32，Node SSR worker 并发。 |
| ` ssg.timeoutMs ` | ` 30000 ` | 整数 100–300000 毫秒，SSR 执行超时。 |
| ` build.highlightRepresentation ` | ` jsx ` | ` jsx ` 或 ` static-html `；后者为 Rust 生成且已转义的 token HTML，不是作者任意 raw HTML。 |
| ` build.targetConcurrency ` | ` 1 ` | ` 1 ` 或 ` 2 `，浏览器/服务端编译调度；提高前先确认内存。 |


这些限制互相独立，不改变文档路由数，也不关闭最终验证。本官网显式使用 ` static-html `；框架保留 ` jsx ` 默认值供检查 token 子节点的自定义 renderer。Rust 生成的代码颜色不需要浏览器语法高亮器。


第二个 ` farm ` 参数接受 Farm 编译设置、原生 Rust ` plugins ` 描述（字符串或 ` [字符串, 选项] `）及 ` snippets `。工作流与 ` docs:site ` 输入由 ` defineDocsConfig ` 管理，拒绝额外 workflow、` vitePlugins `、` jsPlugins ` 和 JS 编译插件对象。` compilation.output.path ` 指定站点内专用输出目录，默认 ` build `；不接受无关的现存非空目录作为旧 Docs 输出。


` snippets ` 支持 ` rendererModule ` 以及旧版 ` highlight ` 配色。建议使用下方统一的 ` site.code `，让围栏、显式组件和行内签名共用主题。该工作流的 representation 由站点 build 设置决定，不存在任意主题文件或 JavaScript 高亮回调配置。详见[主题定制](</zh/docs/farm-docs/theme-customization>)。


<a id="验证清单"></a>
## 验证清单


- 站点内所有目录、侧栏和主题文件真实存在且没有越界。
- 用实际内容构建并预览，检查语言/版本切换、404、资源、AI 与 SEO 公共输出。
- 自定义槽位后检查导航、搜索、移动端和键盘操作。
- 单独核验正式依赖及平台包：工作区构建、本地 tar 包安装、正式部署不是同一个验收结果。


<a id="统一代码配色预发布候选"></a>
## 统一代码配色（预发布候选）


` site.code ` 统一控制 Markdown 围栏、显式 ` CodeBlock `/` CommandTabs `，以及带 ` data-language ` 的静态行内签名；浏览器不执行高亮解析。可选 ` light `、` dark ` 支持 ` farm-light `、` farm-dark `、` vscode-light `、` vscode-dark `、` inspired-github `、` base16-ocean-dark `。未配置时保留 VS Code 默认值以兼容已有项目。


```ts
code: {
  light: 'farm-light',
  dark: 'farm-dark',
  tokens: {
    light: { function: '#497774', type: '#526b87' },
    dark: { function: '#9fbebc', type: '#a8b9ce' }
  }
}
```


` tokens.light `、` tokens.dark ` 可覆盖 ` foreground `、` keyword `、` control `、` function `、` type `、` class `、` variable `、` parameter `、` property `、` string `、` number `、` comment `、` tag `、` attribute `、` constant `、` punctuation `。颜色必须为 ` #RRGGBB `；未知名称和不安全颜色表达式会被原生配置校验拒绝。` type ` 覆盖类型族，包括内置类和命名空间；显式 ` class ` 配置进一步覆盖类作用域。语法能够区分时，` parameter ` 等细分类别优先于 ` variable ` 等宽泛类别。分类来自语法作用域，不提供语言服务器级语义分析，不猜测任意自定义符号。


显式 ` site.code ` 字段优先于旧的 ` snippets.highlight `；缺失字段回退到旧配置，再回退到原生默认值。自定义 token 按明暗模式和类别合并。配置只解析为一份，传给 prepare 和两个构建目标；配色变化进入内容缓存身份。` build.highlightRepresentation ` 仍单独控制 JSX/静态 HTML。背景、字体、边框和间距继续通过 ` theme.customCss ` 定制。