Mermaid Gantt chart examples

How does Mermaid work out the dates of a task?

Every task line is a name, a colon, and metadata separated by commas. Tags come first if you use any (done, active, crit, milestone). What remains is read by position: one item is the end, given as a date or a duration, and the task starts where the previous line ended; two items are a start and an end; three items are an ID, a start and an end. The start can be a date in your dateFormat or after one or more task IDs, and the end can be a date, a duration, or until another task.

Durations are a number and a unit: ms, s, m (minutes), h, d, w, M (months) or y, and decimals such as 1.5d are allowed. Mermaid’s documentation warns that an invalid token such as 3dX is ignored and the task gets zero duration, so a typo shows up as a missing bar rather than an error.

What is the difference between dateFormat and axisFormat?

dateFormat is how Mermaid reads the dates you type. It uses Day.js tokens and defaults to YYYY-MM-DD. axisFormat is how Mermaid prints dates on the axis. It uses d3 time-format codes, which start with a percent sign, and also defaults to a year-month-day layout. The two are independent: you can type ISO dates and print Jan 05, or type times with HH:mm and print %H:%M, as in the runbook example.

Which other Gantt options does Mermaid have?

These are the remaining Gantt keywords and settings from Mermaid’s documentation, with the version that introduced the newer ones. Keywords go on their own line after gantt; displayMode and topAxis go in a config block at the top of the diagram, under gantt.

Why is my Mermaid Gantt chart not rendering?

Start with the metadata order. Tags must come before the ID: done, t1, 2026-05-18, 3d works, while t1, done, 2026-05-18, 3d makes the whole diagram fail. A task name cannot contain a colon, because the first colon starts the metadata. Every section needs a name; a bare section line breaks the drawing. And excludes accepts dates, weekday names and weekends, but not weekdays.

Some mistakes do not raise an error at all. A date typed in a different layout from your dateFormat, or an after that names an ID that does not exist, can still render, with the bar somewhere you did not expect. If a bar is missing or misplaced, check the IDs and the date layout first. Finally, check the renderer’s version: until needs 10.9.0, weekend 11.0.0, vert 11.7.0 and several excludes lines 11.16.0, and a platform on an older Mermaid will reject or ignore them.

Should you use a Gantt chart or a timeline?

Use a Gantt chart when dates, durations and dependencies matter: a project plan, a release schedule, a sprint. Use Mermaid’s timeline when you only need the order of events grouped by period, such as a product history, because it needs no dates or durations at all. A Gantt chart made only of milestones, as in the Milestones example above, sits between the two: it keeps the one-marker-per-event look of a timeline but spaces the events by their real dates. To show how a total splits into parts rather than how work is scheduled, a pie chart is the better fit.

How do you make one task start after another in a Mermaid Gantt chart?

Give the first task an ID, the first item after any tags, as in Design :des, 2026-01-05, 5d. Then start the next task with after des, as in Build :after des, 10d. A task can wait for several tasks at once, after des api, and then starts when the last of them ends. A task with no start at all begins where the task on the line above ends, which is often all you need.

How do you exclude weekends and holidays in a Mermaid Gantt chart?

Add excludes weekends after dateFormat, and add specific dates to the same line, written in your dateFormat, for holidays. Excluded days are shaded on the chart and do not count towards durations, so a task that crosses a weekend gets longer instead of losing days. From Mermaid 11.0.0, weekend friday makes Friday and Saturday the weekend.

Does Mermaid mark tasks as done automatically?

No. done and active are tags you write yourself; Mermaid does not compare them with today’s date. What it does draw automatically is the today marker, a vertical line at the current date whenever today falls inside the chart. You can restyle that line with todayMarker followed by CSS properties or hide it with todayMarker off, but updating task status stays a manual edit.

Can a Gantt chart work as a timeline?

Yes, when the events have real dates. Give every row the milestone tag and a 0d duration and use a section per phase, as in the Milestones example above: Mermaid draws one marker per event on a date axis and no bars, so two launches a week apart sit close together and a six-month gap shows as a gap. For events without dates, such as eras or numbered steps, use Mermaid’s timeline diagram instead: it needs no dateFormat, gives every period the same width and lists several events under one period with extra colons.

Does GitHub render Mermaid Gantt charts?

Yes. GitHub renders fenced mermaid blocks in Markdown files, issues, pull requests, discussions and wikis with the Mermaid library, so the Gantt syntax on this page works there. GitHub chooses which Mermaid version it runs, so newer options such as several excludes lines may not work there yet. Its documentation suggests a one-word info diagram to show the version in use. See how Mermaid works in Markdown.

Can a Mermaid Gantt task link to a web page?

Yes, with a click line such as click t1 href "https://example.com", where t1 is the task ID. Mermaid only activates links and callbacks when the page renders diagrams with securityLevel set to loose; with strict they are ignored. Docs MD renders with strict, so a click line here is skipped without breaking the rest of the chart.