Mermaid Gantt charts: project timelines, milestones, and dependencies

puml.online
  2026-08-08 10:00 2026-08-08 10:00 Created   2026-08-14 21:34:29 2026-08-14 21:34:29 Updated    

Mermaid’s Gantt chart is a project management powerhouse — describe task timelines, milestones, and dependencies in text, embed directly in docs. PlantUML’s Gantt support is weak; Mermaid is the clear winner here.

What is a Gantt Chart

A Gantt chart plots tasks on the vertical axis against time on the horizontal axis, showing:

  • When each task starts and ends
  • Dependencies between tasks
  • Key milestones
  • Which tasks run in parallel

Use cases: Sprint planning, release roadmaps, technical migration timelines, version schedules.

Minimal Example

1
2
3
4
5
6
7
8
gantt
    title Project Milestones
    dateFormat YYYY-MM-DD
    section Development
    Requirements: a1, 2026-01-01, 7d
    Design: a2, after a1, 5d
    Development: a3, after a2, 14d
    Testing: a4, after a3, 5d
  • title sets the chart title
  • dateFormat declares the date format
  • section groups tasks by responsibility
  • task name: ID, start date, duration (7d = 7 days; after ID = starts after another task ends)

Date Formats

1
2
3
4
5
6
7
8
9
gantt
    dateFormat YYYY-MM-DD
    TaskA: t1, 2026-03-01, 3d

    dateFormat YYYY/MM/DD
    TaskB: t2, 2026/03/05, 2d

    dateFormat DD-MM-YYYY
    TaskC: t3, 07-03-2026, 1d

Common formats:

  • YYYY-MM-DD — ISO standard, recommended
  • YYYY/MM/DD — US style
  • YYYY-MMM-DD — month abbreviation (2026-Jan-15)
  • YYYY-MM-DD HH:mm — hour-level precision

Task Duration

1
2
3
4
5
6
7
gantt
    dateFormat YYYY-MM-DD
    
    section Units
    Days: t1, 2026-01-01, 5d
    Weeks: t2, 2026-01-03, 2w
    Months: t3, 2026-01-10, 3m

Duration units: d (days), w (weeks), m (months), h (hours).

Section Grouping

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
gantt
    title E-commerce Refactoring Plan
    dateFormat YYYY-MM-DD
    
    section Infrastructure
    Database selection: i1, 2026-01-01, 14d
    Cache architecture: i2, after i1, 7d
    CI/CD setup: i3, 2026-01-10, 10d
    
    section Core Features
    User module: u1, after i1, 21d
    Product module: u2, after i1, 21d
    Order module: u3, after u1, 14d
    
    section Launch
    Integration testing: t1, after u3, 7d
    Canary release: t2, after t1, 7d
    GA launch: t3, after t2, 1d

Sections keep related tasks together and make the chart much more readable.

Milestones

Milestones mark critical checkpoints — milestone keyword with 0d duration:

1
2
3
4
5
6
7
8
9
10
11
12
13
gantt
    title Release Plan
    dateFormat YYYY-MM-DD
    
    section Development
    Requirements: r1, 2026-01-01, 7d
    Design: r2, after r1, 5d
    Development: r3, after r2, 14d
    
    section Milestones
    Alpha: milestone, after r3, 0d
    Beta: milestone, after r3 + 7d, 0d
    GA: milestone, after r3 + 21d, 0d

0d duration is the key — Mermaid renders it as a diamond shape.

Dependencies

after — starts when predecessor ends

1
2
3
4
5
gantt
    dateFormat YYYY-MM-DD
    A: a1, 2026-01-01, 3d
    B: b1, after a1, 2d
    C: c1, after b1, 1d

Chain syntax

1
2
3
4
5
6
7
gantt
    dateFormat YYYY-MM-DD
    Requirements: 2026-01-01, 7d
    Design: after Requirements, 5d
    Development: after Design, 14d
    Testing: after Development, 7d
    Launch: after Testing, 1d

