Diagrams

Monofile renders mermaid diagrams inside markdown files, so a diagram lives in the same file as the prose that explains it. To move boxes around by hand, convert the same mermaid source into a drawing you can edit.

Mermaid in a markdown file

A fenced code block tagged mermaid renders as a diagram. Type /mermaid at the start of an empty line to insert an empty block, or paste a fence you already have.

Each block has two states. You normally see the rendered diagram. Click the edit button on the block to show the mermaid source, change it, then press Escape or click away to return to the diagram. The block has two more buttons. One zooms the diagram to full size, and one copies the whole fenced block so you can paste it elsewhere.

Diagrams follow your theme. Pick a dark theme and mermaid renders dark, with no per-diagram configuration.

Sequence diagrams work the same way, and suit anything that happens in an order:

The diagram is part of the markdown, so it also renders in a share link, in an embed, and on pages like this one.

When mermaid will not parse

Mermaid is strict. When a diagram fails to parse, Monofile retries once with one fix applied: it quotes unquoted flowchart labels, the most common mistake. If it still fails you get a card headed "Diagram rendering failed", the error under it, and your raw source below that. A parse failure reports "Invalid mermaid syntax".

A diagram that previously rendered stays on screen while you retype, so you do not see an error on every keystroke. While the AI assistant is still writing a diagram, you see "Generating diagram..." instead of an error.

Keeping a diagram legible

These are the rules Monofile applies to the diagrams it generates. They apply equally to diagrams you write by hand:

Rule	Why
Around 25 nodes is the ceiling	Past that, split it. One overview with 5 to 8 boxes plus a diagram per path beats one mega-graph
Labels under 30 characters	Put the technology in parentheses, as in `Cache (Redis)`
`TD` for layers, `LR` for pipelines	Clients at the top, data stores at the bottom. Left to right for sequential stages
Group with subgraphs, nested at most one level	Make grouping explicit instead of relying on where the layout puts things
Two or three `classDef` styles at most	More colour reads as noise
Label an edge only when the relationship is not obvious	`on miss` earns its place, `calls` does not
Never draw a bidirectional pair	Pick the primary direction. If the reply matters, one dotted edge is enough
Numbered steps in a flowchart mean you wanted a sequence diagram	Use the right type instead of forcing the wrong one

Turning mermaid into a drawing

A .draw file is an editable drawing with shapes, arrows and text you can select, drag, restyle and add to. Converting mermaid into one gives you a hand-editable diagram without placing every box yourself.

Five diagram types convert:

Mermaid type	Written as
Flowchart	`flowchart TD` or `graph LR`, subgraphs included
Sequence diagram	`sequenceDiagram`
Class diagram	`classDiagram`
Entity relationship diagram	`erDiagram`
State diagram	`stateDiagram-v2`

The converter refuses any other type with a message instead of producing a flat picture, so the output always stays editable.

There are two ways to run a conversion. Ask the AI assistant for a diagram and it writes the mermaid and creates the .draw file for you. Or do it yourself from the terminal:

Terminal

monofile diagram /diagrams/architecture.draw --from ./architecture.mmd

The source can also come from standard input:

Terminal

echo "graph TD
  A[Start] --> B[Ship]" | monofile diagram /diagrams/flow.draw

Monofile stores the mermaid source alongside the drawing. Regenerating from the same source gives the same diagram. Once you move shapes by hand, the drawing is authoritative and the stored source is history. Source is limited to 50,000 bytes, and a parse error returns the line number so you can fix the mermaid and rerun.

Next steps

Markdown ReferenceEvery markdown feature Monofile renders, with examples.
DrawingsExcalidraw drawings stored as .draw files, drawn by hand or generated from mermaid.
The Markdown EditorLive WYSIWYG editing, slash commands, and how saving works.
The AI AssistantWhat the built-in assistant is, what it can touch, and the two modes.
CLI CommandsEvery command, flag, JSON output shape and exit code.