---
title: "Draw diagrams as code · Agent Wranglers"
url: https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/diagrams-as-code
id: DOC-46
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 752
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Draw diagrams as code

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [README and docs as code](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: DOC-46
- Level: Recommended
- Chapter: [README and docs as code](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code.md)
- Rule: Write diagrams as text in the repository, with a diagram language such as Mermaid, PlantUML or D2, never only as an exported image.
- 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.
- How: 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. Update each diagram with its code, as [Change the docs in the same pull request](https://agentwranglers.se/playbook/engineering/version-control-and-review/docs-with-the-change.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Mermaid example

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

## Related rules

- TKO-5 [Map the system before changing it](https://agentwranglers.se/playbook/codebase-takeover/triage/system-map.md) in Codebase takeover
- DOC-40 [Keep one architecture overview with a context view and a container view](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/architecture-overview.md) in Documentation
- ENG-29 [Change the docs in the same pull request](https://agentwranglers.se/playbook/engineering/version-control-and-review/docs-with-the-change.md) in Engineering

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/diagrams-as-code">Agent Wranglers documentation playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep one architecture overview with a context view and a container view](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/architecture-overview.md)
- Next: [Keep a first-week guide for new team members](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/onboarding-guide.md)
- [README and docs as code](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code.md)