Diagrams

There are two ways to put a diagram on a page, and they are not rivals. Mermaid is text: a fenced code block inside the Markdown, so the diagram travels with the sentence it illustrates and every change to it lands in the diff as changed lines. draw.io is a canvas: a real diagramming tool with shapes, layers, and pixel-precise positioning, stored as files beside your pages.

	Mermaid	draw.io
Lives in	The .md file itself	Two files in the project’s _attachments/
Edited with	Any text editor, or the editor’s source view	The bundled draw.io canvas — in the DocuCommit editor only
Reads as a diff	Yes — a few changed lines	Not usefully; both files are text, but machine-written
Best for	Flowcharts, sequences, state and ER diagrams	Architecture boards, network maps, custom shapes, exact layout
Survives PDF and HTML export	No — the fence exports as a code block	Yes — embedded into the export as an image

The rule of thumb: if a reviewer should be able to see what changed, write Mermaid. If the picture needs to look exactly a certain way, draw it.

Mermaid

A fenced block tagged mermaid becomes a diagram. Mermaid 11 renders it in the browser with the neutral theme and the strict security level, on both surfaces — the editor and the read-only server. A diagram that does not parse is replaced by an inline error box rather than a gap, so a typo is visible instead of silent.

```mermaid
flowchart LR
  Draft --> Review --> Publish
```

The syntax itself is Mermaid’s own and is not documented here. Markdown reference covers how the fence is recognised and what the renderer does with it.

Creating a draw.io diagram

In the editor’s toolbar, open Diagram and choose Create diagram. A dialog called Insert a new diagram opens with a Name field and the full draw.io canvas below it. Draw, then press Save diagram. Cancel throws the canvas away.

Save diagram writes two files immediately — the diagram’s source and a rendered SVG of it — and drops an image into the document at your cursor. The document itself is still unsaved at that point: the image reference reaches the .md file only when you press the document’s own Save, exactly as with any other edit.

The Name you type becomes the file name, lowercased, with spaces and separators turned into single hyphens and anything else dropped. System Architecture becomes system-architecture.

It is genuinely offline

The draw.io editor is not an embed of a website. A full copy of jgraph/drawio v30.2.6 (Apache Licence 2.0) ships inside the editor and is served by the application itself, with draw.io’s own offline and stealth flags set. It contacts no network host — not diagrams.net, not a CDN, not a font server. Nothing you draw leaves your machine, and the canvas works on a disconnected laptop exactly as it does online.

How a draw.io diagram lives in your repository

Every diagram is a pair of files in the project’s _attachments/ folder: the .drawio source you re-open to edit, and the .svg readers actually see.

my-project/
├── index.md
├── architecture.md
└── _attachments/
    ├── system-architecture.drawio    # the source — reopened by the editor
    └── system-architecture.svg       # the rendering — what readers see

Both are ordinary files, so both are committed by Save a snapshot along with the prose that explains them. That is the whole point: a diagram and the page it belongs to move through history together. Checking out last quarter’s tag gives you last quarter’s diagram, not today’s.

The SVG is produced by draw.io itself at the moment you press Save diagram, not later by the server. The server has no diagram editor and never re-renders anything — it serves the .svg file the editor already wrote.

Re-opening and renaming

Open Diagram again and the dropdown grows two groups, Insert and Edit, each listing diagrams by name. Edit reloads that diagram’s .drawio source into the canvas, under a dialog title of Edit followed by the diagram’s name. Insert places an existing diagram’s image again.

Both lists are built from the diagram images already present in the document you have open, not from everything in _attachments/. A diagram drawn on one page does not appear in another page’s menu — to reuse it there, reference its .svg by hand like any other image.

Changing the Name while editing renames the diagram: the new pair is written, the old .drawio and .svg are deleted, and the image in your document is pointed at the new file. Both the deletion and the addition land in your next snapshot.

What exports do with them

This is the one place the two kinds diverge sharply, and it decides which to use for anything destined for a PDF.

• draw.io survives. The diagram is an image file under _attachments/, so a self-contained HTML or PDF export embeds it as a base64 data URI. The exported file needs nothing else to display it.
• Mermaid does not. Mermaid runs in the browser, and an export is not a browser. PDF and HTML exports contain the raw fenced source in a plain code block where the diagram would have been.

So a Mermaid flowchart is perfect for a page people read on the server and terrible for a page people hand to an auditor as a PDF. Nothing warns you about this at export time, which is the main reason to know it in advance.

Worth knowing

• draw.io editing is editor-only. The server, the export, and any other tool see a finished SVG. Editing a diagram means opening its page in the editor.
• The inserted image has empty alt text. The editor writes ![](…) and leaves the description to you, exactly as it does for an uploaded picture. See Images and attachments.
• Nothing garbage-collects a diagram. Deleting the image from a page leaves both files in _attachments/. Remove them yourself if you want them gone.
• A conflicting diagram does not merge sensibly. Both files are technically text, so the merge screen will show them side by side — as machine-generated XML nobody can review. Pick a side and redraw if you have to. See Resolve conflicts for how that screen works.