Farm Docs 配置参考

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

两层配置

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

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。完整小项目见主题定制。

站点、路由和文件

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

文档和博客集合

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

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

语言和版本

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

{
  "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 前缀。回退内容并不意味着已经完成翻译。

侧栏

sidebar 指向含必填 items、可选 categories 复用字典的 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 字段。

独立页面

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

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 映射；语言必须已声明，标题非空。它们是页面元数据，不是任意浏览器表达式。

主题和导航

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

搜索

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

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 字符约束。这只生成发现元数据，不会自动创建页面的搜索界面。

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 导出。

构建和编译选项

这些限制互相独立，不改变文档路由数，也不关闭最终验证。本官网显式使用 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 高亮回调配置。详见主题定制。

验证清单

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

统一代码配色（预发布候选）

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

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 定制。