Mermaid Gantt Chart Syntax
Gantt charts plot tasks against a timeline. Each task has a start date (explicit or relative to another task), a duration, and optionally a status and section grouping. Mermaid renders them as horizontal bar charts with a time axis, making it straightforward to document project schedules, sprint plans, and migration timelines in version-controlled text.
Basic Structure
gantt
title Project Name
dateFormat YYYY-MM-DD
axisFormat %b %d
section Phase 1
Task A :a1, 2024-01-01, 7d
Task B :after a1, 5d
section Phase 2
Task C :after a1, 10dEvery Gantt chart starts with gantt. The title, dateFormat, and axisFormat are optional but recommended. Tasks are grouped under section headers.
Task Definition
Each task line has this format:
Task name :status, taskId, startDate, durationAll fields except the task name are optional, but in practice you need at least a start (or dependency) and a duration.
| Field | Example | Notes |
|---|---|---|
| name | Build API | Displayed label |
| status | done, active, crit | Optional, combinable |
| taskId | api1 | Required if other tasks depend on it |
| start | 2024-03-01 or after other | Explicit date or dependency |
| duration | 5d, 2w | Days or weeks |
Dependencies
Dependencies are the most useful part of Gantt charts. Instead of hardcoding dates, define relationships:
gantt
dateFormat YYYY-MM-DD
Design :des, 2024-01-01, 5d
Implement :impl, after des, 10d
Test :test, after impl, 5d
Deploy :after test, 2dWhen you change the Design duration, every downstream task shifts automatically. This is how you model critical paths without manually calculating dates.
Multiple dependencies
Integration :after backend frontend, 5dThis task starts only after both backend and frontend are complete.
Task Status
gantt
dateFormat YYYY-MM-DD
section Sprint 1
Done task :done, t1, 2024-01-01, 3d
Active task :active, t2, after t1, 5d
Critical task :crit, t3, after t2, 2d
Future task :t4, after t3, 4d| Status | Rendering | Use for |
|---|---|---|
done | Muted fill | Completed work |
active | Highlighted | Current sprint/task |
crit | Red accent | Critical path items |
| (none) | Default fill | Planned future work |
Combine statuses: :done, crit, taskId marks a task as both done and critical.
Sections
Sections group related tasks visually with a label and alternating background bands:
section Backend
API endpoints :api, 2024-01-01, 10d
Database setup :db, 2024-01-01, 5d
section Frontend
UI components :ui, after api, 8d
Integration :int, after ui, 5dTasks in different sections can still reference each other with after.
Date and Axis Formatting
dateFormat YYYY-MM-DD %% how you write dates in task definitions
axisFormat %b %d %% how dates display on the axis
tickInterval 1week %% spacing between axis ticksCommon axisFormat values:
| Format | Output |
|---|---|
%b %d | Mar 01 |
%Y-%m-%d | 2024-03-01 |
%d %b | 01 Mar |
%B %Y | March 2024 |
Practical Patterns
Sprint plan
gantt
title Sprint 12
dateFormat YYYY-MM-DD
axisFormat %b %d
section Stories
User auth :done, s1, 2024-03-04, 3d
Profile page :active, s2, after s1, 4d
Settings :s3, after s2, 3d
section Tech debt
Upgrade deps :done, t1, 2024-03-04, 2d
Fix flaky test :t2, after s2, 1d
section Release
QA :qa, after s3, 2d
Ship :milestone, after qa, 0dMigration timeline
The pre-loaded example shows an API migration with planning, implementation, and rollout phases, dependency chains, and a production cutover milestone. This pattern works for database migrations, infrastructure upgrades, and any phased project.
For documenting the API interactions within this timeline, try the Mermaid Sequence Diagram. For the database schema being migrated, use the Mermaid ER Diagram.