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.

Build a Mermaid timeline in four steps

1. Open a Markdown code fence labelled mermaid.
2. Put timeline on the first line inside the fence.
3. Add an optional title, then one period : event line for each milestone.
4. Close the fence and preview the Markdown in a viewer that supports Mermaid timelines.

The release-history block above is a complete chart code example: copying the entire fence gives you a working Markdown timeline. Replace the dates and events with your own, and keep them in the order you want readers to follow. Mermaid does not sort timeline labels as calendar dates.

For several events under one period, add another colon-separated event on that line. For chapters such as planning and launch, use section labels as in the research example below.

Timeline syntax in Markdown

Start the fenced block with mermaid, then put timeline on the first line inside it. An optional title line names the diagram. Each period or date label is followed by a colon and an event; add another colon for a second event in the same period. For example, a research history can group two publications under one year:

Mermaid timeline labels are text. The years above are labels in the order written, not dates parsed by a scheduler. Put them in chronological order yourself. dateFormat and axisFormat belong to the Gantt examples above; adding them to a timeline will not turn its events into scheduled tasks.

To embed either example in a Markdown document, copy the entire fenced block, including its opening fence labelled mermaid and its closing fence. If the diagram displays as code, check that the viewer supports Mermaid timeline diagrams and that the fence is labelled mermaid.

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.

Check the Meaning of the Schedule

For a Gantt chart, verify that every task has the intended start, duration, or dependency; a diagram can render while describing the wrong schedule. For a timeline, check event order and the labels that identify periods. Keep dates and event names in the surrounding Markdown so reviewers can compare the diagram with the source facts.

A timeline communicates events; a Gantt chart communicates work over time. For a numeric comparison such as monthly requests or category totals, use the Mermaid bar chart guide.