Documentation Recommended

Draw diagrams as code

Write diagrams as text in the repository, with a diagram language such as Mermaid, PlantUML or D2, never only as an exported image.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Text diagrams change in the same pull request as the code and show a readable diff. GitHub and GitLab draw Mermaid blocks inside Markdown. Render others to SVG in the build with their command-line tool. Keep one diagram per idea, with at most about 15 boxes.

Example

flowchart LR
  shop[Order page] --> api[Orders API]
  api --> db[(Orders database)]
  api --> kitchen[Kitchen screen]

How to check

The build renders every diagram source with its tool, such as mmdc for Mermaid, and fails on a syntax error. A search finds no .png or .svg diagram without a source file next to it.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/diagrams-as-code.