Situation. Your architecture, data flow or process needs a diagram. You want it to live in the repository, remain readable in a diff and rely on no online tool.
What you get at the end. A text-based Mermaid diagram, rendered locally, included in your documentation or exported as an image.
1. Start from a template
Choose File > New file (⌘N), then a Mermaid diagram.
The gallery offers the 28 recognized families, 16 recommended templates and search by purpose and type. Three customization fields let you adjust the starting point before creating the file.
If you do not know which family to choose, search for what you want to show rather than the technical name.
2. Build
There are two ways to work on the same file.
On the rendered diagram, click to select, double-click a node to change its label, double-click the background to add a node and press Delete to remove the selection. A separate handle creates relationships.
For structural editing, the left navigation lists the diagram’s declarations. Select one to edit its fields, use Add to insert, and Move up or Move down to reorder.
In Source mode, write Mermaid syntax directly.
3. Accept the calculated layout
Mermaid calculates the layout. Moving an element without a corresponding change in the grammar returns it to its calculated position.
This ensures the text file contains the whole diagram. To influence the layout, change the direction or declaration order.
4. Include the diagram in documentation
In a Markdown document, Insert opens the same gallery and places the diagram inside a fence chosen to avoid conflicts with the content.
For an existing block, Edit opens the same surface in a separate window. The draft stays isolated: Cancel leaves the document untouched, and Apply replaces only the block’s interior.
5. Export when you need an image
Copy the source, copy the image, or export SVG and PNG.
The exported image is the one sanitized for display: no scripts or active links.
Keep the .mmd in the repository even when delivering a PNG. You can regenerate the image; the text is what you can review and edit.
6. Build your library
Choose a local folder as your personal template library. Templates are ordinary .mmd or .mermaid files.
From an open diagram, Save copy as template… adds it there.
Forgetting the folder only removes Balise’s access, without deleting any files.
If something goes wrong
- Empty rendering, errors or editing unavailable: When a diagram does not appear
- Every command in detail: The Mermaid workspace