Documentation Guide

Embed architecture diagrams in Markdown

Every architecture diagram in a README was accurate on the day someone exported it. This is about the export step — why it is the thing that rots your documentation, and what to put in the file instead.

Draw one freeKeeping docs in sync
9 min readFor data and platform engineers

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

91/2000• 2 credits left
Try:

No account needed · Editable canvas, not a picture

The export step is the bug

Take any repository with an architecture diagram in its README. Check when the image was last changed, then check when the infrastructure it describes was last changed. On most repositories those two dates are months apart.

This is not a discipline problem. Updating an embedded PNG means opening the source file in whichever tool produced it — assuming you can find it and still have access — editing, exporting, and committing a binary. Four steps, each easy to postpone. The diagram does not decay gradually; it stops being updated on a specific day, and because a stale diagram looks exactly like a current one, nobody finds out until someone acts on it.

The tell

A diagram that still shows a service you decommissioned is not a documentation problem. It is a signal that the cost of updating it exceeded the cost of leaving it wrong — which is a property of the workflow, not of the person who left it.

What actually works, and where

Three approaches, with honest limits.

Mermaid in a fenced block

Lives in the same file, changes in the same commit, renders natively on GitHub and GitLab. Excellent up to roughly fifteen nodes. Past that the generated layout stops being readable, and there is no way to say “these four belong in a zone”.

Committed PNG or SVG

Works everywhere, including Confluence and PDF exports. Also the version that goes stale, because nothing connects the file to the system it describes.

Hosted image with a stable URL

One Markdown line, renders anywhere Markdown renders, and the picture changes when the source does — no re-export, no commit. The trade-off is that it needs the source to stay reachable.

The line itself

Standard Markdown image syntax. No plugin, no HTML, nothing that breaks when the file is rendered somewhere other than where it was written:

## Architecture

![Customer analytics pipeline](https://datadef.io/api/embed/customer-analytics-pipeline)

The pipeline lands raw events in S3, sessionises them in dbt, and serves
`gold.customer_features` to the ML jobs.

Because the URL resolves to the current state of the canvas rather than to a file someone uploaded, editing the diagram updates every place it is embedded. The README, the Notion page and the Confluence space stop being three copies that disagree.

Platform by platform

WhereMarkdown imageNotes
GitHubYesAlso renders Mermaid in fenced blocks. Private repos still fetch public image URLs.
GitLabYesSame syntax; Mermaid supported in issues and wikis too.
NotionYesPaste the URL and choose Embed. Refreshes when the page reloads.
ConfluenceVia macroUse the Image or Iframe macro with the URL rather than uploading an attachment.
Docusaurus / MkDocsYesPlain Markdown, so it survives a static build with no plugin.

Letting an agent write the whole thing

If the diagram is embedded rather than pasted, the natural next step is not drawing it yourself. An agent with access to the repository can read the terraform, the dbt models or the notebooks, draw the architecture, and write the section around it — with the embed line already in place.

That is what the MCP server exists for: Claude Code, Cursor or VS Code create and edit the canvas directly, and the documentation they produce keeps matching it afterwards because the image is a reference, not a copy.

What to do on Monday

Pick the one diagram people actually look at — usually the platform overview in the main repository’s README. Check its last modified date against the last infrastructure change. If they are more than a month apart, replace the exported file with an embed and watch whether it stays right for a quarter without anyone maintaining it.

Draw one free, no account — or read keeping data documentation in sync for the wider problem.