mermaid

Mermaid Diagram Standard

Mermaid is the default diagram format because the same editable text can render directly in GitHub Markdown and inside Slidev decks. Keep the source portable, reviewable, and close to the prose it explains.

Decision Boundary

• Use Mermaid for flowcharts, sequences, states, classes, entity relationships, timelines, mind maps, Git graphs, and other compact technical visuals.
• Use LikeC4 instead when the architecture model is the durable source of truth and must generate multiple consistent views.
• Use D2 instead for an existing D2 codebase or a bespoke standalone composition that Mermaid cannot express clearly.
• Omit the diagram when prose, code, a short list, or a table communicates the point more directly.

Workflow

1. State one visual thesis and the reader decision it supports.

2. Choose the simplest stable diagram type supported by every target renderer. Prefer flowchart, sequenceDiagram, stateDiagram-v2, classDiagram, and erDiagram for GitHub and Slidev portability.

3. Write the editable source as a fenced mermaid block when it belongs to one Markdown document, or as a .mmd file when it is reused or rendered independently.

4. Keep labels short, relationships explicit, direction intentional, and the node count small enough to read without zooming.

5. Use Mermaid frontmatter for configuration. Do not add deprecated %%{init: ...}%% directives to new diagrams.

6. Apply the Fmind theme from fmind-theme when the work represents Médéric or www.fmind.dev.

7. Validate and render locally:

   mmdc -i diagram.mmd -o diagram.svg -b transparent
   

8. Inspect the actual render for clipping, line crossings, contrast, spelling, label density, and mobile or slide readability.

9. Keep the Mermaid source. Add SVG by default only when the target cannot render Mermaid; add PNG only when a platform requires raster output.

Portable Embedding