PlantUML in documentation sites — Hexo, MkDocs, Sphinx and Docusaurus

Diagrams in docs sites — the best approach depends on the framework. Here are the actual configs for 4 popular tools.

Why does this need a dedicated post?

PlantUML source and rendered output are separate. That means docs sites have three embedding strategies:

Pre-render: At build time, generate SVG static files → embed with <img> (fastest, most reliable).
Client-side render: At runtime, call plantuml.com / your own server (flexible, slightly slower).
Mixed: Generally pre-render, but offer live preview when editing the source.

Below by framework.

Hexo (what you’re using)

Approach A: server-side pre-render (recommended)

Use hexo-renderer-plantuml:

1	npm install hexo-renderer-plantuml --save

_config.yml:

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

In a post:

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

At build time the plantuml CLI renders to SVG, embedded into HTML. Pros: pure static, fast load, SEO-friendly. Cons: build is slower (every diagram goes through Java/PlantUML).

Approach B: client-side live render

<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>

Pros: fast build, no rebuild to edit. Cons: depends on plantuml.com — your CI runner behind the GFW will choke.

Approach C: TeaVM client-side pre-render (compromise)

Drop plantuml.js into themes/<name>/source/js/ and have the page go through TeaVM:

Slow first load (TeaVM startup), then cached.
Fully offline — no external services.
Config takes more effort, see this site’s own setup.

MkDocs (Python docs site)

Plugin plantuml-markdown:

1	pip install plantuml-markdown

mkdocs.yml:

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

In a page:

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

Pros: supports local plantuml jar (also plantuml.com). Cons: defaults to an external service.

Sphinx (Python’s official docs system)

Plugin sphinxcontrib-plantuml:

1	pip install sphinxcontrib-plantuml

conf.py:

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

In a page:

.. uml::

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

Or use the .. plantuml:: directive to reference an external .puml file — better for version control (and PR reviewing diagrams).

Docusaurus (React docs site)

Docusaurus 3.x uses MDX; there is no official PlantUML plugin. Common workarounds:

Approach A: embed in MDX

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

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

The PlantUML component calls plantuml-encoder to construct a plantuml.com URL and displays it live.

Approach B: pre-generate static assets

Write a build script: scan docs/**/*.puml → call plantuml CLI → emit static/img/uml/*.svg → in MDX, <img src="/img/uml/xxx.svg">.

Which one to choose?

Framework	Recommended approach	Why
Hexo	pre-render	Build isn’t slow, output is the fastest
MkDocs	plantuml.com plugin	Active plugin, lots of docs examples
Sphinx	sphinxcontrib	Native reST directive, reST users are happy
Docusaurus	MDX + encoder	Client-side by default, zero build burden

Common pitfalls

1. Cross-border with plantuml.com

CI in mainland China hits a wall:

travis-ci / GitHub Actions overseas runners: OK.
Self-hosted runners inside China: frequent fetch failure.
Fix: self-host a plantuml server in your stack. One-line docker image: docker run -d -p 8888:8080 plantuml/plantuml-server.

2. CJK fonts

All frameworks run into this. At the top of every puml:

1	skinparam defaultFontName "Noto Sans CJK SC"

Or skinparam defaultFontName "Source Han Sans SC".

3. Diagram caching

CI rebuilds rerender every diagram — that’s painfully slow. hexo offers cache: false / cache: true toggles (no cache during dev, cache in prod). MkDocs has cache options too.

4. Version skew

PlantUML CLI versions differ wildly (!include behaviour, !theme import syntax, etc). Fix:

pin plantuml/plantuml:1.2024.x in Dockerfile.
document the required PlantUML version in README.

Recap

Hexo → pre-render.
MkDocs → plugin, default plantuml.com; in CN, self-host via docker.
Sphinx → sphinxcontrib (cleanest reST directive).
Docusaurus → MDX + plantuml-encoder (client-side).