Gantt charts are the backbone of project management visualization. They map tasks against a timeline, show dependencies, highlight milestones, and make resource allocation transparent to entire teams. Traditionally built in Microsoft Project or Excel, Gantt charts can now be created entirely in code using Mermaid—making them version-controllable, automatable, and easy to embed in documentation.
This guide teaches you everything you need to build professional Gantt charts with Mermaid, from basic syntax to advanced project planning patterns.
Why Use Mermaid for Gantt Charts?
Traditional Gantt chart tools lock your data into proprietary file formats. Mermaid changes this paradigm entirely.
- Text-based source: Your schedule lives in Git, enabling pull request reviews and change tracking.
- Quick iteration: Adjusting a deadline or adding a task takes seconds, not clicks through nested menus.
- Documentation-native: Embed live Gantt charts directly in your README, wiki, or technical spec.
- CI/CD compatible: Generate project reports automatically from milestone data.
Basic Syntax
Every Gantt chart starts with the gantt keyword, followed by a date format declaration and task definitions.
If you want to start from an editable example instead of a blank file, open the Mermaid Gantt chart example and export it as PNG, SVG, PDF, or JPG after adjusting the tasks.
gantt
title Website Redesign Project
dateFormat YYYY-MM-DD
section Design
Wireframes :a1, 2025-12-01, 7d
Visual Design :a2, after a1, 10d
section Development
Frontend :a3, after a2, 14d
Backend API :a4, after a2, 10d
section Testing
QA Testing :a5, after a3, 7d
Bug Fixes :a6, after a5, 5d
Key Components Explained
| Component | Syntax | Purpose |
|---|---|---|
title | title Project Name | Displays a chart header |
dateFormat | dateFormat YYYY-MM-DD | Defines how dates are parsed |
section | section Phase Name | Groups related tasks visually |
| Task name | Task Name | Human-readable label on the chart |
| Task ID | :id, | Optional identifier for dependency references |
| Start date | 2025-12-01 or after id | When the task begins |
| Duration | 7d, 2w, 1m | How long the task runs |
Supported Date Formats
Mermaid accepts multiple date format patterns. Choose one that matches your data source.
| Format Pattern | Example | Best For |
|---|---|---|
YYYY-MM-DD | 2025-12-01 | ISO standard, unambiguous |
MM-DD-YYYY | 12-01-2025 | US-centric sources |
DD-MM-YYYY | 01-12-2025 | European sources |
YYYY/MM/DD | 2025/12/01 | Alternative separator style |
Always declare your chosen format at the top of the chart with dateFormat.
Task Dependencies
Dependencies are where Gantt charts deliver their real power. Mermaid supports two dependency types.
Sequential Dependencies with after
Use after taskId to start a task only when another completes.
gantt
dateFormat YYYY-MM-DD
Research :r1, 2025-12-01, 5d
Analysis :r2, after r1, 3d
Report Writing :r3, after r2, 4d
Multiple Predecessors
A task can depend on multiple preceding tasks. It starts when the last dependency finishes.
gantt
dateFormat YYYY-MM-DD
Frontend Dev :f1, 2025-12-01, 10d
Backend Dev :b1, 2025-12-01, 8d
Integration Testing :i1, after f1 b1, 5d
Task Status Indicators
Mermaid lets you mark tasks with visual status tags.
| Status | Syntax | Visual |
|---|---|---|
| Active | Active, taskId, ... | Thick colored bar |
| Done | Done, taskId, ... | Striped or lighter bar |
| Critical | Crit, taskId, ... | Red-highlighted bar |
gantt
dateFormat YYYY-MM-DD
section Sprint 1
Planning :done, p1, 2025-12-01, 2d
Core Feature :active, c1, after p1, 5d
Security Audit :crit, s1, after c1, 3d
Documentation :d1, after c1, 4d
Milestones
Milestones represent zero-duration events such as deadlines, releases, or review gates.
gantt
dateFormat YYYY-MM-DD
Alpha Development :a1, 2025-12-01, 14d
Alpha Release :milestone, am, after a1, 0d
Beta Development :b1, after am, 10d
Beta Release :milestone, bm, after b1, 0d
Milestones render as diamond shapes on the timeline, making them instantly recognizable as checkpoints.
Real-World Example: Product Launch
Here is a complete Gantt chart for a typical product launch spanning three months.
gantt
title Product Launch Q1 2026
dateFormat YYYY-MM-DD
section Strategy
Market Research :done, mr, 2026-01-05, 10d
Competitive Analysis :done, ca, after mr, 7d
Launch Strategy :active, ls, after ca, 5d
section Product
Feature Freeze :milestone, ff, 2026-01-28, 0d
QA Testing :qa, 2026-01-29, 14d
Bug Fix Sprint :bf, after qa, 7d
Release Candidate :milestone, rc, after bf, 0d
section Marketing
Content Creation :cc, 2026-02-01, 14d
Landing Page :lp, after cc, 7d
Email Campaign :ec, after lp, 5d
section Launch
Press Release :pr, 2026-02-24, 3d
Social Media Blast :sm, after pr, 2d
Official Launch :milestone, ol, 2026-03-01, 0d
Best Practices for Gantt Charts
Follow these guidelines to keep your Gantt charts readable and maintainable.
Use meaningful task IDs. IDs like r1, dev1, or qa2 are fine for small charts. For complex projects, use descriptive IDs such as frontend_dev or security_audit.
Group with sections. Sections create visual separation. A chart with 20 ungrouped tasks is overwhelming; the same tasks split across 4 sections is scannable.
Keep durations realistic. Mermaid does not validate whether your schedule is achievable. Use it as a visualization layer on top of realistic estimates from your project management tool.
Combine with other diagrams. Link your Gantt chart to a requirements document that includes flowcharts for processes, or sequence diagrams for API interactions during the development phase.
Export for stakeholders. Mermaid2Img lets you export your Gantt chart to PNG or PDF for PowerPoint presentations, email updates, or printed reports.
Common Pitfalls
| Pitfall | Solution |
|---|---|
Missing dateFormat | Always declare dateFormat before any tasks |
| Circular dependencies | Ensure after references do not create loops |
| Overlapping task IDs | Each ID must be unique within the chart |
| Invalid duration units | Use d for days, w for weeks, m for months, y for years |
| Undeclared predecessor | The task referenced in after must exist before the dependent task |