Beauty Diagram
Diagram type

Mermaid Gantt Chart Syntax & Examples

Reference for Mermaid Gantt chart syntax — dateFormat, sections, tasks, dependencies (after), milestones, and excludes. Copy-paste examples for release plans and roadmaps.

Syntax reference, layout guidance, and ready-to-open examples for this diagram type.

At a glance

A syntax reference for Mermaid's gantt grammar — read this when you need to know the exact way to declare a section, dependency, milestone, or excluded date range, then render the result in the editor.

What is a Mermaid Gantt chartHeader — title, dateFormat, axisFormatSections — group related tasksTasks — id, start, duration, dependenciesMilestones — zero-duration anchorsCommon patterns & gotchas
Rendered proof
Gantt chart for a small release plan.
Theme · Atlas
Open this diagram in editor
TIMELINE Release plan Apr 2026 Apr 01-05 Apr 06-12 Apr 13-15 04/01/26 04/03 04/05 04/07 04/09 04/11 04/13 04/15 Backend Frontend Launch A1 API work TASK A2 Migrations TASK B1 Landing pages TASK B2 Editor polish TASK C1 QA TASK C2 GA TASK A1 A2 B1 B2 C1 C2
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
diagram.mmd
1gantt
2  title Release plan
3  dateFormat  YYYY-MM-DD
4  section Backend
5  API work         :a1, 2026-04-01, 7d
6  Migrations       :a2, after a1, 3d
7  section Frontend
8  Landing pages    :b1, 2026-04-03, 6d
9  Editor polish    :b2, after b1, 5d
10  section Launch
11  QA               :c1, after a2, 4d
12  GA               :c2, after c1, 1d

What is a Mermaid Gantt chart

A Mermaid Gantt chart describes a project schedule as horizontal bars on a timeline. Each row is a task; rows are grouped into sections (typically phases or teams); bars show duration; and dependency arrows can link tasks to predecessors. It is the right shape when the question is what-runs-when across multiple parallel work streams: release plans, sprint roadmaps, project schedules, deployment windows. If your story is a single chronology with no parallel streams, prefer a timeline; if it is a process with branches rather than parallel work, prefer a flowchart.

Header — title, dateFormat, axisFormat

Every Gantt chart starts with the gantt keyword. The first lines configure the chart: title Plan name sets the visible title. dateFormat YYYY-MM-DD declares how date strings in the source are parsed (ISO is the safest default). axisFormat %Y-%m-%d controls how dates render on the time axis (a more compact %m-%d is common for short plans). The excludes weekends directive removes Saturdays and Sundays from the rendered timeline, which is useful when work doesn't span weekends — task durations are computed as business days instead of calendar days.

  • title <Name> — chart heading
  • dateFormat YYYY-MM-DD — input date format (ISO is safest)
  • axisFormat %m-%d — rendered time-axis labels (uses strftime tokens)
  • excludes weekends — skip Sat/Sun in duration calculations

Sections — group related tasks

Use section Name to declare a section header. Subsequent task lines belong to that section until the next section declaration. Sections render as horizontal bands with the section name on the left. Pick sections by team (Backend / Frontend / Launch), by phase (Design / Build / Ship), or by track (Customer-facing / Internal) depending on what the chart is communicating. Sections also affect visual grouping in the legend, so a deliberate choice here makes the chart read as a plan rather than as an unorganised list of tasks.

Tasks — id, start, duration, dependencies

A task is a single line with the format Task name :id, start, duration. The id is used to reference the task as a dependency. The start can be an absolute date (2026-05-01) or relative to another task (after a1 runs after task with id a1 completes). The duration can be days (5d), weeks (2w), hours (8h), or an absolute end date. Multiple dependencies are written as after a1 a2 a3 — the task starts after all listed predecessors finish. Tasks can also be flagged with state modifiers: done (greyed out), active (highlighted as in-progress), crit (critical path emphasis).

  • Task :id, 2026-05-01, 5d — absolute start, day duration
  • Task :id, after a1, 3d — start after another task completes
  • Task :crit, id, after a1, 5d — flag as critical path
  • Task :done, id, 2026-04-01, 7d — already completed

Milestones — zero-duration anchors

A milestone is a task with 0d duration (or the milestone keyword). It renders as a diamond marker rather than a bar, which makes it visually distinct from work tasks. Use milestones for release dates, go/no-go decisions, freeze points, deployment cuts — the moments on the chart that are events rather than effort. The milestone keyword is shorthand: GA :milestone, m1, after qa, 0d produces the same diamond as the explicit 0d form.

Common patterns & gotchas

Two patterns cover most real Gantt charts. Phase plans use sections per phase (Design / Build / QA / Ship), with each phase's tasks chained by after dependencies. Team plans use sections per team, with cross-team dependencies as the interesting edges to watch. The most common gotcha: after a1 with a task that has no id — every task that will be referenced as a predecessor must have an explicit id (Task :a1, 2026-05-01, 5d). Second gotcha: forgetting to set dateFormat — Mermaid then guesses from the input and often picks differently than expected. Always declare dateFormat YYYY-MM-DD explicitly.

  • Every task referenced by after must have an explicit id — the a1 part of :a1, start, duration
  • Always declare dateFormat explicitly — auto-detection is unreliable for non-ISO inputs
  • Use excludes weekends for business-day duration math
FAQ

Mermaid Gantt Chart Syntax & Examples — frequently asked questions

How do I express task dependencies in Mermaid Gantt syntax?

Use after <id> in place of an absolute start date — for example Migrations :a2, after a1, 3d means "start after task with id a1 completes, run for 3 days". Multiple predecessors are written as after a1 a2 a3 (space-separated) — the task starts after all listed predecessors finish. Every task you want to reference must have an explicit id, which is the first field in its declaration.

How do I mark a milestone in a Mermaid Gantt chart?

Two ways. Explicitly use the milestone keyword: GA :milestone, m1, after qa, 0d. Or implicitly give a task 0d duration: GA :m1, 2026-05-01, 0d — Mermaid renders both as a diamond marker rather than a bar, which makes them visually distinct from work tasks. Use milestones for release dates, go/no-go points, and deployment cuts.

What does excludes weekends do?

It removes Saturdays and Sundays from the rendered timeline and the duration math. With excludes weekends set, a 5-day task that starts on a Wednesday will end on the following Tuesday rather than the following Monday — Mermaid skips the weekend automatically. This is the right default for engineering plans where work doesn't span weekends; remove it if you want calendar-day durations instead.

Why does my Gantt chart show all tasks starting on the same day?

Almost always because dependencies are missing or wrong. Mermaid does not infer dependencies from order — tasks without after clauses start on whatever absolute date you give them, regardless of where they appear in the source. Either add explicit after clauses (Task2 :b1, after a1, 5d) or set explicit start dates per task. Order in the source affects visual position (top-to-bottom), not scheduling.

Can I flag a task as in-progress or on the critical path?

Yes. Use the state modifiers: done (greyed-out completed task), active (highlighted as in-progress, useful for status updates), and crit (critical path emphasis with a stronger colour). Combine with the normal task syntax: Task :crit, active, id, 2026-05-01, 5d flags a critical in-progress task. The modifiers stack and are useful for periodic status reviews where the same chart shows planning + current state in one view.