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.

```mermaid
flowchart TD
  Client[Client] --> API[API gateway]
  API --> Svc[Files service]
  Svc --> DB[(Postgres)]
  Svc --> Cache[(Cache)]
```

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:

```mermaid
sequenceDiagram
  participant You
  participant Editor
  participant Server
  You->>Editor: type
  Editor->>Server: save
  Server-->>Editor: version captured
  Editor-->>You: saved
```

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.

> [!TIP]
> Almost every real failure is punctuation in a label. Quote it:

```mermaid
flowchart LR
  A["Cache (Redis)"] --> B["Queue (SQS)"]
```

## 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:

```bash title="Terminal"
monofile diagram /diagrams/architecture.draw --from ./architecture.mmd
```

The source can also come from standard input:

```bash title="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

:::cards
- [[Markdown Reference]] — Every markdown feature Monofile renders, with examples.
- [[Drawings]] — Excalidraw drawings stored as .draw files, drawn by hand or generated from mermaid.
- [[The Markdown Editor]] — Live WYSIWYG editing, slash commands, and how saving works.
- [[The AI Assistant]] — What the built-in assistant is, what it can touch, and the two modes.
- [[CLI Commands]] — Every command, flag, JSON output shape and exit code.
:::