openmanual

AI 友好的开源文档系统框架。只需编写 Markdown/MDX 文档和 JSON 配置，即可自动生成基于 Next.js 的完整文档站点。

特性

• 零配置起步 — 最小只需 name 字段和 content/index.mdx 即可启动
• 代码生成模式 — 通过模板引擎生成 Next.js 应用，用户无需接触框架代码
• Zod 校验 — 配置文件使用 Zod Schema 严格校验，错误提示清晰
• 灵活导航 — 支持多分组侧边栏、自定义图标、折叠控制
• 主题定制 — 通过 primaryHue 色相值轻松调整品牌色
• 全文搜索 — 内置搜索功能，一行配置开启
• MDX 增强 — 支持 React 组件、LaTeX 公式
• AI 原生设计 — 纯 JSON 配置 + Markdown 内容，非常适合 AI 辅助生成

快速开始

安装

npm install -g openmanual

创建项目

# 1. 创建项目目录
mkdir my-docs && cd my-docs

# 2. 创建配置文件（最小配置）
cat > openmanual.json << 'EOF'
{
  "name": "My Docs"
}
EOF

# 3. 创建首页文档
mkdir content
cat > content/index.mdx << 'EOF'
---
title: 欢迎使用
---

# Hello OpenManual

这是我的第一篇文档。
EOF

# 4. 启动开发服务器
openmanual dev

访问 http://localhost:3000 即可看到文档站点。

CLI 命令

命令	说明
openmanual dev	启动开发服务器（默认端口 3000）
openmanual dev -p 8080	指定端口启动
openmanual build	构建静态站点
openmanual preview	预览构建产物（默认端口 8080）
openmanual preview -d ./out	指定产物目录预览

配置参考

在项目根目录创建 openmanual.json：

{
  "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" }
      ]
    },
    {
      "group": "进阶",
      "collapsed": true,
      "pages": [
        { "slug": "advanced/theme", "title": "主题定制" },
        { "slug": "advanced/search", "title": "搜索配置" }
      ]
    }
  ],
  "search": {
    "enabled": true
  },
  "mdx": {
    "latex": true
  }
}

配置字段说明

字段	类型	必填	默认值	说明
name	string	是	—	站点名称
description	string	否	—	站点描述
contentDir	string	否	content	文档内容目录
outputDir	string	否	dist	构建产物输出目录
locale	string	否	—	站点语言
navbar.logo	string	否	—	Logo 图片路径
navbar.github	string	否	—	GitHub 仓库链接
navbar.links	array	否	—	导航栏链接列表
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.enabled	boolean	否	true	是否启用搜索
mdx.latex	boolean	否	false	是否启用 LaTeX 支持

项目结构

一个典型的 OpenManual 用户项目结构如下：

my-docs/
├── openmanual.json       # 配置文件
├── content/              # 文档内容目录
│   ├── index.mdx         # 首页
│   ├── getting-started.mdx
│   └── advanced/
│       ├── theme.mdx
│       └── search.mdx
└── public/               # 静态资源（可选）
    └── logo.svg

工作原理

flowchart LR
    A[openmanual.json] --> C[配置解析 + Zod 校验]
    B[content/*.mdx] --> C
    C --> D[模板引擎生成 Next.js 应用]
    D --> E[安装依赖]
    E --> F{dev / build}
    F -->|dev| G[开发服务器 localhost:3000]
    F -->|build| H[静态站点输出到 dist/]

• 读取配置 — 解析 openmanual.json，使用 Zod Schema 校验所有字段
• 加载内容 — 扫描 contentDir 下的所有 MDX 文件
• 生成应用 — 通过模板引擎生成完整的 Next.js 应用到临时目录
• 链接内容 — 将用户内容目录和静态资源符号链接到生成目录
• 安装依赖 — 自动安装生成应用所需的 npm 依赖
• 启动/构建 — 启动开发服务器或构建静态产物

编写文档

每个 MDX 文件可以包含 frontmatter 元数据：

---
title: 页面标题
---

# 页面标题

这里是正文内容，支持标准 Markdown 语法和 MDX 组件。

页面树生成规则

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

贡献 / 开发

欢迎贡献！以下是本地开发环境搭建步骤：

# 克隆仓库
git clone https://github.com/shenjingnan/openmanual.git
cd openmanual

# 安装依赖
pnpm install

# 开发模式
pnpm run dev

# 构建
pnpm run build

# 运行测试
pnpm run test

# 代码检查
pnpm run check

开发命令

命令	说明
pnpm run dev	开发模式（watch）
pnpm run build	构建项目
pnpm run test	运行测试
pnpm run test:watch	测试监听模式
pnpm run test:coverage	测试覆盖率报告
pnpm run lint	代码检查
pnpm run lint:fix	自动修复代码问题
pnpm run format	格式化代码
pnpm run typecheck	TypeScript 类型检查
pnpm run check	完整检查（typecheck + lint）
pnpm run spellcheck	拼写检查

许可证

MIT © 2026 shenjingnan