honkit-plugin-mermaid-svg

Mermaid 渲染插件，兼容 Honkit 与 GitBook 3。

构建时自动将 markdown 中的 ```mermaid 代码块渲染为图形：

• website 构建 → 输出矢量 SVG（无限清晰）
• EPUB / PDF 构建 → 输出 PNG（高兼容性，阅读器全支持）
• 容器内直接调用全局 mmdc（docker-gitbook 镜像已内置），不依赖 npx 网络下载
• 自动检测容器 /puppeteer-config.json（已含 --no-sandbox），无需手动创建

安装

npm install honkit-plugin-mermaid-svg

在 Docker 镜像（bloodstar/gitbook-builder）中使用

镜像已内置全部依赖，只需在 book.json 声明插件：

{
  "plugins": ["mermaid-svg"],
  "pluginsConfig": {
    "mermaid-svg": {
      "plugin": {
        "embed": false
      },
      "mermaid": {
        "theme": "neutral"
      }
    }
  }
}

构建时自动生效（无需额外安装步骤）：

docker run --rm -v "$PWD":/workspace -w /workspace \
  bloodstar/gitbook-builder:latest \
  bash -c 'honkit epub && honkit pdf'

配置

• pluginsConfig["mermaid-svg"].plugin.embed
  • true：website 构建时用 mermaid-cli 渲染 SVG 并嵌入
  • false（默认）：website 构建时用浏览器端 Mermaid JS 直接渲染，EPUB/PDF 始终用 mermaid-cli
• pluginsConfig["mermaid-svg"].mermaid
  • 透传给 mermaid-cli 的配置（如 theme），详见 Mermaid 主题

使用

在 markdown 中写 ```mermaid 代码块即可：

```mermaid
graph TD
    A[计划] --> B[组织]
    B --> C[控制]
```

兼容性

| 引擎 | website | epub | pdf | |------|---------|------|-----| | Honkit | ✅ | ✅ | ✅ | | GitBook 3 | ✅ | ✅ | ✅ |

Linux / Docker 说明

无需手动创建 puppeteer-config.json——插件自动检测：

1. /puppeteer-config.json（容器内置，含 --no-sandbox）
2. 书根目录 puppeteer-config.json（可选，覆盖默认）

致谢

基于 intptr-t/honkit-plugin-mermaid-hybrid 改造。