Sprint and project planning with Mermaid Gantt charts

Project timelines live in the wrong place. They're in spreadsheets nobody links to, Confluence pages nobody updates, and project management tools that are three status reports out of date. The team ships code to GitHub and plans work... somewhere else.

Mermaid's gantt diagram type puts the plan where the code is. A Gantt chart as a text block in your repository is a plan that can be reviewed, diffed, and updated in the same workflow as everything else.

Gantt syntax basics

Every Gantt chart starts with gantt, followed by optional configuration and then sections of tasks:

gantt
    title Sprint 14 — Auth Redesign
    dateFormat YYYY-MM-DD

    section Backend
    API schema design      :done, schema, 2026-06-01, 2d
    Auth endpoint          :done, auth, after schema, 3d
    Token refresh logic    :active, refresh, after auth, 2d

    section Frontend
    Login page             :login, after auth, 3d
    Profile settings       :profile, after login, 2d

    section QA
    Integration tests      :tests, after refresh, 3d
    UAT                    :uat, after tests, 2d

Each task line follows the pattern:

Task label  :  [status,]  [id,]  start,  duration

• status is optional: done, active, or crit (critical path)
• id is optional but required when other tasks reference this one with after id
• start is an explicit date (YYYY-MM-DD) or a relative reference (after schema)
• duration is in days (2d), hours (2h), or weeks (1w)

Date formats

dateFormat controls how literal dates in the chart are parsed. Pick one and be consistent — mixing formats in the same chart causes tasks to silently render in the wrong position.

Format	Example
YYYY-MM-DD	2026-06-09
DD/MM/YYYY	09/06/2026
MM-DD-YYYY	06-09-2026

Task states and the critical path

Four modifiers affect how a task bar renders:

Modifier	Meaning	Visual
done	Completed	Muted fill
active	In progress	Highlighted fill
crit	On the critical path	Red fill
(none)	Planned	Default fill

Combine them: crit, active marks a task as both on the critical path and currently running. This is the fastest way to communicate "this task is late and everything depends on it" without calling a meeting.

gantt
    title Release 2.0 Critical Path
    dateFormat YYYY-MM-DD

    section Infrastructure
    Database migration    :crit, done, db, 2026-06-01, 3d
    Cache layer           :crit, active, cache, after db, 4d
    Load balancer config  :crit, lb, after cache, 2d

    section Features
    User export           :export, 2026-06-01, 5d
    Notification service  :notif, after export, 3d

Red bars catch the eye immediately. In a planning meeting, "critical path is red, everything else is grey" communicates schedule risk in under a second.

A complete sprint planning example

Here's a realistic two-week sprint with parallel tracks and weekend exclusion:

gantt
    title Sprint 15 (June 9–20, 2026)
    dateFormat YYYY-MM-DD
    excludes weekends

    section Design
    Component specs         :done, specs, 2026-06-09, 2d
    Final design review     :review, after specs, 1d

    section Backend
    Endpoint scaffolding    :done, scaffold, 2026-06-09, 1d
    Business logic          :active, logic, after scaffold, 4d
    Unit tests              :unittests, after logic, 2d

    section Frontend
    Component build         :comp, after review, 3d
    API integration         :integration, after comp, 2d
    E2E tests               :e2e, after integration, 2d

    section Release
    Staging deploy          :crit, staging, after unittests, 1d
    QA sign-off             :crit, qa, after staging, 1d
    Production deploy       :crit, prod, after qa, 1d

excludes weekends automatically shifts any task that would land on a Saturday or Sunday to the following Monday. Use excludes weekends, 2026-06-19 to also skip a specific holiday.

Milestones

Milestones are zero-duration tasks that mark a point in time — a review gate, a release, a decision deadline:

gantt
    title Q3 2026 Roadmap
    dateFormat YYYY-MM-DD

    section Platform
    API v2                :api, 2026-07-01, 21d
    SDK update            :sdk, after api, 14d

    section Milestones
    API v2 launch         :milestone, m1, after api, 0d
    SDK GA                :milestone, m2, after sdk, 0d

The milestone keyword renders a diamond instead of a bar — the visual convention for checkpoints in traditional project management.

Using after references everywhere

Hardcoded start dates go stale the moment anything slips. Relative references (after logic, 2d) automatically reflow the schedule when an upstream task moves:

gantt
    title Feature: Checkout Redesign
    dateFormat YYYY-MM-DD

    Backend API          :api, 2026-06-10, 5d
    Frontend components  :fe, after api, 4d
    Integration tests    :tests, after fe, 2d
    Code freeze          :milestone, freeze, after tests, 0d
    QA window            :qa, after freeze, 3d
    Ship                 :milestone, ship, after qa, 0d

If the backend API slips a day, every subsequent task shifts automatically. You update one date; the whole timeline reflows.

Tips for keeping Gantt charts useful

Put the chart next to the code. A Mermaid block in docs/sprint-15.md or a project README is visible in GitHub, reviewed in PRs, and searchable with grep. A Gantt chart in a separate planning tool is invisible to the engineers doing the work.

Keep tasks coarse. A chart with forty tasks is a wall of bars. Keep tasks at the feature or story level — group subtasks into a single bar. Detailed breakdowns belong in your issue tracker.

Update done and active each day. Marking a task done takes thirty seconds and immediately communicates to everyone what's shipped versus what's in flight.

Diff re-plans in PRs. When the sprint plan changes mid-sprint, a PR that updates the Gantt chart documents the re-plan for the record. Three months later, "why did QA run long in Sprint 15?" has a documented answer.

Use it for retrospectives. Compare the initial plan against the final state to see exactly where estimates were off. That's how teams improve their estimates sprint over sprint.

Gantt charts vs. Kanban boards

These tools model different things. A Kanban board shows current status — what's in progress now, what's blocked, what's done. A Gantt chart shows time allocation — what was planned to run when, in relation to other work.

Teams use both. The Kanban board drives the daily workflow; the Gantt chart communicates timelines to stakeholders and creates a permanent record of the plan. Neither replaces the other.

The most underrated use of a project Gantt chart isn't planning — it's retrospectives. When you can diff the initial plan against the final state, you know exactly where estimates were off.

Start with the current sprint. Sketch the tasks, link them with after references, commit it to the repo. By the time the sprint is over, you'll have a permanent record of how the work actually went — and a baseline for the next estimate.