Technical diagrams often become stale because editing them requires finding the original design file, opening a separate application, and exporting another image. Mermaid takes a different approach: the diagram is defined as text and stored beside the documentation.
To add Mermaid to Markdown, place the diagram definition inside a fenced code block with the mermaid language identifier. Use the Mermaid Diagram Preview to render the syntax locally, correct errors, copy the complete Markdown fence, or download an SVG.
This guide starts with a small flowchart and builds toward sequence, class, Gantt, mind map, and entity-relationship diagrams.
Mermaid in 30 Seconds
A basic Mermaid block looks like this:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
The opening fence tells a compatible renderer that the content is Mermaid syntax. flowchart LR selects a flowchart arranged from left to right. The remaining lines define nodes and connections.
If the destination does not support Mermaid, readers will usually see a code block instead of a diagram. That fallback preserves the source, but it is not a replacement for checking compatibility before publication.
Why Use Text-Based Diagrams?
Mermaid is especially useful when a diagram:
- belongs to version-controlled documentation;
- changes along with code or procedures;
- needs meaningful pull-request diffs;
- uses standard shapes and relationships;
- should be editable without a proprietary design file;
- must be regenerated in light and dark themes.
It is less suitable for detailed illustration, pixel-perfect layout, freehand annotation, or visual design requiring precise manual placement. In those cases, use a drawing tool and export an accessible SVG or image.
Example 1: A Flowchart
Flowcharts describe a process, decision, or routing rule.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Key syntax:
TDmeans top to bottom.LRmeans left to right.[Text]creates a rectangular process node.{Text}creates a decision node.-->creates a directional connection.-->|Label|adds text to a connection.
Use stable, short node IDs such as A or validate. Keep the visible label inside brackets so changing the wording does not require changing every connection.
Add a subgraph
Subgraphs group related steps:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Use subgraphs when the grouping communicates ownership, system boundaries, or phases. Do not add a box merely for decoration.
Example 2: A Sequence Diagram
Sequence diagrams show interactions in time order. They work well for API calls, authentication, browser workflows, and event-driven systems.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Common arrows:
->>sends a solid message.-->>sends a dashed response.participantdeclares a system or service.actordeclares a human or external role.autonumberlabels interactions in order.
Focus on one scenario. A sequence diagram that attempts to show every alternative and every internal function becomes harder to understand than the code.
Show an alternative path
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Use alt, else, and end for meaningful branches. If the branch requires several pages of explanation, link to prose below the diagram.
Example 3: A Class Diagram
Class diagrams describe types, properties, operations, inheritance, and relationships.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
This example states that MarkdownDocument inherits from Document. Use class diagrams for a conceptual model, not as an automatic replacement for complete API reference documentation.
Good class diagrams omit details that do not help the reader understand the design. Showing every private field can turn the diagram into a less searchable version of the source code.
Example 4: A Gantt Chart
Gantt charts show tasks across time. They are useful for release plans, migrations, and documentation projects.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Keep dates explicit and use task IDs when one task depends on another. Remember that a diagram stored in documentation will not update itself when the real project schedule changes. Assign ownership for keeping it current.
Example 5: A Mind Map
Mind maps organize ideas around a central topic.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Mind maps are most effective during planning or as a high-level overview. They are less useful for precise relationships because the tree structure can imply hierarchy where the real concepts overlap.
Example 6: An Entity-Relationship Diagram
ER diagrams describe data entities and their relationships.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Use an ER diagram to explain the model and a schema or migration file to define the implementation. A diagram may omit indexes, constraints, and fields that are not relevant to the current explanation.
Preview Mermaid Before Publishing
Writing diagrams directly in a long Markdown document makes syntax errors difficult to isolate. A focused preview loop is faster:
- Open the Mermaid Diagram Preview.
- Paste only the diagram definition, without the outer code fence.
- Render the diagram.
- Read any syntax error and correct the referenced area.
- Copy the generated fenced Markdown.
- Download the SVG when the destination needs a static asset.
- Test the final Markdown in its real platform.
The preview renders in your browser with a strict security configuration. Diagram callbacks and other interactive behaviors may be disabled even if another Mermaid installation permits them. That conservative behavior is appropriate for a general preview tool.
Common Mermaid Errors
The diagram type is missing
Incorrect:
A --> B
Correct:
flowchart LR
A --> B
The first line identifies the diagram grammar.
Punctuation in a label breaks parsing
Quote complex labels:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
This is particularly useful for parentheses, punctuation, and labels that resemble syntax.
A reserved word is used unexpectedly
Mermaid grammars have keywords. The official flowchart documentation specifically warns that lowercase end can break a flowchart. Capitalize it or place the visible text inside a quoted node label:
flowchart LR
Start --> Finish["End"]
The code fence is incorrect
The language identifier belongs immediately after the opening backticks:
```mermaid
flowchart LR
A --> B
```
Do not indent the complete fence unless the surrounding Markdown syntax requires it.
It works in one platform but not another
Mermaid evolves, and platforms can use different renderers, versions, security settings, and enabled diagram types. A syntax feature supported by the newest Mermaid release may fail in a platform using another implementation or older version.
Prefer widely supported syntax for documents that move between platforms. Test advanced shapes, themes, directives, and newer diagram types in every required destination.
Platform Compatibility
Compatibility should be tested rather than assumed:
| Platform | Current documented approach | Important note |
|---|---|---|
| GitHub | Use a fenced mermaid block | GitHub documents rendering in Markdown files, issues, discussions, pull requests, and wikis |
| GitLab | Use a Mermaid code block in GitLab Flavored Markdown | GitLab documents its supported Mermaid version; self-managed installations may differ |
| Obsidian | Use a fenced mermaid block in a note | Obsidian’s renderer and supported features can change between releases |
| Material for MkDocs | Configure a Mermaid custom fence | Native theme integration requires documented pymdownx.superfences configuration |
| Generic Markdown parser | Often displays code only | Mermaid rendering usually requires a JavaScript integration or build plugin |
Check the current official documentation before relying on a newer feature:
- GitHub: Creating diagrams
- GitLab Flavored Markdown
- Obsidian: Advanced formatting syntax
- Material for MkDocs: Diagrams
- Mermaid syntax reference
For a documentation site you control, pin the Mermaid dependency version and test upgrades. Otherwise, a minor syntax change can alter diagrams across the entire site.
Mermaid and Accessibility
A rendered SVG does not automatically communicate its meaning to every reader. Treat the diagram as a visual summary and provide an equivalent explanation in nearby prose.
For the earlier conversion flowchart, add text such as:
The user selects a DOCX file. Valid files are converted locally and displayed for review; invalid files produce an error. The user can then copy or download the reviewed Markdown.
Accessibility practices:
- introduce what the diagram explains;
- summarize the conclusion after complex diagrams;
- do not encode meaning with color alone;
- use readable labels rather than internal abbreviations;
- maintain sufficient contrast in light and dark themes;
- avoid diagrams that require precise mouse interaction;
- provide a text or table alternative for essential information;
- export SVG with care when the static file must carry an accessible name.
The source code is useful to authors, but it is not necessarily a good text alternative for readers.
Designing Diagrams That Stay Readable
Keep one purpose per diagram
A diagram should answer a question such as “What happens after a failed request?” or “Which service owns each data store?” If it attempts to explain the entire system, split it.
Prefer short labels
Put detailed explanations in prose. Long labels force narrow nodes, awkward line wrapping, and large diagrams on mobile screens.
Use direction intentionally
Left-to-right flow works well for short processes and request paths. Top-to-bottom flow often fits narrow screens better. Preview both before committing.
Limit visual styling
Custom colors can conflict with dark mode or platform themes. Begin with the renderer’s defaults. Add styles only when they communicate meaning and remain readable in all required themes.
Keep source near its explanation
Store the Mermaid block in the same Markdown file when possible. That makes the prose and diagram change together in one review.
Mermaid vs a Static Image
Choose Mermaid when:
- the diagram changes frequently;
- source diffs are valuable;
- the layout uses standard diagram types;
- the publishing platform renders Mermaid reliably.
Choose SVG or PNG when:
- the design requires precise manual layout;
- the destination does not render Mermaid;
- the exact appearance must remain fixed;
- external sharing requires a standalone asset.
A useful hybrid is to maintain Mermaid source and export an SVG for destinations that cannot render it. Keep the source beside the exported asset and document how to regenerate it.
Use Markdown to Image for shareable rendered Markdown content, or download SVG directly from the Mermaid Diagram Preview when the diagram itself is the asset.
FAQ
Is Mermaid part of standard Markdown?
No. A fenced mermaid block is an extension recognized by compatible applications and build systems. A basic Markdown parser may render it as ordinary code.
Does GitHub render Mermaid diagrams?
Yes. GitHub’s documentation describes Mermaid rendering in Markdown files and several collaboration surfaces. Test newer syntax because GitHub controls the deployed renderer and security settings.
Can I use Mermaid in Obsidian?
Obsidian’s official help documents Mermaid-style fenced diagram blocks in notes. Feature support can change with the application’s renderer, so verify complex or newly introduced diagram types in your installed version.
Can Mermaid replace architecture documentation?
No. A diagram is one view of a system. Pair it with decisions, ownership, constraints, failure behavior, and links to authoritative interfaces or schemas.
Why does my diagram render differently in dark mode?
Platforms may apply different Mermaid themes, CSS variables, fonts, and backgrounds. Avoid hard-coded colors until you have tested both themes.
Should I commit exported SVG files?
Commit an SVG when the publishing destination needs a static asset or the rendered result must remain stable. Also keep the Mermaid source and a documented regeneration process to prevent the two versions from drifting.
Is Mermaid safe for confidential diagrams?
Confidentiality depends on the editor and publishing workflow. WordToMD’s preview renders the diagram in your browser, but publishing the Markdown or SVG to a repository or site follows that destination’s access controls.
Conclusion
Mermaid makes diagrams maintainable because the source lives with the Markdown. Start with a small fenced block, choose the diagram type that matches the question, preview the syntax, and test it in the final renderer. Use prose to explain essential meaning and export SVG when a destination needs a static asset.
Try the examples in the Mermaid Diagram Preview, edit the surrounding documentation in the Markdown Editor, and keep the diagram focused enough that a future contributor can understand and update it without redrawing the entire page.