Mermaid Gantt and Timeline Examples in Markdown
Use a Mermaid Gantt chart when your document needs task dates, durations, and dependencies. Use a Mermaid timeline when the important information is the sequence of events. Both live inside a fenced mermaid block, so you can keep the diagram beside the plan that explains it.
The examples here describe a fictional documentation release. Copy a block into a Markdown file and open it in mdview.io to preview the diagram with the rest of your document.
Start With a Small Gantt Example
Read this as a short work plan: writing begins first, review follows writing, and publication follows review. The diagram belongs in the same document as the acceptance criteria, owners, and links to the relevant work.
To embed it, the opening fence is three backticks followed by mermaid; the closing fence is three backticks alone. A fence labelled text or markdown normally displays the source rather than the diagram.
Show Parallel Work and a Release Milestone
This fictional example gives file opening and folder navigation the same start date. That communicates parallel work more clearly than a paragraph saying that several tasks happen “around the same time.” The milestone marks a point, rather than another task with a multi-day duration.
Keep names concrete. “Regression checks” is more useful than “Phase 3” when someone reads the chart without knowing your project vocabulary. For a real plan, put detailed completion requirements in the prose below the diagram.
A Timeline Example for Release History
A history or retrospective often reads better this way. Readers can scan what happened without interpreting each row as scheduled work. If the question becomes “How long did each task take, and which task blocked the next?”, switch back to a Gantt chart.
The Mermaid timeline reference covers timeline syntax. For task scheduling, see the separate Gantt reference.
Choose the Diagram by the Reader's Question
| Reader wants to know | Better starting point |
|---|---|
| What work starts after review? | Gantt |
| Which tasks run at the same time? | Gantt |
| What changed during the release? | Timeline |
| What are the major events in our history? | Timeline |
| Which decision leads to which outcome? | Flowchart |
Do not squeeze a decision tree into a timeline. For branches and choices, use the Markdown flowchart guide.
When the Example Shows Code Instead of a Diagram
First confirm that the viewer supports Mermaid. Rendering ordinary headings and tables does not imply support for diagram fences. Next check the fence label and closing fence. Then try the smallest example above on its own.
If the small example works, add your changes incrementally. A wrong date, a mistyped task ID, or an incomplete line is easier to locate in a short block than in a whole project plan. Mermaid capabilities also vary by version; a chart that works in one editor may need adjustment elsewhere.
For dates and task details, consult the Gantt reference rather than inventing syntax from a screenshot. A diagram can render successfully while still describing the wrong plan: compare its bars and dependencies with the intended schedule.
Keep the Markdown Useful Without the Diagram
Add a sentence explaining the takeaway and a compact list of owners or acceptance criteria. That makes the document useful in source review and gives the visual an explicit purpose. Avoid relying on color alone to explain task status.
For more diagram types, read three less familiar Mermaid diagrams. For numerical comparisons rather than dates, use a Mermaid bar chart.
Preview your Markdown schedule before sharing it, and check the actual diagram at the size your readers will use.