配置参考

在项目根目录创建 openmanual.json 来配置你的文档站点。配置文件使用 Zod Schema 严格校验，错误提示清晰友好。

完整配置示例

{
  "name": "My Docs",
  "description": "项目文档",
  "contentDir": "content",
  "outputDir": "dist",
  "locale": "zh",
  "navbar": {
    "logo": "/logo.svg",
    "github": "https://github.com/user/repo",
    "links": [
      { "label": "Blog", "href": "https://blog.example.com" }
    ]
  },
  "footer": {
    "text": "Built with OpenManual"
  },
  "sidebar": [
    {
      "group": "快速开始",
      "icon": "Rocket",
      "collapsed": false,
      "pages": [
        { "slug": "getting-started", "title": "安装指南", "icon": "Download" },
        { "slug": "configuration", "title": "配置说明", "icon": "Settings" }
      ]
    }
  ],
  "theme": {
    "primaryHue": 240,
    "darkMode": true
  },
  "search": {
    "enabled": true
  },
  "mdx": {
    "latex": true
  }
}

字段说明

基础配置

字段	类型	必填	默认值	说明
`name`	string	是	—	站点名称，显示在导航栏和页面标题
`description`	string	否	—	站点描述，用于 SEO meta 标签
`contentDir`	string	否	`content`	文档内容目录路径
`outputDir`	string	否	`dist`	构建产物输出目录
`locale`	string	否	—	站点语言，如 `zh`、`en`

字段	类型	必填	默认值	说明
`navbar.logo`	`string \| { light, dark }`	否	—	Logo 配置。字符串形式为图片路径或文本；对象形式可分别指定 light/dark 模式的图片路径
~~`navbar.github`~~	string	否	—	~~GitHub 仓库链接~~ (已废弃，请使用 `header.links`)
`navbar.links`	array	否	—	导航栏链接列表

:::note[迁移指南]

如果之前使用了 navbar.github 配置 GitHub 链接，请迁移到 header.links：

// 旧写法（已废弃）
{ "navbar": { "github": "https://github.com/user/repo" } }

// 新写法（推荐）
{ "header": { "links": [{ "icon": "Github", "href": "https://github.com/user/repo" }] } }

支持三种图标格式：lucide 图标名（如 "Github"）、自定义 SVG 路径（如 "/icons/github-fill.svg"）、或纯文字标签。

:::

navbar.logo 支持两种形式：

// 字符串形式（向后兼容）
"logo": "/logo.svg"     // 图片路径
"logo": "MyProject"     // 纯文本

// 对象形式，分别指定 light/dark 模式 Logo
"logo": {
  "light": "/logo-light.svg",
  "dark": "/logo-dark.svg"
}

字段	类型	必填	默认值	说明
`footer.text`	string	否	—	页脚文本

字段	类型	必填	默认值	说明
`sidebar[].group`	string	是	—	分组名称
`sidebar[].icon`	string	否	—	分组图标名称
`sidebar[].collapsed`	boolean	否	`false`	是否默认折叠
`sidebar[].pages[].slug`	string	是	—	页面 slug，对应文件路径
`sidebar[].pages[].title`	string	是	—	页面标题
`sidebar[].pages[].icon`	string	否	—	页面图标名称

搜索 (search)

搜索功能默认启用，无需配置。可通过 search.position 控制搜索入口位置：

字段	类型	必填	默认值	说明
`search.position`	string	否	`'sidebar'`	搜索入口位置：`'sidebar'`（侧边栏顶部）或 `'header'`（导航栏中间）

MDX (mdx)

字段	类型	必填	默认值	说明
`mdx.latex`	boolean	否	`false`	是否启用 LaTeX 公式支持

页面树生成规则

未在 sidebar 配置中声明的 MDX 文件不会出现在导航中
slug 字段对应 contentDir 下的文件路径（不含扩展名）
例如 slug: "advanced/theme" 对应 content/advanced/theme.mdx

配置参考

配置参考

完整配置示例

字段说明

基础配置

导航栏 (navbar)

页脚 (footer)

侧边栏 (sidebar)

搜索 (search)

MDX (mdx)

页面树生成规则

On this page