配置站点

这篇文档合并说明 Clarify 中和“站点体验”有关的配置：顶部导航、Tabs、侧边栏、主题、多语言、部署子路径和信息架构。

真实项目建议用配置表达读者任务路径，而不是直接暴露仓库目录结构。

顶部导航

顶部导航只放少量高频入口：

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

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 },
    ],
  },
})

字段	说明
`label`	导航项显示文字；支持多语言对象
`href`	链接地址，站内链接建议使用绝对路径
`external`	是否按外部链接处理

Tabs 与侧边栏

Clarify 使用根级 tabs 做站点的一层业务分类。每个 tab 拥有自己的侧边栏。

export default defineConfig({
  tabs: [
    {
      tab: '文档',
      icon: 'BookOpen',
      pages: [
        {
          group: '开始使用',
          icon: 'Rocket',
          pages: [
            { page: 'getting-started', icon: 'Map' },
            { page: 'guides/writing-content', title: '写作文档', icon: 'PenLine' },
          ],
        },
      ],
    },
  ],
})

tabs[].pages 支持两种模式：

模式	适用场景
`'FileTree'`	小型站点或早期原型，直接按 `source` 目录生成
分组数组	正式文档站，按用户任务组织阅读路径

页面项类型：

字段	说明
`page`	引用 `source` 下的 MDX 页面，不写 `.mdx` 后缀
`openapi`	引用 `source` 下的 OpenAPI JSON/YAML 文件
`title`	覆盖页面在导航中的显示标题
`icon`	使用 lucide 图标名称

示例 OpenAPI 入口：

{
  openapi: 'api.openapi.json',
  title: 'API Reference',
  icon: 'FileJson2',
}

入口	解决的问题
快速开始	如何安装、创建页面、启动和构建
写作文档	如何写 MDX、组织目录、使用 Frontmatter 和组件
配置站点	如何配置导航、主题、多语言和路径
API 文档	如何把 OpenAPI 变成 Reference 和教程嵌入
发布上线	如何构建、部署、输出 `llms.txt`
参考资料	查询字段、命令和组件属性

主题

Clarify 当前提供稳定、收敛的主题配置：先选择预设，再用少量 token 覆盖。

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

当前预设：

预设	说明
`default`	Clarify 品牌主题
`base`	黑、白、灰构成的中性主题

注意：

不需要创建 tailwind.config.js。
当前没有稳定的项目级自定义 CSS 入口。
亮色、暗色和系统偏好检测由渲染器内置。

国际化

开启 i18n 后，内容按 locale 目录组织，路由、导航、语言切换器和缺失翻译回退会自动处理。

export default defineConfig({
  i18n: {
    defaultLocale: 'zh-CN',
    missing: 'fallback',
    locales: [
      { code: 'zh-CN', label: '简体中文', dir: 'ltr' },
      { code: 'en-US', label: 'English', dir: 'ltr' },
    ],
  },
})

目录示例：

source/
├── zh-CN/
│   ├── index.mdx
│   └── getting-started.mdx
└── en-US/
    ├── index.mdx
    └── getting-started.mdx

路由规则：

文件	路由
`source/zh-CN/index.mdx`	`/`
`source/zh-CN/getting-started.mdx`	`/getting-started`
`source/en-US/index.mdx`	`/en-US`
`source/en-US/getting-started.mdx`	`/en-US/getting-started`

缺失翻译策略：

策略	行为
`fallback`	缺失页面使用默认语言内容生成对应 locale 路由
`404`	缺失页面不生成对应语言路由
`hide`	缺失页面不生成；自动文件树导航中也隐藏

配置中的可见文本支持本地化对象，例如：

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

部署子路径

如果站点部署在子路径下，例如 GitHub Pages 项目站点，需要配置 routePrefix：

export default defineConfig({
  routePrefix: '/my-repo/',
})

Clarify 会同步处理页面路由、静态资源路径、客户端导航和原始内容链接。

隐藏页面

当前版本不提供 hidden frontmatter。要隐藏某个页面，不要把它加入显式 tabs 配置即可。文件仍然存在，可通过 URL 直接访问。

配置站点

顶部导航

Tabs 与侧边栏

推荐信息架构

主题

国际化

部署子路径

隐藏页面