Markdown Isn’t Just for Text: 10 Mermaid Diagrams You Can Copy
Create flowcharts, timelines, sequence diagrams and more without leaving your Markdown file.
Mermaid turns a short block of text into an editable diagram inside Markdown. Open the file in a compatible Markdown viewer, and it renders as a flowchart, timeline, sequence diagram or another visual.
Here are ten practical examples you can copy and adapt.
The basic idea
A Mermaid diagram sits inside a fenced code block labelled mermaid:
```mermaid
flowchart LR
A[Write] --> B[Preview] --> C[Publish]
```
Here, flowchart LR creates a left-to-right flowchart, and the next line connects the three steps. A supporting viewer renders the diagram; other platforms show the source as code. Support varies by Mermaid version, especially for newer formats such as timelines and quadrant charts.
Compatibility: In practice, flowcharts and sequence diagrams have the widest support. GitHub, GitLab, Visual Studio Code and Obsidian can render Mermaid, while Medium works best with an exported diagram image and the source beneath it. You will find a fuller compatibility guide after the examples.
1. Map a process with a flowchart
Use a flowchart when the order of the steps matters or a decision creates different paths.
```mermaid
flowchart TD
A[Receive draft] --> B[Check facts]
B --> C{Ready to publish?}
C -->|No| D[Revise the draft]
D --> B
C -->|Yes| E[Publish]
```
TD means the diagram flows from top to bottom. Change it to LR when a left-to-right layout fits the page better.
Square brackets create ordinary process boxes. Curly braces create a decision. Labels between vertical bars explain why someone follows a particular arrow.
This is useful for approval processes, troubleshooting guides, onboarding instructions and operating procedures.
Compatibility: Flowcharts are the safest starting point. They are among Mermaid’s oldest and most widely supported diagram types.
I’m building Markdific because I wanted a better way to read, edit and preview Markdown files. It’s available for Mac, Windows and Linux if you’d like to try it.
2. Explain an interaction with a sequence diagram
A flowchart shows where a process goes. A sequence diagram shows who communicates with whom, and in what order.
```mermaid
sequenceDiagram
actor Reader
participant App
participant Renderer
Reader->>App: Open document.md
App->>Renderer: Send Markdown source
Renderer-->>App: Return formatted output
App-->>Reader: Display preview
```
In this example, solid arrows show requests or actions and dashed arrows show responses. Mermaid does not enforce that meaning, so the important thing is to use the styles consistently. Participants appear from left to right in the order in which you declare them.
Sequence diagrams are particularly good for API calls, login flows, payment processes and explaining what happens after someone clicks a button.
Compatibility: Sequence diagrams are broadly supported, although spacing and themes can differ. GitHub also documents a known issue where some sequence diagrams acquire extra space beneath the chart.
3. Show the lifecycle of something with a state diagram
A state diagram focuses on the condition of one object and the events that move it between states.
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> InReview: Submit
InReview --> Draft: Request changes
InReview --> Approved: Approve
Approved --> Published: Publish
Published --> Archived: Retire
Archived --> [*]
```
The [*] symbol represents the beginning or end. Text after a colon labels the transition.
Use this for document statuses, support tickets, subscriptions, orders or any object that moves through a defined lifecycle. It is usually clearer than drawing a general flowchart when your real subject is a set of states.
Compatibility: stateDiagram-v2 works in modern Mermaid releases. A particularly old integration may understand only the older stateDiagram renderer, so preview it before publishing.
4. Plan work with a Gantt chart
Gantt charts place tasks on a calendar so you can see their order, duration and overlap.
```mermaid
gantt
title Documentation release
dateFormat YYYY-MM-DD
axisFormat %b %d
section Research
Interview users :done, research, 2026-10-05, 3d
Confirm requirements :after research, 2d
section Production
Write draft :draft, 2026-10-10, 4d
Create diagrams :diagrams, after draft, 3d
Review and publish :crit, after diagrams, 2d
```
The dateFormat tells Mermaid how to read the dates. Tags such as done and crit change how tasks are displayed. A dependency such as after research starts one task after another finishes.
Keep a Gantt chart focused. A high-level plan is helpful inside a README or project brief; fifty tiny tasks will usually be easier to manage in a dedicated project tool.
Compatibility: Gantt charts are well established, but date parsing, fonts and available width can make the same chart look different across tools and exports.
5. See an experience from the user’s perspective
The journey diagram combines stages, actions and satisfaction scores. The score runs from 1 to 5.
```mermaid
journey
title Opening a Markdown file for the first time
section Discover
Receive the file: 3: User
Find an editor: 2: User
section Open
Load the document: 4: User
See the preview: 5: User
section Finish
Make a correction: 4: User
Export the result: 5: User
```
The scores make friction visible. In this example, finding an editor is the weakest part of the journey, so that is where the experience needs attention.
Journey diagrams work well in product briefs, service reviews and customer-experience documents. They are not a replacement for research, but they make the result of that research easier to discuss.
Compatibility: Journey diagrams require a reasonably recent Mermaid renderer. If portability matters, include a short text summary beside the chart.
6. Describe a database with an entity-relationship diagram
An entity-relationship diagram, or ER diagram, shows data entities, their fields and the relationships between them.
```mermaid
erDiagram
USER ||--o{ DOCUMENT : creates
DOCUMENT ||--o{ REVISION : contains
USER {
int id PK
string email
}
DOCUMENT {
int id PK
string title
int owner_id FK
}
REVISION {
int id PK
datetime created_at
int document_id FK
}
```
Here, one user can create zero or more documents, and one document can contain zero or more revisions. PK and FKmark primary and foreign keys.
This is handy when a README needs enough schema context to help a contributor without sending them to a separate diagram file.
Compatibility: ER diagrams work in modern Mermaid renderers. Large schemas are more likely to produce layout differences than syntax errors, so keep the example focused.
7. Sketch software structure with a class diagram
Class diagrams show classes, their attributes, methods and relationships.
```mermaid
classDiagram
class Document {
+String title
+String content
+save()
}
class Renderer {
+render(markdown)
+exportPDF()
}
Document --> Renderer : sends content to
```
The plus sign means the member is public. Mermaid also supports other visibility markers and several relationship types, but a simple overview is often more useful than a diagram containing every class in the codebase.
Use this for architecture notes, design proposals and contributor documentation. If the diagram becomes a second copy of your entire codebase, it will be difficult to maintain.
Compatibility: Class diagrams are widely available in modern Mermaid integrations, but exact arrow placement and box sizing can vary between versions.
8. Organise an idea with a mind map
A mind map begins with one subject and expands into related branches.
```mermaid
mindmap
root((Article))
Audience
Beginners
Technical writers
Content
Explanation
Examples
Troubleshooting
Publishing
Images
Links
Final review
```
The structure comes from indentation, which makes the source easy to scan even before it is rendered.
Get Yugene’s stories in your inbox
Join Medium for free to get updates from this writer.
Mind maps are useful during planning, but keep the branches short. Once each branch contains full paragraphs, an outline is usually the better format.
Compatibility: Mind maps arrived later than flowcharts and sequence diagrams. Older integrations may display this block as code or report an unknown diagram type.
9. Tell a chronological story with a timeline
Use a timeline when readers need to understand what happened and when, without the task dependencies of a Gantt chart.
```mermaid
timeline
title Product launch
Research : Interview users
: Review competing tools
Build : Create prototype
: Test the workflow
Release : Publish documentation
: Announce the update
```
Each main label creates a time period. The indented entries describe events within it.
This works for project histories, release summaries, incident reports and explaining how a decision developed over time.
Mermaid currently describes the timeline diagram as experimental. Its basic syntax is stable, but you should still test it in the exact editor or publishing system where the document will be used.
Compatibility: Treat timelines as less portable than flowcharts. Keep an image fallback when the document will be opened in several different apps.
10. Prioritise ideas with a quadrant chart
A quadrant chart places items along two axes. It is useful when a decision depends on two competing dimensions, such as effort and impact.
```mermaid
quadrantChart
title Feature priority
x-axis Low effort --> High effort
y-axis Low impact --> High impact
quadrant-1 Plan carefully
quadrant-2 Do next
quadrant-3 Skip for now
quadrant-4 Reconsider
Live preview: [0.25, 0.82]
Export themes: [0.45, 0.70]
Team sync: [0.85, 0.65]
Custom cursors: [0.72, 0.18]
```
The coordinates run from 0 to 1. In this example, live preview has high impact and relatively low effort, while team sync has meaningful impact but requires much more work.
Quadrant charts are good conversation starters. The positions are still judgments, so explain the evidence behind them instead of treating the chart as a calculation.
Compatibility: Quadrant charts are a newer Mermaid feature and are not as reliably supported by older integrations. Test the chart in the destination app before sharing it.
Where Mermaid diagrams work
Mermaid support varies by app:
- Compatible markdown viewer: renders Mermaid blocks in its Markdown preview.
- GitHub: works in Markdown files, issues, discussions, pull requests and wikis.
- GitLab: supports Mermaid diagrams and currently documents Mermaid 11.
- Visual Studio Code: renders Mermaid in its built-in Markdown preview.
- Obsidian: renders Mermaid blocks in notes.
- Medium: use an exported image, then add the source as a code block if readers may want to copy it.
- CommonMark, Microsoft Word and Google Docs: do not natively turn Mermaid source into a diagram.
Newer diagram types may vary between apps, so preview the final document before publishing.
Which markdown mermaid diagram should you choose?
Start with the question the diagram needs to answer:
- What happens next? Use a flowchart.
- Who communicates, and in what order? Use a sequence diagram.
- What condition is this object in? Use a state diagram.
- When will the work happen? Use a Gantt chart.
- How does the user experience each stage? Use a journey diagram.
- How is the data related? Use an ER diagram.
- How is the software structured? Use a class diagram.
- How do these ideas branch? Use a mind map.
- What happened over time? Use a timeline.
- Where does each option sit on two dimensions? Use a quadrant chart.
The best diagram is not the most elaborate one. It is the one that answers the reader’s question faster than another paragraph would.
Why your Mermaid diagram may show as code
If you see the Mermaid source instead of a diagram, check these three things:
- The opening fence is exactly
```mermaid, with lowercase spelling. - The diagram itself contains valid Mermaid syntax.
- Your editor or publishing platform actually supports Mermaid rendering.
GitHub can render Mermaid in Markdown files, issues, discussions, pull requests and wikis. Other Markdown environments may support only certain diagram types, or may use an older Mermaid version.
For a quick source-and-preview reference, this guide to Mermaid diagrams in Markdown explains the fence syntax and common rendering problems.
What works on Medium
Medium supports code blocks, but it does not allow authors to run arbitrary scripts inside a story, and its documentation does not list native Mermaid rendering. Treat a Mermaid block on Medium as code, not as a live diagram.
For a Medium article, use this combination:
- Render the diagram in a Mermaid-compatible editor.
- Export or capture the rendered diagram as an image.
- Upload the image to Medium.
- Put the Mermaid source beneath it in a code block.
Readers get an immediate visual and an editable example they can copy. It also gives the article a useful fallback if they are reading on a platform that does not support Mermaid.
One rule that keeps Mermaid useful
Keep each diagram focused on one question.
Mermaid makes it easy to keep adding nodes, but a diagram with thirty boxes can be harder to understand than the text it replaced. Start with the smallest version that communicates the idea. Add detail only when it changes what the reader understands or decides.
That is where text-based diagrams work best: they are easy to write, easy to revise, and stay close to the surrounding documentation, making them less likely to become outdated. Use a compatible Markdown viewer to render and view the diagrams properly.
