Mermaid Gantt Chart Tutorial (Project Timelines)
A gantt chart shows a project's tasks across a timeline. Mermaid lets you write one in text and update it as fast as the plan changes.
A gantt chart lays a project's tasks out along a timeline, with each task drawn as a horizontal bar whose length shows its duration and whose position shows when it happens. It is the classic project-planning view, making it easy to see what runs when, what overlaps, and what depends on what. Mermaid's gantt syntax lets you build one from text, which is a genuine convenience for developers and technical teams who would rather write a plan than wrestle with project-management software.
This tutorial covers the gantt essentials: setting up the chart and date format, organizing tasks into sections, defining task durations, chaining dependencies so tasks follow one another automatically, and marking milestones. As with all Mermaid, you can paste each snippet into the live editor at /diagram-tools/mermaid-editor and watch it render. Gantt charts have a few unique syntax quirks around dates and dependencies that are worth understanding clearly.
Setting up the chart
A gantt chart starts with the keyword `gantt` on its own line. You then typically set a title with `title Project Plan` and a date format with `dateFormat YYYY-MM-DD`, which tells Mermaid how to interpret the dates you write for tasks. The date format line is important - it defines the pattern your task dates must match, and getting it consistent avoids a common source of rendering errors.
You can also configure the axis format to control how dates display along the top with `axisFormat`, and set the chart to exclude weekends or specific dates from duration calculations, which makes the timeline reflect actual working days. These setup lines go right after the `gantt` keyword and configure the whole chart before you define any tasks. For a first chart, just `gantt`, a title, and a dateFormat are enough to get going.
Sections and tasks
Tasks are grouped into sections, which appear as labelled rows of the chart. You declare a section with `section Design`, and every task after it belongs to that section until the next `section` line. Sections are how you organize a plan into phases or workstreams - Design, Development, Testing, Launch - so the timeline is readable rather than a flat list of bars.
A task line has a name, a colon, and then its parameters: an optional task ID and status, a start point, and a duration or end date. The simplest task is `Write spec :2026-08-01, 5d`, which starts on that date and lasts five days. You can give a task an ID for referencing in dependencies: `Write spec :spec1, 2026-08-01, 5d` names it `spec1`. Task status keywords like `done`, `active`, and `crit` change how the bar renders - `crit` marks a critical task in a distinct color, useful for highlighting the critical path.
Dependencies and milestones
The most powerful feature of Mermaid gantt is automatic dependencies. Instead of writing a fixed start date, you can start a task `after` another task, and Mermaid calculates the date. Writing `Build feature :dev1, after spec1, 10d` means the build starts as soon as `spec1` finishes and runs ten days. This is enormously useful because when you change an earlier task's duration, everything downstream shifts automatically - the whole plan re-flows, which is exactly what you want when a schedule slips.
- `after taskId` starts a task when another finishes, chaining dependencies automatically.
- Change an upstream duration and all dependent tasks shift - no manual date edits.
- A task can depend on several others: `after task1 task2` waits for both.
- Mark a milestone with the `milestone` keyword and a zero duration - it renders as a diamond marker.
- Use `done` for completed tasks, `active` for in-progress, and `crit` to highlight critical ones.
- Give every task you will reference an ID so dependencies can point to it.
- Sections keep phases visually separated, which matters as the plan grows.
A complete example and its limits
Putting it together, a small project might read: `gantt`, a title, `dateFormat YYYY-MM-DD`, then `section Planning` with `Write spec :spec1, 2026-08-01, 5d`, then `section Build` with `Develop :dev1, after spec1, 10d` and `Test :after dev1, 4d`, and finally a milestone `Launch :milestone, after dev1, 0d`. In a dozen readable lines you have a real project timeline that recalculates itself when durations change. That responsiveness is the big advantage of a text-based gantt over a hand-drawn one.
The honest limits: Mermaid gantt is great for straightforward timelines but not a substitute for full project-management software when you need resource allocation, percent-complete tracking, or complex dependency types. Its strength is a lightweight, versionable timeline that lives with your docs and updates in seconds. For a polished timeline in a presentation, or when you want to arrange things precisely, you can bring the chart into a visual tool - Atlas Diagram Studio supports Mermaid import and visual editing at /diagrams, and you can generate a first draft from a written plan using the AI diagram generator at /diagram-tools/ai-diagram-generator.