Mermaid Gantt Charts: Syntax, Gotchas, and Round-Tripping to a Real Editor

The syntax in one pass

A gantt block opens with the keyword gantt and a few header lines, then section headings with task lines under them. Indentation is convention, not grammar.

A task line is a name, a colon, then comma-separated fields:

Task name :tag, id, start, duration

• Tags — any of done, active, crit, milestone, in any order, and you can stack several. Optional.
• id — a bare word, needed only if something else refers to this task by name.
• start — a date, or after someId, or omitted entirely to continue from the task above.
• duration — 5d, 2w, or a second absolute date.

Header lines worth knowing: dateFormat (how dates in your file are written), excludes weekends, title, and axisFormat (how the axis is labelled, in strftime-style codes). Fields are classified by shape rather than strictly by position, which is why :done, res, 2026-01-05, 5d and :res, done, 2026-01-05, 5d both work.

A worked example you can paste into a README

A complete, valid block for real work — migrating a public API from v1 to v2. It uses sections, absolute dates, after chains, every tag, a milestone and excluded weekends. Paste it into a fenced mermaid block in any GitHub Markdown file and it renders.

gantt
      title API v2 Migration
      dateFormat YYYY-MM-DD
      axisFormat %b %d
      excludes weekends
      
      section Discovery
      Audit v1 endpoints   :done, audit, 2026-03-02, 5d
      Draft OpenAPI spec   :done, spec, after audit, 4d
      Spec review          :active, review, after spec, 2d
      
      section Build
      Auth service         :crit, auth, after review, 10d
      Resource endpoints   :res, after auth, 12d
      Client SDK regen     :sdk, after res, 3d
      
      section Cutover
      Staging soak         :soak, after sdk, 5d
      Public beta          :milestone, beta, 2026-05-04, 0d
      Deprecate v1         :dep, after beta, 2w

Task-line reference

Every field and modifier, what it does, and what it looks like in practice.

Four things that will bite you

1. Durations are inclusive of the start day. 5d from Monday the 5th runs to Friday the 9th, not the 10th. An off-by-one here shifts every task in the file and still renders perfectly, which is the worst possible failure mode: nothing looks broken.

2. after plus excludes weekends is where the real bugs live. If a predecessor ends on a Friday, its successor starts on the Monday — not Saturday. Any tool that resolves after by adding one calendar day will quietly put tasks on weekends in a file that explicitly forbids them, and every downstream date drifts from there. Ours did this, briefly. The fix routes the arithmetic through the working calendar so the import agrees with what Mermaid draws, and the test guarding it asserts the property rather than specific dates: no derived start or end may land on an excluded day. Dates you typed by hand are left where you put them, weekend or not — silently moving an author's explicit date is the wrong kind of helpful.

3. There is no escaping. A colon starts the field list and a comma separates fields, so Phase 2: design, review becomes a task called "Phase 2" with garbage fields. Keep colons, commas and semicolons out of names; on export we substitute spaces rather than emit a line that will not parse.

4. An unparseable duration silently becomes zero. Write 3dd and you get a zero-length bar rather than an error. Scan for invisible tasks after a bulk edit.

The limits of a diagram format

Mermaid gantt is a rendering language, not a scheduling engine, and the difference shows up the moment you want the chart to answer a question rather than illustrate an answer.

• No resources. No field for who does the work, no cost, no effort, no units. You cannot over-allocate someone in Mermaid because Mermaid does not know anyone exists.
• No float, and no computed critical path. crit is a colour you apply by hand. Nothing walks the dependency graph, computes early and late dates, or tells you which chain drives the finish date. A diagram where every bar is tagged crit is as valid as one where none are.
• No baseline. Nowhere to record what the plan said last month, so there is no variance to show and no slip to measure.
• Finish-to-start only. after is FS with zero lag. SS, FF, SF and any lag or lead have nowhere to go. Real plans are full of "start testing three days after development starts" — in Mermaid that becomes a hard-coded date, and the link is gone.
• No progress percentage. A task at 40% and one at 90% are both just "active".
• Flat sections. No nested groups, so a WBS deeper than one level flattens on the way in.

None of that makes it a bad format. It makes it a publishing format — good for showing a schedule, useless for deriving one. Which is why the round trip matters.

Editing visually, then pasting the text back

Plenty of tools render Mermaid. What has been missing is the other direction — dragging bars and getting the syntax back out.

1. Paste or open your diagram in gantts.app — a .mmd, or a .md with a fenced block. It detects a gantt block by content, not extension.
2. Drag, link and re-date it like any other chart. excludes weekends switches the working calendar on, so the dates it produces agree with the file it came from.
3. Export ▸ Mermaid gantt, copy, paste back into your README, commit the diff.

The trip is lossy in a known, boring way. Progress maps 100% to done and 1–99% to active on the way out; active comes back in as 50% — a guess you are told about in a warning rather than left to find in a status report. Links that cannot be written as after — anything with a lag, or any SS/FF/SF relationship — fall back to absolute dates, which stay correct even though they stop being maintainable.

One deliberate asymmetry, because it is not a bug: crit is exported but never imported. On the way out it is derived — the editor computed the critical path from the dependency graph, so the tag is true when written. On the way in it is a word somebody typed in a file that may be weeks stale, and trusting it would let an old diagram paint a non-critical chain red. So it is written and then ignored: the critical path you see after an import was recalculated, not asserted.

A useful side effect if you draft schedules with an LLM: ask for Mermaid gantt syntax, paste the answer in, and you have an editable chart with a computed critical path — no API key, no backend.

Templates that use this

• Project Management Gantt Chart Template
• Browse all Gantt chart templates

Keep reading

• Gantt Chart Dependencies Explained: FS, SS, FF and SF
• Critical Path Method (CPM): Steps, Formula & Example
• What Is a Gantt Chart? Definition, Examples & Uses

Frequently asked questions