Get started

How a diagram is drawn

What happens to a diagram between the text you write and the picture you see: it is checked, laid out, drawn, described, and placed in your document. It is for anyone who wants to know why a diagram looks the way it does, and what to expect when something goes wrong.

TL;DR

Question	Answer
What do I write?	Plain text, one statement per line. You choose what a thing is (a database, a gateway), never how it looks.
What if I make a mistake?	Every mistake is reported at once, each with a line, a column, and a hint. Nothing is drawn until the source is valid.
Who picks the colors?	The theme, in a light and a dark version, so contrast holds in both and diagrams from different authors match.
Does the picture depend on a font or a browser?	No. The SVG carries its own colors and measured text, so it looks the same on GitHub, in an editor, or as a file.
Can text overflow a box?	No. Boxes grow to fit their text. Text is cut only past a hard limit, and a warning says so.
How does it reach my document?	`sync` writes the picture files and a picture block under the fence.

1. The stages

From text to picture: 8 nodes, 8 connections. Source text is checked, laid out, drawn as SVG, described in words, and written into the document.

2. What each stage does

Stage	What happens	What you see
Check	The text is read against the language. Unknown words, missing pieces, and unbalanced blocks are found.	Errors with a line, a column, and a hint, and warnings for a diagram that is too dense or too wide.
Layout	Each box is sized from the measured width of its text. Flow and schema diagrams route connectors at right angles. Sequence diagrams run on a timeline.	Boxes exactly as large as their text needs, with the same padding on both sides.
Draw	The layout is painted as SVG using the theme's colors for the light and the dark version.	Two files: `<id>.svg` and `<id>.dark.svg`.
Describe	The diagram is written out in reading order.	The picture's alt text, and the collapsed "Text description" under it.
Place	`sync` inserts a picture block under the fence in your Markdown file.	The picture in your document. See Diagrams in Markdown and on GitHub.

3. Why it works this way

Decision	What it means for you
You choose meaning, not color	An agent can write `database` or `gateway` and the look follows. Contrast is the theme's job, in both modes.
One statement per line, labels in quotes	A mistake has an exact position, and punctuation in a label never breaks the syntax.
Colors are fixed in the SVG	GitHub shows the picture through an image tag, where page styles and variables do not reach.
Text is measured, and boxes grow	A long label makes a wider box. A substitute font cannot make text spill out of one.
Warnings instead of silent fixes	A diagram that is too dense or too wide is a problem for its author, so you are told, with a hint.
The same source gives the same picture	The result does not depend on the machine that drew it.
The picture block records a fingerprint	If the diagram or the renderer changes, `sync --check` reports the picture as stale, so a document never shows an old drawing.

4. When something looks wrong

Symptom	Cause	Fix
Nothing is drawn and `validate_diagram` lists errors	The source has mistakes	Fix each one using its line, column, and hint.
A label ends in an ellipsis (warning `W203`)	The text was longer than the hard limit	Shorten it, or move detail into `sub=` or the prose around the diagram.
The diagram looks small (warning `W202`)	It is wider than a Markdown column	Use `direction=down`, shorten labels, or split it.
The document shows an old picture	The picture block is stale	Ask your agent to sync the file again, or call `sync_markdown` with it.

Doc	Why
Writing diagrams	The language by example
Diagrams in Markdown and on GitHub	The sync step in use
Language reference	Every word the language accepts

TL;DR

1. The stages

2. What each stage does

3. Why it works this way

4. When something looks wrong

See also