3 Mermaid Diagrams You Didn't Know Exist
Most people discover Mermaid through flowcharts. That makes sense: flowcharts are easy to read, easy to write, and useful in almost every technical document. The same goes for sequence diagrams, which are now common in API docs, architecture notes, and incident writeups.
But Mermaid can do more than boxes and arrows. Some of its most useful diagram types are still underused, even though they solve problems that show up constantly in real engineering documents: timelines, database relationships, and state transitions.
If your Markdown files include delivery plans, data models, onboarding flows, workflow states, or product behavior, these three Mermaid diagram types are worth knowing. They let you keep diagrams close to the text, review them in pull requests, and update them without exporting a new image from another tool.
1. Gantt Diagrams: Roadmaps That Stay With the Plan
Gantt charts are not only for project managers. They are useful whenever a technical document needs to explain work over time: migration plans, rollout phases, implementation schedules, incident recovery timelines, dependency sequencing, or release plans.
The reason Gantt diagrams work well in Markdown is that they keep the schedule readable as text. A reviewer can see both the rendered timeline and the source that produced it. That matters when the plan changes every few days.
gantt
title Deployment Phases
dateFormat YYYY-MM-DD
section Phase 1 - Core
Metrics dashboards :p1a, 2026-01-01, 3d
Logs pipeline :p1b, after p1a, 2d
Tracing setup :p1c, after p1b, 2d
section Phase 2 - Security
Runtime detection :p2a, after p1c, 3d
Vulnerability scans :p2b, after p2a, 2d
section Phase 3 - Automation
Runbooks :p3a, after p2b, 3d
Auto-remediation :p3b, after p3a, 3d
This kind of diagram is especially useful for docs that answer "when does each part happen?" A written checklist is good for tasks, but a Gantt chart makes overlap, ordering, and handoff points much easier to scan.
Open the rendered Gantt example in mdview
Use Gantt diagrams when your document contains phased delivery, rollout windows, migration steps, or team schedules. They are less useful for precise resource planning, but excellent for explaining sequencing to engineers, stakeholders, and reviewers.
2. ER Diagrams: Database Models Without Screenshots
Entity relationship diagrams are one of Mermaid's most practical hidden features. Instead of pasting a stale database screenshot into a README, you can describe the schema directly in Markdown.
This is useful for product specs, API docs, backend design proposals, onboarding guides, and architecture reviews. A small ER diagram can make a data model understandable before someone has to open the ORM, SQL migrations, or database console.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : appears_in
CUSTOMER {
uuid id PK
string email
string name
}
ORDER {
uuid id PK
date created_at
string status
}
LINE_ITEM {
uuid id PK
int quantity
decimal unit_price
}
PRODUCT {
uuid id PK
string sku
string name
}
The biggest advantage is reviewability. If someone adds a table, changes a relationship, or renames a field, the diagram changes in the same diff as the rest of the document. That makes it easier to keep docs aligned with reality.
Open the rendered ER diagram example in mdview
ER diagrams are also useful outside databases. You can model domain entities, ownership relationships, billing objects, permission models, and event structures. If the document is explaining nouns and relationships, an ER diagram may be clearer than a flowchart.
3. State Diagrams: Lifecycles, Wizards, and Retry Logic
State diagrams are ideal when a system has modes, transitions, retries, approvals, failures, or lifecycle stages. They answer a different question than flowcharts. A flowchart usually explains a process. A state diagram explains what something can be, and how it moves between those states.
That distinction is useful in product and engineering docs. Think of subscription states, upload processing, deployment pipelines, authentication sessions, background jobs, review workflows, checkout flows, and multi-step configuration screens.
stateDiagram-v2
[*] --> Upload
Upload --> Configure : file parsed
Configure --> Preview : settings complete
Preview --> Configure : edit
Preview --> Deploy : approve
Deploy --> Live : pipeline created
Live --> [*]
state Configure {
[*] --> Source
Source --> Schedule
Schedule --> Target
}
This example looks like a setup wizard, but the same structure works for many technical systems. A background job might move from Queued to Running to Succeeded, with branches for Failed, Retrying, and Cancelled. A document review system might move from Draft to Submitted to Approved or Changes Requested.
Open the rendered state diagram example in mdview
State diagrams are especially helpful when teams argue about edge cases. What happens if the user edits after preview? Can a failed job return to queued? Is cancellation allowed after deployment starts? A state diagram forces those answers into the document.
Why These Diagrams Belong in Markdown
The best technical docs are not just prose. They combine explanation, examples, diagrams, and decisions in one place. Mermaid fits this workflow because the diagram source lives beside the surrounding text. That makes diagrams easier to update, easier to review, and easier to share.
Gantt diagrams help readers understand time. ER diagrams help readers understand structure. State diagrams help readers understand behavior. Together, they cover a large part of what technical teams explain every day.
They also reduce the need for separate diagramming tools. You do not need to export images, upload assets, or wonder whether the picture in the doc still matches the system. The diagram is code, and the code is inside the Markdown file.
Try Them in mdview.io
If you already have Mermaid blocks in a Markdown file, you can open the file in mdview.io and read it as a rendered document. If a diagram is broken, the Mermaid Quick Fix tools can help repair the syntax and make the example shareable.
That makes these lesser-known Mermaid types practical for everyday docs. Use Gantt when the document is about schedule, ER diagrams when it is about data, and state diagrams when it is about lifecycle or behavior. Your Markdown will be clearer, and your diagrams will be much easier to keep current.