Repository navigation
feat: integrate drawio / mermaid / plantuml diagrams into .docx output #63
Description
Summary
Render diagrams authored via the three mature upstream Sphinx
extensions — sphinxcontrib-drawio, sphinxcontrib-mermaid,
sphinxcontrib-plantuml — as embedded PNG images in the .docx that
docxsphinx emits. Covers RST .. uml:: / .. mermaid:: /
.. drawio-image:: directives and MyST fenced-block equivalents.
Why
Diagrams are a first-class documentation artifact for architecture,
sequence flows, flowcharts, and entity relationships. Every other
mainstream Sphinx output format (HTML, LaTeX, PDF) supports them via
these three extensions. docxsphinx currently has zero support —
diagram nodes fall through to unknown_visit and are silently
dropped from the Word output.
Scope (MVP)
| Extension | Work required |
|---|---|
sphinxcontrib-drawio |
Zero code — produces standard nodes.image; existing visit_image handles it. |
sphinxcontrib-plantuml |
New visit_plantuml mirroring the extension's LaTeX-builder pattern — call its exported render_plantuml() helper, then delegate to visit_image. |
sphinxcontrib-mermaid |
New visit_mermaid — shell out to mmdc (mermaid-cli) to render PNG, then delegate to visit_image. |
pip install ".[diagrams]"extras bucket for the three extensions.- Dockerfile installs
plantuml(JRE),nodejs+@mermaid-js/mermaid-cli,
anddrawio(Debian electron desktop build) so
make example DIR=md_mermaid|md_plantuml|md_drawioworks out of
the box. Image size grows by ~500MB; accepted for dev convenience. - One new example project per format under
examples/. - Unit tests stub the CLIs; e2e + golden fingerprint tests exercise
the real rendering pipeline. - README gets a Diagrams section; CHANGELOG entry for 2.2.0.
Out of scope
- SVG-native embedding in
.docx(blocked on
python-docx PR #1386). - Bundling the three extensions into docxsphinx itself — they remain
user-installed deps. - A unified
```{diagram}directive — each extension already has
an idiomatic author surface.
Effort
~3.5 days end-to-end (½d drawio + docs, 1d plantuml, 1½d mermaid
including chromium-quirks time, ½d Docker + CI + README + CHANGELOG).
Reference
Full design notes, code sketches, file-by-file touch list, risks, and
verification steps are checked in at
.claude/plans/diagram-integration.md.
Activity