PlantUML export post-processing: SVG to PDF / PPT / Markdown embedding

PlantUML outputs SVG by default, but real projects need to embed diagrams in PDF, PPT, Word, Notion, and enterprise wikis. This is the post-processing script collection, foot-guns, and performance trade-offs.

Three core output formats

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# default SVG
plantuml -tsvg diagram.puml
# output: diagram.svg — vector, web-friendly

# PNG (bitmap)
plantuml -tpng diagram.puml
# output: diagram.png — for SVG-unaware environments

# PDF
plantuml -tpdf diagram.puml
# output: diagram.pdf — papers, reports

# LaTeX (embed in papers)
plantuml -tlatex diagram.puml
# output: diagram.tex — TikZ source, compile with pdflatex

# EPS (legacy LaTeX)
plantuml -teps diagram.puml

SVG is the default and best — vector, selectable text, any color depth. PNG/PDF are compatibility fallbacks.

SVG embedding in Markdown

GitHub / GitLab

1

![architecture](docs/diagrams/architecture.svg)

GitHub renders SVG directly, vector, sharp at any zoom. GitLab same.

Hexo / Hugo (local static blogs)

See [plantuml-render-from-hexo]; the recommendation is to use hexo-renderer-plantuml to pre-render at build time.

Notion

Notion does not accept direct SVG upload; convert to PNG first:

1

plantuml -tpng -Sresolution=300 diagram.puml

Sresolution=300 produces 300 DPI PNG, sharp after Notion’s compression. 300 DPI output is exactly what Notion needs.

Confluence

Confluence accepts SVG direct upload but sometimes force-converts to PNG for display. To embed the raw SVG:

1
2
3
4
5

<ac:structured-macro ac:name="html">
  <ac:plain-text-body><![CDATA[
    <object data="diagram.svg" type="image/svg+xml"></object>
  ]]></ac:plain-text-body>
</ac:structured-macro>

SVG → PNG high-DPI export

Default -tpng outputs 96 DPI — blurry when zoomed. Boost resolution:

1
2
3
4
5

# 200 DPI
plantuml -tpng -Sresolution=200 diagram.puml

# PNG with transparent background
plantuml -tpng -SbackgroundColor=transparent diagram.puml

Batch script:

1
2
3
4
5
6
7
8
9
10

