Diagrams and formulas
Mermaid, PlantUML, Graphviz, D2, Vega, formulas and more, drawn from fenced blocks on your Mac.
Diagrams drawn on the page
Write a diagram as text in a fenced code block and Kirbon draws it — in Visual, Preview, side by side, on Read Only pages, and when you print or export a PDF. The file keeps the text exactly as you wrote it, so GitHub, GitLab and every other editor see the same block.
| Notation | Fence |
|---|---|
| Mermaid — flowcharts, sequence, class, state, ER, Gantt, mind maps and more | mermaid |
| PlantUML, with the C4 library | plantuml, puml |
| Graphviz | dot, graphviz |
| D2 | d2 |
| Vega-Lite and Vega charts | vega-lite, vega |
| WaveDrom timing diagrams | wavedrom |
| nomnoml | nomnoml |
| Pikchr | pikchr |
| Svgbob (ASCII drawings) | svgbob, bob |
| Formulas in LaTeX | math |
The fence word can be in any case and may have more after it (```Mermaid title="flow"). Blocks inside lists, quotes and callouts stay code blocks.
Adding a diagram
- Type
/mermaid,/plantumlor/formulaand press Return, or choose Insert ▸ Mermaid Diagram, PlantUML Diagram or Formula. You start from a small example with its source open. - Type a fence such as
```d2in an empty line and press Return. - Or pick a notation in a code block’s language pop-up: the block becomes a diagram once the caret leaves it.
Editing a diagram
A click selects a diagram. Press Return, double-click it, or click Edit Source in its header: the source opens as a code block with the drawing under it, redrawn as you type. Esc, or clicking elsewhere, closes the source.
| With a diagram selected | |
|---|---|
| ⌫ | Removes the block (one Undo step) |
| ⌘C | Copies the block’s Markdown, fences included |
| Space | Shows the diagram in Quick Look |
Right-click a diagram for Edit Source, Copy Source, Copy Image (PDF and PNG, ready to paste into other apps) and Open Diagram, which shows it full size in Quick Look. In Preview and on Read Only pages the same menu is there, without Edit Source.
When a block can’t be drawn — a typo in the source, say — the page shows the source with the engine’s message above it. While you edit, the last good drawing stays under the source, dimmed, until the source draws again.
Light and dark, zoom and print
Diagrams follow the appearance: they’re redrawn in dark colours when the Mac switches to Dark. They’re vector drawings, so they stay sharp at any zoom and in print or PDF. A diagram wider than the text is scaled to fit; Open Diagram shows it full size.
Drawn on your Mac
The drawing engines come with Kirbon and run on your Mac. Nothing in your documentation is sent anywhere: Kirbon draws diagrams in a web view that is never shown and blocks every load it tries from the internet. macOS lets an app use such a web view only with permission for outgoing network connections, which is why Kirbon has that permission — see Privacy.
Because of that, PlantUML can’t download standard libraries: C4 is included, while others such as AWS or Azure show an error instead of drawing.
A drawing is kept on this Mac, so opening the page again shows it at once. Very large diagrams, and ones that take more than ten seconds, are shown as their source with a message.
Turning drawing off
Turn off Settings ▸ Editor ▸ Draw diagrams and formulas, and diagram blocks show as ordinary code blocks everywhere. Nothing changes in the files either way.