开源技术书籍 HonKit + Mermaid 构建模板

这是一个专为软件工程、技术架构类书籍设计的本地化、轻量级静态电子书构建模板。

模板在 HonKit 基础上，融合了 Mermaid 静态预渲染、HTML5 figure 语义图示规范、自动化出版前排版审校和 GitHub Pages 双端持续集成。

一、模板特性

  1. 零运行时 Mermaid 依赖：使用 Puppeteer 和 @mermaid-js/mermaid-cli 在构建前将 .mmd 矢量源码批量转换为高清、可缩放的 .svg。解决静态发布平台（GitHub Pages 等）及 PDF 导出对三方 Mermaid 插件的不兼容问题；
  2. HTML5 语义化图示管理：提供图示规范化脚本，自动把普通 Markdown 图片语法转换为标准的 <figure> + <figcaption>，自动生成连续图号和中文图注；
  3. 自动化排版审校（Linter）：内置 audit-book.js 审校器，强制验证章节元信息、导读、图号连续性、本地失效链接、代码块长度和禁用术语；
  4. 网站级排版优化：内置 website.css，针对技术书籍的“本章导读”、“章节元信息”、“案例小结”和“实践任务”进行了视觉语义增强与移动端防溢出处理；
  5. 发布级 SEO 自动增强：编译产物自动生成 canonical 连接、Open Graph 社交元数据、sitemap.xml 和 robots.txt，对搜索引擎友好。

二、模板工程结构

online-book-template/
  ├── .github/
  │     └── workflows/
  │           └── deploy-pages.yml      # GitHub Pages 自动构建发布
  ├── appendix/
  │     └── README.md                   # 附录索引
  ├── book/
  │     ├── _chapter-template.md        # 规范化章节 Markdown 模板
  │     └── 01-intro.md                 # 样章示例
  ├── diagrams/
  │     ├── .render-manifest.json       # 预渲染指纹文件（加速编译）
  │     └── README.md                   # 图示规范
  ├── scripts/
  │     ├── audit-book.js               # 出版前排版审校器
  │     ├── normalize-chapter-layout.js # 元信息结构化脚本
  │     ├── normalize-figures.js        # 语义化图片转换脚本
  │     ├── prepare-pages.js            # SEO 标签与站点地图生成脚本
  │     └── render-diagrams.js          # Mermaid 增量渲染脚本
  ├── styles/
  │     └── website.css                 # 电子书网站版排版层叠样式表
  ├── book.json                         # HonKit 配置文件
  ├── package.json                      # 模块依赖与常用 npm 脚本
  ├── puppeteer-config.json             # Puppeteer 沙箱逃逸配置
  ├── README.md                         # 模板介绍与使用手册
  └── SUMMARY.md                        # 书籍导航树

三、快速开始

1. 从模板初始化

克隆或以此模板创建你的书籍仓库：

git clone https://github.com/your-username/your-book-repo.git
cd your-book-repo

2. 安装依赖

npm ci

(注意：安装依赖会下载 Puppeteer 所需的 Chromium，用于将 Mermaid 图形渲染为 SVG。)

3. 本地预览

npm run book:serve

默认启动本地热重载服务器：http://localhost:4005。

四、核心命令与开发流

1. 规范化元数据和图示

在编写完新章节或加入普通 Markdown 图片后，运行此命令将内容自动规范化为 <aside> 元数据框和 <figure> 语义图片结构：

npm run book:format

2. 预渲染 Mermaid 图形

扫描 diagrams/ 目录下的 .mmd 并自动生成同名 .svg（增量构建）：

npm run diagrams:render

强制重新渲染所有图形：

npm run diagrams:render:force

3. 出版前排版审校

检查 23 个维度的格式问题（包含空链接、编号缺失等）：

npm run book:audit

4. 编译静态网站

清理旧产物、重新渲染有变更的图、执行排版审校，并生成包含 SEO 标签和 sitemap 的静态页面：

npm run book:build

五、章节规范样式 (Styles)

模板内置的 styles/website.css 对以下元素进行了统一视觉定义：

  • 第一标题与章名：自带底部主强调色装饰线；
  • 本章导读 (Lead)：带有柔和左边界色条的强调信息容器；
  • 章节元信息 (Meta)：栅格化布局，弱化视觉，展示对应文章及状态；
  • 二级标题 (H2)：左侧突出强调条；
  • 语义卡片 (H2 id/class 自动挂载)：
    • #贯穿案例...：紫色渐变，用于引导实践场景；
    • #本章小结...：绿色渐变，用于归纳结论；
    • #实践任务...：琥珀色渐变，用于阶段习题；
  • 图示容器 (Figure)：自带圆角、居中、响应式图片尺寸、多行说明文字，并在右上角带有可以直接在新窗口查看的高清 SVG 原图链接。

六、GitHub Pages 自动化部署

模板在 .github/workflows/deploy-pages.yml 配置了开箱即用的 GitHub Actions。向 main 分支推送后，将自动完成以下部署：

  1. 克隆代码；
  2. 安装依赖；
  3. 执行排版格式化、Mermaid 图形预渲染、全书校验；
  4. 构建静态站点；
  5. 生成 SEO sitemap 与 canonical URL；
  6. 自动发布到 https://<username>.github.io/<repo>/。

(在仓库设置中：Settings → Pages → Build and deployment → Source 需选定为 GitHub Actions)

results matching ""

    No results matching ""