PlantUML 与文档站集成：Hexo / MkDocs / Sphinx / Docusaurus 全攻略

文档站里放图，最好的方案因框架而异——这里有 4 套主流工具的实际配置。

为什么需要专门讨论这件事？

PlantUML 源码 + 渲染结果是分开的。这意味着文档站有三种嵌入方式：

1. 预渲染：构建时生成 SVG 静态文件 → <img> 引入（最快、最稳）
2. 客户端渲染：运行时调 plantuml.com / 自有 server（灵活、慢一点）
3. 边渲染边预生成：混用——平时用预渲染，作者改图时客户端实时预览

下面按 4 套常见工具说。

Hexo（你正在用的）

方案 A：服务端预渲染（推荐）

用 hexo-renderer-plantuml：

1

npm install hexo-renderer-plantuml --save

_config.yml：

1
2
3
4
5

plantuml:
  render: plantuml
  syntax: ```plantuml
  inline: true
  cache: false

post 里：

1
2
3
4

{% plantuml %}
Alice -> Bob: Hi
Bob --> Alice: Hi back
{% endplantuml %}

构建时由 plantuml CLI 渲染成 SVG，嵌入 HTML。优点：纯静态、加载快、SEO 友好。缺点：构建慢（每张图都要 Java/PlantUML）。

方案 B：客户端实时渲染

1
2
3
4
5
6
7
8
9
10
11
12

<script src="https://cdn.jsdelivr.net/npm/plantuml-encoder@1.4.0/lib/puml.min.js"></script>
<script type="text/plantuml">
Alice -> Bob: Hi
Bob --> Alice: Hi back
</script>
<script>
  document.querySelectorAll('script[type="text/plantuml"]').forEach(s => {
    const encoded = plantumlEncoder.encode(s.textContent);
    s.insertAdjacentHTML('afterend',
      `<img src="https://www.plantuml.com/plantuml/svg/~1${encoded}">`);
  });
</script>

优点：构建快、改图不用 rebuild。缺点：依赖 plantuml.com，CI 构建机无法翻墙时炸。

方案 C：TeaVM 客户端预渲染（折中）

把 plantuml.js 放进 themes/<name>/source/js/，在页面里走 TeaVM：

• 第一次加载慢（TeaVM 启动），之后缓存
• 全离线、不依赖外部服务
• 配置麻烦些，参考本站实践

MkDocs（Python 文档站）

插件 plantuml-markdown：

1

pip install plantuml-markdown

mkdocs.yml：

1
2
3
4
5
6

plugins:
  - plantuml:
      server: http://www.plantuml.com/plantuml
      format: svg
      theme: default
      class_name: uml

post 里：

1
2
3
4
5
6

Alice -> Bob: Hi
Bob --> Alice: Hi back
{%% uml %%}
Alice -> Bob: Hi
Bob --> Alice: Hi back
{%% enduml %%}

优点：支持本地 plantuml jar（也可走 plantuml.com）。缺点：默认走外部服务。

Sphinx（Python 官方文档系统）

插件 sphinxcontrib-plantuml：

1

pip install sphinxcontrib-plantuml

conf.py：

1
2
3
4

extensions = ['sphinxcontrib.plantuml']
plantuml = 'plantuml'
plantuml_output_format = 'svg'
plantuml_latex_output_format = 'pdf'

post 里：

1
2
3
4

.. uml::

   Alice -> Bob: Hi
   Bob --> Alice: Hi back

或者用 .. plantuml:: directive 引用外部 .puml 文件——这样版本控制好（也方便 PR review 图源）。

Docusaurus（React 文档站）

Docusaurus 3.x 用 MDX，PlantUML 没官方插件。常见做法：

方案 A：MDX 内嵌

1
2
3
4
5
6

import PlantUML from "@site/src/components/PlantUML";

<PlantUML code={`
  Alice -> Bob: Hi
  Bob --> Alice: Hi back
`} />

PlantUML 组件调 plantuml-encoder 拼 plantuml.com URL 实时显示。

方案 B：预生成静态

你写一个 build 脚本：扫 docs/**/*.puml → 调 plantuml CLI → 输出 static/img/uml/*.svg → MDX 里 <img src="/img/uml/xxx.svg">。

选哪个？

共同的踩坑

1. plantuml.com 跨境

中国大陆 CI 翻墙是个问题：

• travis-ci / GitHub Actions 海外 runner OK
• 自建 runner（国内）经常 fetch 失败
• 解法：站内自部署 plantuml server，docker image 一行 docker run -d -p 8888:8080 plantuml/plantuml-server

2. CJK 字体

所有方案都会有这个问题。puml 顶部加：

1

skinparam defaultFontName "Noto Sans CJK SC"

或者 skinparam defaultFontName "Source Han Sans SC"。

3. 图缓存

CI 上每次 build 都重新渲染——会爆慢。hexo 用 cache: false + cache: true 分场景（开发时不缓存、生产缓存）。MkDocs 也有 cache 选项。

4. 版本对齐

plantuml CLI 版本差异大（!include 行为、!theme 引入方式）。建议：

• Dockerfile 里固定 plantuml/plantuml:1.2024.x
• 在 README 写明依赖的 PlantUML 版本

小结

• Hexo → 预渲染
• MkDocs → 插件默认 plantuml.com，国内可用 docker 自建
• Sphinx → sphinxcontrib（reST directive 最干净）
• Docusaurus → MDX + plantuml-encoder（客户端）

下一步

• PlantUML 数据驱动 — 从数据库/API 实时生成图
• PlantUML 在 Hexo 博客里嵌入（服务端 / 客户端两套方案）