#!/bin/bash
# render-hi-dpi.sh
RES=300
mkdir -p out/hi-dpi
for puml in docs/diagrams/*.puml; do
  base=$(basename "$puml" .puml)
  docker run --rm -v $(pwd):/data plantuml/plantuml \
    -tpng -Sresolution=$RES \
    "/data/$puml" -o "/data/out/hi-dpi/${base}.png"
done

SVG → PDF for LaTeX papers

PlantUML’s -tpdf outputs PDF directly, quality is good. But:

• LaTeX \includegraphics clips by default → use width=\textwidth explicitly
• Font may not match paper body → use -SdefaultFontName=Times to force serif

1
2
3
4
5
6

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.8\textwidth]{diagrams/sequence.pdf}
  \caption{User login sequence}
  \label{fig:login-sequence}
\end{figure}

-tlatex outputs TikZ source, can be \input directly into the paper, text uses the paper’s font. But -tlatex does not support every PlantUML feature (complex component / deployment diagrams sometimes error out).

SVG → PPT for presentations

PowerPoint doesn’t support SVG; must convert to PNG:

1

plantuml -tpng -Sresolution=300 diagram.puml

Auto-embed into PPT script (python-pptx):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

from pptx import Presentation
from pathlib import Path
import subprocess
from pptx.util import Inches

prs = Presentation()
for puml in Path("diagrams").glob("*.puml"):
    subprocess.run([
        "docker", "run", "--rm", "-v", f"{Path.cwd()}:/data",
        "plantuml/plantuml", f"/data/{puml}", "-tpng", "-Sresolution=300"
    ], check=True)
    slide = prs.slides.add_slide(prs.slide_layouts[5])
    slide.shapes.add_picture(
        f"diagrams/{puml.stem}.png",
        left=Inches(0.5), top=Inches(0.5),
        width=Inches(9), height=Inches(6))
prs.save("diagrams.pptx")

Font consistency — PPT uses Calibri by default; PlantUML defaults to DejaVu Sans. After export, slide text and diagram text use different fonts. Fix:

1

plantuml -tpng -SdefaultFontName="Calibri" -SdefaultFontSize=14 diagram.puml

Embedding in Word / Office

Word 2016+ supports SVG paste: copy the SVG file → Ctrl+V in Word → embeds as scalable vector image.

But Word renders SVG with IE compatibility mode, some PlantUML CSS3 features may not display. Safe path: PNG in Word, 300 DPI:

1

plantuml -tpng -Sresolution=300 diagram.puml

SVG optimization (smaller files)

PlantUML’s default SVG has lots of metadata, comments, empty elements. For production use SVGO:

1
2

npm install -g svgo
svgo -i input.svg -o output.min.svg

40-60% size reduction, but all comment text gets stripped — if the diagram has note left of Alice: remember, the note will not render.

svgo config that preserves comments (svgo.config.js):

1
2
3
4
5
6
7

module.exports = {
  plugins: [
    { name: 'removeComments', active: false },  // keep comments
    { name: 'removeMetadata', active: true },
    { name: 'removeXMLNS', active: false },     // keep namespace
  ]
};

Dark mode adaptation

PlantUML defaults to white background + black text. When the blog has dark mode, SVG doesn’t auto-adapt.

Fix: render twice, JS swaps based on theme:

1
2

plantuml -tsvg -SbackgroundColor=transparent -Scolor=white diagram.puml    # dark
plantuml -tsvg -SbackgroundColor=transparent -Scolor=black diagram.puml    # light

1
2
3
4

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="diagram-dark.svg">
  <img src="diagram-light.svg" alt="diagram">
</picture>

prefers-color-scheme: dark auto-switches. Way better than CSS filter:invert (the latter turns blue into orange — ugly).

Performance: bulk export

100+ .puml files, spinning up Docker per file is slow. Parallel:

1
2
3
4

# GNU parallel
ls docs/diagrams/*.puml | parallel -j 8 \
  "docker run --rm -v $(pwd):/data plantuml/plantuml \
   -tsvg /data/{} -o /data/out/"

xargs -P:

1
2

ls docs/diagrams/*.puml | xargs -P 8 -I {} \
  sh -c 'docker run --rm -v $(pwd):/data plantuml/plantuml -tsvg /data/{} -o /data/out/'

Or hit plantuml-server once per file:

1
2

PUML=$(cat diagram.puml | base64 -w0 | sed 's/+/-/g;s/\//_/g/')
curl "http://localhost:8080/svg/~1${PUML}" -o diagram.svg

~1 is the HUFFMAN encoding prefix plantuml.com switched to (post-2025).

Failure cases

• SVG doesn’t show in Outlook email: Outlook’s Word rendering engine doesn’t recognize SVG. PNG only, 300 DPI.
• LaTeX \includegraphics reports “File not found”: PlantUML PDF output needs font embedding; LaTeX side requires pdflatex to eat the PDF. xelatex works too. lualatex frequently complains about fonts.
• Notion SVG is blurry: Notion scales SVGs to a fixed size. Add width=100% so the SVG is responsive itself — don’t use fixed width.
• Diagram distorts in PPT: python-pptx scales by original pixel ratio, may not match PPT 16:9. Manually set width=Inches(9) height=Inches(6).
• CI renders Chinese as garbage: PlantUML’s default DejaVu Sans has no CJK. Install fonts-noto-cjk on the server, plantuml uses -SdefaultFontName=Noto Sans CJK SC.