Mermaid Gantt Chart: Project Timeline Diagrams

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, 10d

Every 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, duration

All fields except the task name are optional, but in practice you need at least a start (or dependency) and a duration.

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, 2d

When 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, 5d

This 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

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, 5d

Tasks 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 ticks

Common axisFormat values:

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, 0d

Migration 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.