Clarify 配置参考

推荐使用 clarify.ts 作为项目配置文件。clarify.js 和 clarify.json 也受支持，加载优先级为：

clarify.ts > clarify.js > clarify.json

clarify.json 适合不需要插件函数的简单项目；需要插件或更强类型提示时使用 clarify.ts。

配置分层

Clarify 将项目配置和运行参数明确分离：

层级	受众	入口	职责
项目配置	内容作者、技术写作者、扩展开发者	`clarify.ts/js/json`	站点展示、多语言、导航、插件
CLI 参数	开发者、构建环境	`clarify dev/build`	项目根目录、内容目录、输出目录、端口

内容创作者主要维护 clarify.ts 和 source；开发者通过 CLI 参数控制运行方式。

完整配置类型

import { defineConfig } from '@clarify-labs/cli'

export default defineConfig({
  title: 'Clarify 文档',
  description: 'Clarify 官方文档 — 开源文档发布工具',
  logo: {
    light: '/logo-light.svg',
    dark: '/logo-dark.svg',
  },
  favicon: '/favicon.ico',
  routePrefix: '/docs/',
  theme: {
    preset: 'default',
    tokens: {
      colors: {
        primary: '#00D492',
      },
    },
  },
  navbar: {
    links: [
      { label: { 'zh-CN': '文档', 'en-US': 'Docs' }, href: '/getting-started' },
      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
    ],
  },
  banner: {
    content: { 'zh-CN': 'Clarify 正在快速迭代中', 'en-US': 'Clarify is evolving fast' },
    dismissible: true,
  },
  footer: {
    socials: {
      github: 'https://github.com/taicode-labs/clarify',
    },
    copyright: '© 2026 Clarify Team',
  },
  i18n: {
    defaultLocale: 'zh-CN',
    missing: 'fallback',
    locales: [
      { code: 'zh-CN', label: '简体中文', dir: 'ltr' },
      { code: 'en-US', label: 'English', dir: 'ltr' },
    ],
  },
  tabs: [
    {
      tab: { 'zh-CN': '文档', 'en-US': 'Docs' },
      icon: 'BookOpen',
      pages: 'FileTree',
    },
  ],
  ssg: {
    failOnError: true,
  },
  plugins: [],
})

顶层字段

字段	类型	默认值	说明
`title`	`string`	`"Clarify Docs"`	站点标题，用于侧边栏品牌和 HTML 标题
`description`	`string`	`""`	站点描述，用于 SEO 和 `llms.txt`
`logo`	`string \| { light?: string; dark?: string }`	—	品牌 Logo 路径
`favicon`	`string \| { light?: string; dark?: string }`	—	favicon 路径或亮暗主题变体
`theme`	`{ preset?: 'default' \| 'base'; tokens?: ClarifyThemeTokensConfig; layout?: ClarifyThemeLayoutConfig; editor?: boolean }`	`{ preset: 'default', editor: false }`	主题预设、局部覆盖和实时主题编辑器配置；`theme.editor` 可在构建后的站点中暴露编辑器，dev 模式会自动启用
`routePrefix`	`string`	`"/"`	部署子路径，例如 `/docs/`
`navbar`	`{ links?: ClarifyNavbarLink[] }`	—	顶部导航链接
`banner`	`ClarifyBannerConfig`	—	顶部公告配置，供主题或后续 UI 使用
`footer`	`ClarifyFooterConfig`	—	页脚配置，供主题或后续 UI 使用
`i18n`	`ClarifyI18nConfig`	—	多语言配置
`tabs`	`ClarifyTabsConfig`	按文件树自动生成	站点业务分类和各分类下的侧边栏结构
`ssg`	`{ failOnError?: boolean }`	`{ failOnError: true }`	静态生成错误策略
`plugins`	`ClarifyPlugin[]`	`[]`	构建期插件列表，仅 `clarify.ts/js` 可用

本地化文本

多个配置字段接受本地化文本：

type ClarifyLocalizedText = string | Record<string, string>

示例：

{
  label: {
    'zh-CN': '文档',
    'en-US': 'Docs',
  }
}

`logo` 和 `favicon`

