Direct answer
Mermaid is useful when you want fast, text-based diagrams for docs, architecture notes, and workflows.
The code below is ready to paste into Markups. Wrap each block in a fenced code block with the
mermaid language tag and the preview will render the diagram live.
Flowchart
```mermaid graph TD A[Idea] --> B[Draft] B --> C[Preview] C --> D[Publish] ```
Sequence diagram
```mermaid sequenceDiagram participant U as User participant M as Markups U->>M: Write markdown M-->>U: Render preview ```
Gantt timeline
```mermaid gantt title Markdown workflow dateFormat YYYY-MM-DD section Writing Drafting :a1, 2026-04-26, 2d Review :after a1, 1d Publish :after Review, 1d ```
Entity-Relationship diagram
```mermaid
erDiagram
USER ||--o{ POST : writes
POST ||--|{ COMMENT : has
USER ||--o{ COMMENT : authors
```
Class diagram
```mermaid
classDiagram
class User {
+id: int
+name: string
+email: string
}
class Post {
+id: int
+title: string
+author: User
}
User "1" --> "*" Post : writes
```
State diagram
```mermaid stateDiagram-v2 [*] --> Draft Draft --> Review Review --> Published Published --> [*] ```
Pie chart
```mermaid pie showData title Documentation effort "Drafting" : 40 "Reviewing" : 25 "Publishing" : 20 "Maintenance" : 15 ```
How to write better diagram-driven documentation
Use one diagram per idea. Start with a simple flow first, then add detail only if it changes a decision. For system docs, pair each Mermaid block with a short explanation of assumptions, input, and output. This keeps your page usable for both engineers and non-technical reviewers.
If a diagram becomes too dense, split it into multiple sections. Smaller diagrams are easier to maintain and easier to understand in exported PDF or HTML formats. For more on building clear docs, see the markdown cheatsheet.
Tips for clean Mermaid output
- Wrap the diagram in a fenced code block with
```mermaidfor the language tag. - Keep node labels short and consistent across the diagram.
- Avoid mixing too many diagram types in a single document.
- Use subgraphs to group related nodes in complex flowcharts.
- Preview often — Mermaid errors are usually obvious in the live preview.
- For sequence diagrams, name participants explicitly to keep the diagram readable.
FAQ
How do I write a Mermaid diagram in markdown? Wrap the syntax in a fenced code block
with the language tag mermaid. Markups renders the diagram in the live preview.
Do I need JavaScript to write Mermaid? No. You only need the markdown code block. Markups handles the rendering.
What diagram types are supported? Flowchart, sequence, Gantt, ER, class, state, pie, user journey, and more. Markups supports all of them.
Can I export diagrams to PDF? Yes. The PDF export renders Mermaid diagrams as part of the page, so they appear in the printable output.
What should I try next? Export the page to PDF or HTML after you confirm the diagram looks right.
Try these examples in Markups
Open markups.dev, paste any of the examples above, and watch the diagram render in real time. When the document is ready, export to PDF, HTML, or Markdown in one click. The editor is free for unlimited diagrams.
For more, see the markdown cheatsheet or math examples.