Diagram-as-Code — Version-Controlled Visual Documentation

In this tutorial, you will learn about Diagram. We cover key concepts, practical examples, and best practices to help you master this topic.

Diagram-as-code means writing diagrams in text files using declarative syntax and rendering them as images, keeping visual documentation in version control alongside code.

In this tutorial, you will learn Mermaid deep dives including C4 diagrams, PlantUML for UML modeling, Structurizr for software architecture, D2 for concise diagrams, and how to integrate diagram generation into CI-CD pipelines.

What You'll Learn

By the end of this guide, you will be able to create maintainable diagrams using Mermaid, PlantUML, Structurizr, D2, and Python-based diagram tools. You will understand how to version-control diagrams, render them in CI pipelines, and embed them in documentation.

Why It Matters

Traditional diagram tools produce binary files that cannot be diffed or reviewed in pull requests. Diagram-as-code enables peer review, automated testing, and seamless updates — exactly like software code.

Real-World Use

DodaZIP's compression module documentation uses Structurizr C4 diagrams generated on every commit. The CI pipeline rejects pull requests that do not update architecture diagrams when the module structure changes.

flowchart LR
  A[Write Diagram Syntax] --> B[Store in Git]
  B --> C[Review in PR]
  C --> D[CI Renders Diagram]
  D --> E[Embed in Docs]
  E --> F[Update as Code Changes]
  F --> A
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Teacher Mindset

Think of diagram-as-code as treating visuals like tests. You would not draw a test on a whiteboard and photograph it. You write the test, commit it, and run it automatically. Diagrams deserve the same discipline. The initial effort of learning syntax pays off every time someone reviews a Pull Request and sees exactly what changed in the architecture.

Common Mistakes in Diagram-as-Code

1. Skipping the Learning Curve

Mermaid and PlantUML have unique syntax rules. Jumping into complex diagrams without reading documentation leads to frustration. Start with simple flowcharts and progress to advanced types.

2. Not Versioning Diagram Source Files

Generating diagrams from code but not committing the source images defeats the purpose. Always commit the source text and generate images during build.

3. Overcomplicating with Too Many Tools

Using Mermaid for flowcharts, PlantUML for UML, and D2 for everything else creates maintenance overhead. Standardize on one or two tools across your documentation.

4. Ignoring Rendering Output Size

Diagrams with small fonts or cramped layouts are unreadable. Configure font sizes, spacing, and dimensions in your diagram source to ensure readable output.

5. Not Testing Diagram Rendering

A syntax error in a diagram source file breaks the build silently. Add diagram rendering to your CI pipeline with tests that verify each diagram compiles without errors.

6. Mixing Diagram Tools in One Documentation Set

Inconsistent visual styles confuse readers. If you use Mermaid in one section and PlantUML in another, the different aesthetics make the documentation feel disjointed.

7. Forgetting Mobile and Print Rendering

Diagrams that render well on desktop may overflow on mobile. Test diagram rendering at multiple widths and consider responsive layout options.

Practice Questions

1. What is the primary advantage of diagram-as-code over GUI-based drawing tools? Version control and peer review. Text-based diagram sources can be diffed, reviewed in pull requests, and updated alongside code changes with no binary file conflicts.

2. When should you use Structurizr instead of Mermaid? Use Structurizr for C4 architecture diagrams that need hierarchical context — system context, containers, components, and code. Mermaid is better for simple flowcharts and sequence diagrams.

3. How do you handle diagram rendering in CI-CD? Install the diagram tool as a build dependency and run a rendering script that converts all diagram files to images. Fail the build if any diagram has a syntax error.

4. What is the role of D2 in the diagram-as-code ecosystem? D2 is a newer diagram language that emphasizes concise syntax and automatic layout. It competes with Mermaid for simplicity while offering better default layouts.

5. Challenge: Take an existing architecture diagram from an open-source project and rewrite it using Mermaid, PlantUML, and Structurizr. Compare the syntax and output quality for each approach.

FAQ

Which diagram-as-code tool should I start with?

Start with Mermaid. It has the lowest learning curve, the best documentation, and native support in GitHub and GitLab Markdown rendering.

Can I use diagram-as-code for non-software diagrams?

Yes. Mermaid supports Gantt charts for project management, timeline diagrams, and git branch visualizations. PlantUML covers wireframes and mind maps.

How do I handle large diagrams in diagram-as-code?

Split large diagrams into multiple files and use includes or references to compose them. Avoid putting more than 15 to 20 nodes in a single diagram.

Does diagram-as-code work with static site generators?

Yes. Hugo, Docusaurus, and the DodaTech Python generator all support Mermaid rendering. PlantUML and Structurizr require a build-time image generation step.

What is the C4 model and why does it matter for diagram-as-code?

The C4 model provides a hierarchical approach to software architecture diagrams — Context, Containers, Components, and Code. Structurizr implements C4 natively and keeps each level consistent.

Mini Project

Set up a CI pipeline for an open-source project that generates diagrams from Mermaid and PlantUML sources on every commit. Write a GitHub Actions workflow that renders diagrams, fails on syntax errors, and deploys the images to GitHub Pages.

What's Next