The Incus RKE2 cluster documentation is authored in AsciiDoc and rendered locally. Diagrams are produced with PlantUML and checked into version control as SVGs so published docs never depend on an external diagram rendering service.
All required tooling (Asciidoctor, PlantUML, Graphviz, Node.js) lives in the docs Flox environment. Activate it before building anything:
# @codebase
flox activate --dir docs-
Edit prose: update the
.adocfiles underdocs/as needed. -
Update diagrams: modify the
.pumlsources, then regenerate the SVGs so they remain committed alongside the prose. -
Preview locally: use the AsciiDoc VS Code extension (or any editor with built-in preview) to render the pages.
The Makefile layer encapsulates PlantUML invocations and stores outputs in docs/images/. Regenerate everything after changing any .puml source:
# @codebase
make diagrams@plantuml # alias: make docs-diagramsOnly committed SVGs under docs/images/ should be referenced from .adoc files via image::images/<name>.svg[].
After activating the docs Flox environment, open the repository in VS Code, install the AsciiDoc extension, and use the built-in preview (AsciiDoc: Open Preview to the Side). PlantUML diagrams resolve immediately because the SVGs are committed under docs/images/.
-
docs/images/– committed SVG artifacts generated from PlantUML. -
docs/*.puml– system and C4 diagrams that feed the SVGs. -
docs/.asciidoctorconfig– shared Asciidoctor attributes (table of contents, syntax highlighting, etc.). -
make diagrams@plantuml– render/update every committed SVG used by the docs.
-
Create a
.pumlfile underdocs/(or extend an existing one). -
Reference the generated SVG in the relevant
.adocfile usingimage::syntax. -
Run
make diagrams@plantumland commit both the updated.pumland resulting SVG indocs/images/. -
Rebuild the HTML to validate the rendered output locally.
Keeping SVGs checked in ensures reviewers and automation can diff both prose and visuals without relying on remote services.