Parallel tasks

1
2
3
4
5
6
gantt
    dateFormat YYYY-MM-DD
    TaskA: a1, 2026-01-01, 5d
    TaskB: b1, 2026-01-01, 3d
    TaskC: c1, after a1, 2d
    TaskD: d1, after b1, after c1, 2d

Task D waits for both B and C to complete.

Task Colors

1
2
3
4
5
6
7
8
9
10
11
12
gantt
    title Status Colors
    dateFormat YYYY-MM-DD
    
    section Status Demo
    Completed: done, 2026-01-01, 10d
    Critical: crit, 2026-01-08, 5d
    Active: active, 2026-01-10, 3d
    Future: future, 2026-01-15, 4d
    
    done, crit: done
    active: active

Mermaid built-in status keywords: done (green), crit (red), active (blue), future (gray).

Custom colors

1
2
3
4
5
6
7
8
gantt
    dateFormat YYYY-MM-DD
    
    Urgent: 2026-01-01, 5d
    Critical task: crit, active, 2026-01-01, 5d
    
    style crit fill:#ff6b6b
    style active fill:#6bcb77

Today Marker

1
2
3
4
5
6
7
8
9
10
%%{init: {'theme': 'base'}}%%
gantt
    title Sprint Plan
    dateFormat YYYY-MM-DD
    todayMarker stroke:#ff3, stroke-width:3px
    
    TaskA: a1, 2026-01-01, 7d
    TaskB: a2, after a1, 5d
    TaskC: a3, after a2, 3d
    today: today, 2026-01-10

todayMarker draws a red vertical line at the current date — essential for sprint planning visibility.

Mermaid vs PlantUML Gantt

Feature Mermaid Gantt PlantUML Gantt
Task duration ✅ d/w/m/h ✅ d/w/m
Dependencies ✅ after ID ✅ then chain
Milestones ✅ milestone ✅ milestone
Section grouping ✅ ❌
Status colors ✅ done/crit/active ✅ style
todayMarker ✅ ❌
Resource allocation ❌ ✅ resource
Readability very clean more verbose

Use Mermaid for documentation and planning — quick, beautiful. Use PlantUML for resource-heavy scheduling with fine-grained control.

Common Errors

Error Cause Fix
Tasks not rendering Wrong date format Match task date format to dateFormat declaration
Circular dependency after points to later task Check dependency chain has no loops
Tasks overlap Parallel tasks missing after Parallel tasks still need dependency declarations
Chinese not displaying Font issue Use fontawesome theme or switch theme

Recap

5 things to remember:

  1. dateFormat YYYY-MM-DD declare the format before using dates
  2. section groups tasks — much cleaner for complex projects
  3. after ID or after taskname is the dependency declaration; chain syntax is most readable
  4. milestone marks key dates; 0d = diamond marker
  5. todayMarker stroke:#ff3 draws today’s date line — essential for sprints

PlantUML Gantt is more powerful but more complex — for daily docs, README, sprint boards, Mermaid Gantt is sufficient.

  • Title: Mermaid Gantt charts: project timelines, milestones, and dependencies
  • Author: puml.online
  • Created at : 2026-08-08 10:00:00
  • Updated at : 2026-08-14 21:34:29
  • Link: https://puml.online/blog/mermaid-gantt-en/
  • License: This work is licensed under CC BY-NC-SA 4.0.
On this page
Mermaid Gantt charts: project timelines, milestones, and dependencies
  1. What is a Gantt Chart
  2. Minimal Example
  3. Date Formats
  4. Task Duration
  5. Section Grouping
  6. Milestones
  7. Dependencies
    1. after — starts when predecessor ends
    2. Chain syntax
    3. Parallel tasks
  8. Task Colors
    1. Custom colors
  9. Today Marker
  10. Mermaid vs PlantUML Gantt
  11. Common Errors
  12. Recap