type ClarifyLogoConfig = string | { light?: string; dark?: string }
type ClarifyFaviconConfig = string | { light?: string; dark?: string }

export default defineConfig({
  logo: '/logo.svg',
  favicon: {
    light: '/favicon-light.svg',
    dark: '/favicon-dark.svg',
  },
})

`theme`

theme: {
  preset?: 'default' | 'base'
  tokens?: ClarifyThemeTokensConfig
  layout?: ClarifyThemeLayoutConfig
}

preset 用来选择内置主题基底。当前只提供两个预设：

预设	主色	辅助色	默认最大内容宽度	适用场景
`default`	`#047857`	`#0D9488`	`82rem`	带有绿色品牌感的默认文档主题
`base`	`#18181b`	`#52525b`	`80rem`	无颜色偏好的黑、白、灰标准主题

剩余字段会在预设基础上覆盖。例如下面配置会先应用 base，再把主色覆盖为品牌色：

export default defineConfig({
  theme: {
    preset: 'base',
    tokens: {
      colors: {
        primary: '#00D492',
      },
    },
  },
})

主题 token 是“局部覆盖”而不是重写整套主题；没有配置的字段会继续继承所选 preset 的默认值。当前版本不会读取用户项目中的自定义 CSS 或 tailwind.config.js 来覆盖渲染器样式。

type ClarifyNavbarLink = {
  label: ClarifyLocalizedText
  href: string
  external?: boolean
}

export default defineConfig({
  navbar: {
    links: [
      { label: '文档', href: '/getting-started' },
      { label: 'API', href: '/features/openapi' },
      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
    ],
  },
})

建议顶部导航只保留核心入口，完整信息架构交给侧边栏承载。

type ClarifyBannerConfig = {
  content: ClarifyLocalizedText
  dismissible?: boolean
}

export default defineConfig({
  banner: {
    content: 'Clarify v0.1 已发布',
    dismissible: true,
  },
})

type ClarifyFooterLink = {
  label: ClarifyLocalizedText
  href: string
  external?: boolean
}

type ClarifyFooterConfig = {
  links?: ClarifyFooterLink[]
  socials?: Record<string, string>
  copyright?: ClarifyLocalizedText
}

export default defineConfig({
  footer: {
    links: [
      { label: '快速开始', href: '/getting-started' },
      { label: '配置参考', href: '/reference/clarify-config' },
      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
    ],
    socials: {
      github: 'https://github.com/taicode-labs/clarify',
    },
    copyright: '© 2026 Clarify Team',
  },
})

links 适合放置快速开始、配置参考、参与贡献等高频页脚入口；socials 适合放置 GitHub、X、Discord 等外部社区链接。

`i18n`

type ClarifyI18nConfig = {
  defaultLocale?: string
  missing?: 'fallback' | '404' | 'hide'
  locales: Array<{
    code: string
    label: string
    dir?: 'ltr' | 'rtl'
  }>
}

defaultLocale 对应不带语言前缀的默认路由；非默认语言会带上 locale 前缀。例如默认语言为 zh-CN 时，中文首页是 /，英文首页是 /en-US。

missing 控制某个语言缺少页面时的处理策略：

策略	行为	适合场景
`fallback`	使用默认语言内容补齐缺失页面	先发布主语言，再逐步补翻译
`hide`	不生成缺失语言页面	未翻译内容不希望出现在目标语言导航中
`404`	缺失页面保持不可访问	严格多语言发布，不允许 fallback 内容混入

dir 会写入生成 HTML 的 dir 属性，适合阿拉伯语、希伯来语等 RTL 语言。

更多说明见配置站点。

`tabs` 导航与侧边栏

Clarify 使用根级 tabs 做站点的一层业务分类。每个 tab 可以配置自己的侧边栏 pages；根级不再支持 pages。

type ClarifyTabsConfig = ClarifyTabItem[]

type ClarifyTabItem = {
  tab: ClarifyLocalizedText
  icon?: string
  pages?: ClarifyPagesConfig
}

type ClarifyPagesConfig = ClarifyPagesGroup[] | 'FileTree'

如果省略 tabs，Clarify 会根据内容目录的文件结构自动生成一个普通侧边栏，包含 .mdx 和 .openapi.json/.yaml/.yml 文件。

