Skip to content
MermaidViewer

Planning diagram

Mermaid Gantt chart

Mermaid Gantt chart syntax for dates, sections, dependencies and milestones, with a roadmap you can edit and export as PNG.

By MermaidViewer editorsPublished Updated

Basic gantt chart example

Basic gantt chart example diagram
mermaid
gantt
    title Website Launch Plan
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Design
      Research           :done,    r1, 2026-01-05, 5d
      Wireframes         :done,    w1, after r1, 4d
      Visual design      :active,  v1, after w1, 6d
    section Build
      Frontend           :         f1, after v1, 10d
      Backend API        :         b1, after w1, 12d
      QA                 :crit,    q1, after f1, 4d
    section Launch
      Go live            :milestone, m1, after q1, 0d
Open in the live editor

Gantt charts show a project schedule: which tasks happen when, how long they take and which ones depend on others. Mermaid Gantt charts let you write the plan as text and get a properly scaled timeline.

They're perfect for roadmaps in README files, sprint plans in Notion or Confluence, and launch checklists that need to be updated frequently without opening a heavyweight project tool.

When to use a gantt chart

  • Product roadmaps and release plans
  • Sprint and milestone planning
  • Event and launch schedules
  • Academic project timelines

Gantt Chart syntax reference

SyntaxWhat it does
ganttStart a Gantt chart.
title TextChart title.
dateFormat YYYY-MM-DDHow dates are written in the task list.
axisFormat %b %dHow dates are shown on the axis (d3 time format).
section NameGroup tasks into a section.
Task :id, 2026-01-01, 3dTask with id, start date and duration.
Task :after id, 5dStart after another task finishes.
done / active / crit / milestoneStatus tags that change color or shape.
excludes weekendsSkip weekends when computing durations.
todayMarker offHide the vertical line for today.

Gantt Chart examples

Sprint plan excluding weekends

excludes weekends makes durations count working days only.

Sprint plan excluding weekends diagram
mermaid
gantt
    title Sprint 14
    dateFormat YYYY-MM-DD
    excludes weekends
    section Stories
      Auth refactor     :a1, 2026-03-02, 3d
      Billing page      :a2, after a1, 4d
      Bug bash          :crit, a3, after a2, 2d
    section Release
      Release 2.4       :milestone, after a3, 0d
Open in the live editor

Dates, durations, and "this starts when that ends" are the whole chart. A mermaid gantt chart is a schedule with start dates and durations. If you can't say how many days a bar lasts, you don't have a Gantt yet. The syntax table lists dateFormat, sections, and after. This section shows how those three interact on a short launch plan.

Ids, sections, and the format string

dateFormat YYYY-MM-DD is a contract with every date in the file. Write the dates in that pattern. A chart full of 05/04/2026 next to a year-first format won't land on the day you meant, even when the preview draws something.

Each task can carry an id after the first colon: Write API :api, 2026-05-04, 5d. The words before the colon are the label. api is the id. after looks up the id, not the label. after api means "start when the API bar ends." after Write API looks for an id you never created.

5d is the duration. You can also write an end date, but a duration is easier to read in review, because a slipped start doesn't force you to recompute the end by hand.

section bands the chart. Build, Ship, and Tell are swimlanes. They don't create dependencies. Only after does that. A section with one task is fine. A chart with no sections is one long lane, and the labels start to collide.

Worked example

The API is five days from 4 May 2026. Docs start when the API bar ends, and they take three days. The announcement waits on the docs.

Mermaid diagram
mermaid
gantt
    title Launch
    dateFormat YYYY-MM-DD
    section Build
    Write API :api, 2026-05-04, 5d
    section Ship
    Docs :docs, after api, 3d
    Announce :news, after docs, 2d
Open in the live editor

api starts on a fixed day because something outside the chart, a staffing date, chose it. docs has no calendar date. It's tied to api, so if you move the API to 11 May, the docs bar follows. news is tied to docs, not to api, which is the dependency you actually mean. Announcing when the API ends, while the docs are still open, is a different plan. Change after docs to after api if that's the real policy.

The section names are for readers, not for the scheduler. "Ship" holds both docs and the announcement because the same people do them. If marketing owns the announcement, give it a section. The bars stay put.

Keep the title specific. "Launch" is a bit bare. "May launch" is better once you have two charts in one doc. The title is the only heading the rendered chart carries. Leave weekends and holidays out of a first draft. A 5d bar is five duration days, and a stakeholder can still read the sequence. Add a calendar nuance in the caption if a particular Friday matters.

When this is the wrong diagram

A timeline is the better picture when you have eras and events and no durations. A kanban diagram is the better picture when the work has a column and no dates. Use a Gantt chart when a bar's length and its start, relative to another bar, are the facts you need on the page.

Common mistakes

  1. Pointing after at the visible title. The dependency token is the id after the colon, so the docs bar should say after api.
  2. Mixing date patterns. dateFormat YYYY-MM-DD wants 2026-05-04. A month-first string won't sit on the day you picked.
  3. Forgetting the duration, so a task is only a name and Mermaid has no bar length to draw. 5d or an end date belongs on the task.
  4. Encoding dependencies only by section order. Sections are bands. If Docs must follow the API, say after api.

Where to go next

The AI Gantt generator can draft sections from a plan written in sentences. Check every after id in the editor, and the cheat sheet keeps the task form on one line. The project roadmap template is a longer schedule if this launch is too small to copy.

Dates you can defend

Every task needs a start you could point to in a ticket, and a duration you could point to in an estimate. A bar that exists only to fill a gap will be questioned in the first review. Milestones are dates, not tasks: use them for the release, not for a week of work.

Tips and best practices

  • Give tasks ids so you can chain them with after id; the plan then updates automatically when a duration changes.
  • Use crit for the critical path and milestone for fixed dates like launches.
  • Set axisFormat to something compact (%b %d or %W for week numbers) on long projects.

Generate a gantt chart with AI

Not sure where to start? Describe what you need and the AI gantt chart generator writes the Mermaid code for you. Try prompts like:

  • “Mobile app MVP plan over 8 weeks”
  • “Conference organisation timeline”
  • “Data migration project with testing phases”

Gantt Chart templates

Gantt Chart FAQ

How do I add dependencies between Gantt tasks?

Give the first task an id and start the second with after id, for example Build :b1, after d1, 5d. Multiple ids can be listed: after a1 b2.

How do I add a milestone?

Add the milestone tag and a 0d duration: Launch :milestone, m1, 2026-06-01, 0d.

Can Mermaid Gantt charts skip weekends or holidays?

Yes. Use excludes weekends, and list specific dates too: excludes weekends, 2026-12-25.