Simple document generation tool. Dependence Node.js run.
npm install zhangdocsCtrl + ←/→）
bash
npm install -g zhangdocs
`
$3
`bash
npm install zhangdocs
`
安装完成后，可以使用 doc 命令来操作项目。
🚀 快速开始
$3
在项目目录下运行：
`bash
doc init
`
或者指定项目名称：
`bash
doc init --Create my-docs
`
初始化过程会引导你配置项目信息，包括：
- 项目名称
- 版本号
- 描述
- 关键词
- 许可证
- 主题选择
$3
在 md/ 目录下创建 Markdown 文件，例如：
`markdown
第一章 介绍
这是第一章的内容。
1.1 概述
概述内容...
`
文件命名建议：使用 数字.标题.md 格式（如 1.介绍.md），工具会自动按数字排序。
$3
`bash
doc build
`
构建完成后，HTML 文件将生成在 html/ 目录下，首页 index.html 会生成在项目根目录。
$3
`bash
doc server
`
这将启动一个本地服务器，并监听文件变化自动重新构建。
$3
`bash
doc watch
`
监听 md/ 目录下的文件变化，自动重新构建。
📖 命令说明
| 命令 | 说明 |
|------|------|
| doc init | 初始化项目 |
| doc build | 构建静态页面 |
| doc watch | 监听文件变化并自动构建 |
| doc server | 启动开发服务器（包含 watch 功能） |
| doc clean | 清理构建文件 |
| doc deploy | 部署文档 |
| doc theme | 主题管理 |
| doc -V | 查看版本号 |
⚙️ 配置说明
项目配置在 package.json 的 zhangdocs 字段中：
`json
{
"zhangdocs": {
"theme": "handbook",
"md": [
"README.md"
]
}
}
`
- theme: 使用的主题名称（位于 theme/ 目录下）
- md: 文档入口文件列表（相对于 md/ 目录）
📁 项目结构
`
项目根目录/
├── md/ # Markdown 源文件目录
│ ├── README.md
│ └── ...
├── html/ # 生成的 HTML 文件目录
│ └── ...
├── static/ # 静态资源目录（CSS、图片等）
│ ├── css/
│ └── img/
├── theme/ # 主题目录
│ └── handbook/
│ ├── layout.ejs # 布局模板
│ ├── header.ejs # 头部模板
│ ├── footer.ejs # 底部模板
│ └── source/ # 主题源文件
├── index.html # 生成的目录首页
└── package.json # 项目配置
`
🎯 主要功能
$3
支持多种编程语言的代码高亮：
``markdown
`javascript
function hello() {
console.log("Hello, World!");
}
`
``
$3
支持多种图表类型：
``markdown
`mermaid
graph TD
A[开始] --> B{判断}
B -->|是| C[执行]
B -->|否| D[结束]
`
``
$3
支持行内公式和块级公式：
`markdown
行内公式：$E = mc^2$
块级公式：
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
`
$3
- 每个页面底部有"上一节"和"下一节"按钮
- 支持键盘快捷键：
- Ctrl + ←：上一节
- Ctrl + →：下一节
$3
工具会自动按文件名前缀的数字排序：
- 1.介绍.md → 2.使用.md → 3.API.md
- 没有数字前缀的文件会排在有序号文件的后面
🔒 访问控制
文档支持 Token 验证功能，可以在模板中配置访问令牌验证逻辑，保护文档内容不被未授权访问。
🎨 主题定制
项目支持自定义主题，主题文件位于 theme/ 目录下。你可以：
1. 修改现有主题的样式和模板
2. 创建新主题
3. 使用 doc theme 命令管理主题
📝 注意事项
1. 文件命名：建议使用 数字.标题.md 格式，便于自动排序
2. 图片路径：图片应放在 static/img/ 目录下，在 Markdown 中使用相对路径引用
3. 数学公式：使用 $...$ 表示行内公式，$$...$$ 表示块级公式
4. Mermaid 图表：在代码块中指定语言为 mermaid`，工具会自动处理特殊字符转义