Guides

Short reads on getting the most out of Mermaid Preview and Mermaid in general. We add new guides as we hit interesting questions in real projects, not on a content schedule.

Why text-based diagrams beat drag-and-drop in a code base — A short argument for keeping diagrams as text — version control, code review, fewer broken images, and faster iteration.
Embedding Mermaid in a GitHub README — How to add a Mermaid diagram to a README so GitHub renders it inline, plus the limits to know about before you commit.
Mermaid in Notion, Obsidian, and GitBook — Three notes-and-docs tools that render Mermaid natively, the quirks that come with each, and how to draft diagrams once and embed everywhere.
Mermaid in Hugo, Jekyll, and VuePress — Three popular static site generators and the dance you need to do for each so Mermaid diagrams in your Markdown actually render in production.
Flowchart vs sequence diagram — which one when — A short decision guide for the two most-used Mermaid diagram types. The trick is recognising whether your story is about steps, or about who-talks-to-whom.
Mermaid theme customisation — The four built-in themes, how to switch between them, and how to push past the defaults with theme variables when the built-ins are not quite right.
Common Mermaid parse errors and how to fix them — A field guide to the parse errors you will hit in your first month with Mermaid, and the small syntax adjustments that resolve each one.
A Mermaid syntax style guide — Conventions for naming, indentation, comments, and line lengths that keep your team's Mermaid diagrams reviewable in a pull request and pleasant to edit a year later.
From whiteboard photo to Mermaid diagram — A pragmatic workflow for converting that photo of a whiteboard into a Mermaid diagram you can actually maintain — without redrawing it five times.
Sharing Mermaid diagrams in code review — How to use Mermaid effectively in a pull-request review — embedding the diagram, suggesting edits inline, and avoiding the bikeshed about layout.