单个 tab 使用文件树

export default defineConfig({
  tabs: [
    {
      tab: '文档',
      icon: 'BookOpen',
      pages: 'FileTree',
    },
  ],
})

多个 tab 手动配置侧边栏

export default defineConfig({
  tabs: [
    {
      tab: { 'zh-CN': '指南', 'en-US': 'Guides' },
      icon: 'Rocket',
      pages: [
        {
          group: { 'zh-CN': '核心路径', 'en-US': 'Core Path' },
          icon: 'Rocket',
          pages: [
            { page: 'getting-started', title: '快速开始', icon: 'Rocket' },
            { page: 'guides/writing-content', title: '写作文档', icon: 'PenLine' },
            { page: 'guides/navigation', title: '配置站点', icon: 'SlidersHorizontal' },
          ],
        },
      ],
    },
    {
      tab: 'API',
      icon: 'BookOpenCheck',
      pages: [
        {
          group: 'API 文档',
          pages: [
            { openapi: 'api.openapi.json', title: 'API Reference', icon: 'BookOpenCheck' },
          ],
        },
      ],
    },
  ],
})

`ClarifyTabItem`

字段	类型	必填	说明
`tab`	`ClarifyLocalizedText`	是	tab 显示名称
`icon`	`string`	否	Lucide 图标名
`pages`	`ClarifyPagesConfig`	否	当前 tab 下的侧边栏结构；省略时按文件树生成

`ClarifyPagesGroup`

字段	类型	必填	说明
`group`	`ClarifyLocalizedText`	是	分组标题
`icon`	`string`	否	Lucide 图标名
`pages`	`ClarifyPagesItem[]`	是	分组下的页面

`ClarifyPagesItem`

形态	说明
`"getting-started"`	简写，引用 MDX 页面
`{ page }`	引用 MDX 页面，不写 `.mdx` 后缀
`{ page, title, icon, redirect }`	引用页面并覆盖标题、图标或目标路径
`{ openapi, title, icon, filter }`	引用 OpenAPI 规范文件；`filter.tags` 可按 operation tags 过滤接口

redirect 只改变导航项点击后的目标路径，不会创建新的内容页面。它适合把一个导航入口指向更具体的章节、迁移后的路径，或在分组首页不存在时避免用户进入空页面：

{
  page: 'guides',
  title: '指南',
  icon: 'BookOpen',
  redirect: '/guides/writing-content',
}

OpenAPI 页面默认展示规范中的全部接口。配置 filter.tags 后，页面只展示 operation.tags 中至少命中一个指定 tag 的接口，并基于 tag 生成独立路由：

{
  openapi: 'api.openapi.json',
  title: 'Projects API',
  filter: {
    tags: ['Projects'],
  },
}

上面的页面路由为 /api/projects。tag 会被转成小写 kebab-case；多个 tag 会按配置顺序拼接，例如 ['Admin Users', 'Billing'] 会生成 /api/admin-users-billing。启用 i18n 时，默认语言仍是 /api/projects，非默认语言会加上 locale 前缀，例如 /en-US/api/projects。

`ssg`

ssg: {
  failOnError?: boolean
}

字段	默认值	说明
`failOnError`	`true`	SSG 失败时是否中断构建

`plugins`

plugins: ClarifyPlugin[]

插件只能在 clarify.ts 或 clarify.js 中配置。更多说明见插件机制和插件 API 参考。

CLI 覆盖项

CLI 会把以下运行参数传入构建系统：

CLI 选项	内部字段	默认值	命令
`--root <dir>`	`projectRoot`	当前目录	`dev` / `build` / `init`
`--content <dir>`	`rootDirectory`	`source`	`dev` / `build` / `init`
`--output <dir>`	`outputDirectory`	`output`	`dev` / `build` / `init`
`--host [host]`	Vite dev server host	—	`dev`
`--port <port>`	Vite dev server port	—	`dev`
`--open [path]`	Vite dev server open	—	`dev`

优先级为：

CLI 参数 > clarify.ts/js/json > 默认值

这允许 CI 在不修改项目配置的情况下覆盖输出目录或内容目录。