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.

Use this page to connect a high-intent search query to the right problem-solution narrative.

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.