zihaodoc

文档构建工具 - 支持 create 创建文档项目，build 构建文档，支持离线资源自动下载，支持 run 启动开发服务器。

安装

npm install -g zihaodoc

使用

创建新文档项目

zihaodoc create api_doc

这会创建以下结构：

• api_doc/docs/ - Markdown 源文件目录
• api_doc/dist/ - 生成的 HTML 输出目录
• api_doc/base.html - HTML 模板
• api_doc/zihao_doc.css - 样式文件
• api_doc/zihao_doc.js - JavaScript 文件
• api_doc/menu.yaml - 菜单配置
• api_doc/assets/ - 离线资源

构建文档

zihaodoc build api_doc

将 docs/ 目录下的 Markdown 文件转换为 HTML，并输出到 dist/ 目录。

启动开发服务器

zihaodoc run api_doc

启动开发服务器并监听文件变动，自动增量构建。

指定端口：

zihaodoc run api_doc -p 8080

功能特性

• Markdown 转 HTML
• 自动下载离线资源（Tailwind CSS、Font Awesome、Google Fonts）
• 实时监听文件变动，自动增量构建
• 内置 HTTP 服务器
• 搜索功能
• 响应式设计
• 图片点击预览

离线资源

构建时会自动检查并下载以下离线资源到 dist 目录：

• Tailwind CSS
• Font Awesome
• Google Fonts (Inter)

首次构建时会下载，之后会使用本地缓存。

目录结构

api_doc/
├── docs/           # Markdown 源文件
│   ├── index.md
│   └── guide/
│       └── getting-started.md
├── dist/           # 生成的 HTML（可部署）
│   ├── index.html
│   ├── zihao_doc.css
│   ├── zihao_doc.js
│   ├── tailwindcss.js
│   ├── font-awesome/
│   └── fonts/
├── assets/         # 离线资源缓存
├── base.html       # HTML 模板（可自定义）
├── zihao_doc.css   # 样式文件（可自定义）
├── zihao_doc.js    # JS 文件（可自定义）
└── menu.yaml       # 菜单配置

菜单配置 (menu.yaml)

site_name: 文档中心
nav:
  - title: 首页
    icon: fa-solid fa-house
    url: index.html
  - title: 快速入门
    icon: fa-solid fa-rocket
    children:
      - title: 产品架构介绍
        url: /guide/architecture.html
      - title: Docker 部署
        url: /guide/docker.html

模板变量

在 base.html 中可使用以下变量：

• {{ title }} - 页面标题
• {{ site_name }} - 站点名称
• {{ breadcrumb }} - 面包屑导航
• {{ assets_path }} - 静态资源路径
• {{{ menu }}} - 渲染后的菜单 HTML
• {{{ content }}} - 渲染后的 Markdown 内容

License

MIT