zhangdocs

一个简单易用的文档生成工具，可以将 Markdown 文件编译成美观的 HTML 静态文档网站。

✨ 功能特性

• 📝 Markdown 支持 - 完整的 Markdown 语法支持，包括 GFM（GitHub Flavored Markdown）
• 🎨 代码高亮 - 基于 highlight.js 的代码语法高亮，支持多种编程语言
• 📊 Mermaid 图表 - 支持流程图、类图、时序图等多种图表类型
• 🔢 数学公式 - 支持 LaTeX 数学公式渲染（行内和块级）
• 📑 自动目录 - 自动生成页面目录导航和全局导航菜单
• 🔄 章节导航 - 支持上一节/下一节按钮和键盘快捷键（Ctrl + ←/→）
• 🏠 目录首页 - 自动生成文档目录索引页面
• 🎯 文件排序 - 支持按文件名前缀数字自动排序章节
• 🔒 访问控制 - 支持 Token 验证保护文档内容
• 🖼️ 图片预览 - 集成 Viewer.js 支持图片点击预览
• 👀 实时预览 - 支持文件监听和自动重新构建
• 🎨 主题定制 - 支持自定义主题和样式
• 📱 响应式设计 - 适配桌面和移动设备

📦 安装

全局安装

npm install -g zhangdocs

本地安装

npm install zhangdocs

安装完成后，可以使用 doc 命令来操作项目。

🚀 快速开始

1. 初始化项目

在项目目录下运行：

doc init

或者指定项目名称：

doc init --Create my-docs

初始化过程会引导你配置项目信息，包括：

• 项目名称
• 版本号
• 描述
• 关键词
• 许可证
• 主题选择

2. 编写文档

在 md/ 目录下创建 Markdown 文件，例如：

# 第一章 介绍

这是第一章的内容。

## 1.1 概述

概述内容...

文件命名建议：使用 数字.标题.md 格式（如 1.介绍.md），工具会自动按数字排序。

3. 构建文档

doc build

构建完成后，HTML 文件将生成在 html/ 目录下，首页 index.html 会生成在项目根目录。

4. 启动开发服务器

doc server

这将启动一个本地服务器，并监听文件变化自动重新构建。

5. 监听文件变化

doc watch

监听 md/ 目录下的文件变化，自动重新构建。

📖 命令说明

| 命令 | 说明 | |------|------| | doc init | 初始化项目 | | doc build | 构建静态页面 | | doc watch | 监听文件变化并自动构建 | | doc server | 启动开发服务器（包含 watch 功能） | | doc clean | 清理构建文件 | | doc deploy | 部署文档 | | doc theme | 主题管理 | | doc -V | 查看版本号 |

⚙️ 配置说明

项目配置在 package.json 的 zhangdocs 字段中：

{
  "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           # 项目配置

🎯 主要功能

代码高亮

支持多种编程语言的代码高亮：

```javascript
function hello() {
    console.log("Hello, World!");
}
```

Mermaid 图表

支持多种图表类型：

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

数学公式

支持行内公式和块级公式：

行内公式：$E = mc^2$

块级公式：
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$

章节导航

• 每个页面底部有"上一节"和"下一节"按钮
• 支持键盘快捷键：
  • Ctrl + ←：上一节
  • Ctrl + →：下一节

文件排序

工具会自动按文件名前缀的数字排序：

• 1.介绍.md → 2.使用.md → 3.API.md
• 没有数字前缀的文件会排在有序号文件的后面

🔒 访问控制

文档支持 Token 验证功能，可以在模板中配置访问令牌验证逻辑，保护文档内容不被未授权访问。

🎨 主题定制

项目支持自定义主题，主题文件位于 theme/ 目录下。你可以：

1. 修改现有主题的样式和模板
2. 创建新主题
3. 使用 doc theme 命令管理主题

📝 注意事项

1. 文件命名：建议使用 数字.标题.md 格式，便于自动排序
2. 图片路径：图片应放在 static/img/ 目录下，在 Markdown 中使用相对路径引用
3. 数学公式：使用 $...$ 表示行内公式，$$...$$ 表示块级公式
4. Mermaid 图表：在代码块中指定语言为 mermaid，工具会自动处理特殊字符转义