Mermaid Gantt Chart: Syntax, Dependencies, and the Slide Problem
Short answer: a Mermaid Gantt chart opens with the `gantt` keyword, declares a `dateFormat`, groups tasks under `section` headings, and defines each task as a title, a colon, and comma-separated metadata. Dependencies use the `after` keyword rather than hardcoded dates, which is the single feature that makes a Mermaid roadmap worth maintaining. Then you put it on a slide in front of executives and discover that a Gantt chart is a wall of bars that nobody reads in the order you intend.
Here is the syntax, then the presentation problem.
What does Mermaid Gantt syntax look like?
``` gantt title Platform Roadmap dateFormat YYYY-MM-DD section Discovery Requirements :done, req, 2026-01-05, 2026-01-19 Technical spike :active, spike, 2026-01-20, 10d section Build Backend API :crit, api, after spike, 20d Web client :web, after api, 15d section Launch Beta :milestone, beta, after web, 0d ```
Reading it line by line:
`dateFormat` tells the parser how to interpret the dates you write. It is not the display format — that is `axisFormat`, which is separate and which most people discover only after wondering why their chart shows American dates.
`section` groups tasks into swimlanes. Sections are the closest thing Mermaid gives you to hierarchy, so use them for workstreams or teams rather than for arbitrary chunking.
Task metadata sits after the colon, comma-separated. A tag comes first if you use one, then an optional id, then the timing. Valid tags are `active`, `done`, `crit`, and `milestone`.
Timing is where the real choice is. Give a task two dates and it is pinned to the calendar. Give it a start date and a duration like `10d` and the end is computed. Give it `after <id>` and a duration, and it moves whenever its predecessor moves.
Why does `after` matter more than everything else?
Because roadmaps slip, and a chart full of hardcoded dates lies within a week of being written.
If the technical spike runs three days long and every downstream task has its own literal start date, you edit every one of them by hand and hope you did not miss one. If those tasks are defined with `after`, you change one date and the whole chain moves.
This is the argument for keeping a roadmap in Mermaid rather than in a drawing tool at all. The text is version-controlled, the dependencies are declared rather than drawn, and a slip is a one-line diff someone can review.
Two practical notes. Ids are what `after` refers to, so give one to any task another task depends on, even if you never style it. And `after` accepts multiple predecessors, so a task waiting on two workstreams is expressed directly rather than by picking whichever you guess will finish last.
What Mermaid Gantt charts cannot do
Worth knowing before you commit a quarter's planning to one.
No resourcing. There is no concept of a person, a team, or capacity. Mermaid will happily show one engineer on four concurrent critical-path tasks.
No percent complete. A task is `done`, `active`, or neither. "Eighty percent through the migration" has no representation, and the usual workaround, splitting the task in two, distorts the dependency chain.
Limited layout control. The axis scales itself to the range. A twelve-month roadmap with one two-day task renders that task as a sliver, and there is no zoom.
No animation. Like the rest of Mermaid, the output is a single static render, which is where the next section starts.
Why does a Gantt chart fail in a presentation?
A Gantt chart is dense by construction. Thirty bars, five sections, a date axis, dependency implied by position rather than drawn. As a planning artefact that density is the point — everything is visible, and the reader hunts for what concerns them.
On a slide the density inverts. The audience gets the whole quarter in one frame, and every person in the room immediately finds their own workstream and stops listening. You are explaining the sequencing of the platform work; they are calculating whether their launch date moved. Nobody is following the argument you came to make, because the chart answered a different question faster than you could ask yours.
The workaround everyone reaches for is one slide per phase, or a chart with successive bars highlighted. Both mean the roadmap now exists in five places, and when a date slips — which is what dates do — the slip has to be applied five times. Three of those slides will quietly stop matching. We wrote about that specific maintenance trap in animated timelines for slides.
What works instead is a chart that builds: section by section, or phase by phase, in the order you explain it, so at any moment the audience is looking at the part you are talking about and nothing else.
Planning artefact or presentation artefact?
| | Static Mermaid Gantt | Animated build | |---|---|---| | Everything visible at once | Yes, by design | No, revealed in order | | Reader hunts for their own task | Immediately | Only when you get there | | Renders in a README or wiki | Yes, natively | As a GIF | | Controls the room's attention | No | Yes | | Updating after a slip | One-line diff, re-render | One-line diff, regenerate | | Right for | Planning, docs, tracking | Steering committees, all-hands |
The Mermaid source is the right home for the plan in both cases. What differs is what you hand the room.
From a Gantt definition to an animated timeline
FluxDiagram's Mermaid converter reads `gantt` definitions alongside flowchart, sequence, class, and pie, extracts the structure, and generates an animated version you can export as GIF, MP4, or WebM and embed in PowerPoint, Google Slides, or Keynote.
The property worth having is that the roadmap keeps living in the text. When the spike slips three days you change one line, regenerate, and drop the new file into the slide, rather than nudging bars in a drawing that has no idea the plan changed. For the wider case on building rather than revealing a roadmap, see animated timelines for slides; for the format decisions, Mermaid to PowerPoint.
FAQ
How do I show a dependency between tasks in a Mermaid Gantt chart?
Give the predecessor an id, then define the dependent task with `after <id>` and a duration instead of a start date. The dependent task then moves automatically whenever the predecessor's dates change, which is the whole reason to use ids.
How do I add a milestone?
Tag the task `milestone` and give it a zero duration, typically `0d`. It renders as a diamond on the axis rather than a bar. Milestones can use `after` like any other task, so a launch marker tracks the work it follows.
Can I change how dates are displayed without changing my input format?
Yes. `dateFormat` controls how Mermaid parses the dates you write; `axisFormat` controls how they are printed on the axis. Set them independently — for example write ISO dates and display them as `%b %d`.
Try it with your own roadmap
If your Gantt chart is heading for a steering committee, build it rather than showing it.
Paste your gantt definition into the converter.
FluxDiagram generates animated diagrams you embed into the deck you already have, in PowerPoint, Google Slides or Keynote.