文档构建工具使用说明

安装

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 - 菜单配置

构建文档

zihaodoc build api_doc

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

启动开发服务器

zihaodoc run api_doc

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

zihaodoc run api_doc -p 8080

指定端口启动。

离线资源

构建时会自动检查并下载以下离线资源到 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/
├── 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 }} - 面包屑导航
• {{{ menu }}} - 渲染后的菜单 HTML
• {{{ content }}} - 渲染后的 Markdown 内容