Use when architecture documentation needs to be delivered as a Word document, stakeholders request formal .docx artifacts instead of markdown, or compliance/audit requires rendered diagrams embedded in Word format
Converts architecture markdown with diagram code blocks into a polished Word document. Diagrams render via Kroki API and embed as PNG images. Supports any Kroki-supported diagram type (PlantUML, C4, Mermaid, D2, Graphviz, etc.).
Requires network access to reach kroki.io (or a local Kroki instance) for diagram rendering. Documents without diagrams render fully offline.
All paths below use $SKILL_DIR as shorthand for this skill's directory (the directory containing this SKILL.md file). Resolve it once from the path used to read this file, then substitute the absolute path directly into each command — shell variables do not persist between tool calls.
Copy this checklist and track progress:
- [ ] Step 1: Verify dependencies
- [ ] Step 2: Run the render script
- [ ] Step 3: Verify output
- [ ] Step 4: Deliver to user
Step 1: Verify dependencies
pip install -r "$SKILL_DIR/scripts/requirements.txt"
Requires: python-docx>=1.1.0, requests>=2.31.0, mistune>=3.0.0, Pillow>=10.0.0
Step 2: Run the render script
python3 "$SKILL_DIR/scripts/render-docx.py" <input.md> [-o output.docx]
| Option | Description | Default |
|---|---|---|
-o, --output | Output DOCX path | <input>.docx |
--kroki-url | Kroki instance URL | https://kroki.io |
--image-width | Max image width (inches) | 6.0 |
--template | Corporate .dotx template | None |
Step 3: Verify output
Run this programmatic check on the generated DOCX:
python3 -c "
from docx import Document
import sys
d = Document(sys.argv[1])
imgs = len(d.inline_shapes)
tables = len(d.tables)
headings = len([p for p in d.paragraphs if p.style.name.startswith('Heading')])
print(f'Headings: {headings}, Tables: {tables}, Images: {imgs}, Size: {len(d.paragraphs)} paragraphs')
" <output.docx>
Check: images > 0 (if source had diagrams), tables > 0 (if source had tables), headings > 0. Report any zeros to the user as a potential issue. Remind user to right-click TOC and select Update Field in Word.
Step 4: Deliver
Report the output path, file size, and verification counts to the user.
Kroki render error (400/422): The failing diagram type and error are printed. Check the diagram syntax. C4 diagrams must have !include <C4/...> or use the c4plantuml fence tag — otherwise they route to the wrong Kroki endpoint. Note: Kroki bundles specific renderer versions — bleeding-edge syntax may not be supported.
Connection error (cannot reach kroki.io): Either the network is down, blocked, or the service is unavailable. Self-host Kroki locally. For documents with Mermaid diagrams, a single container is not enough — use docker-compose:
# docker-compose.yml