Markko › Learn
Mermaid diagrams

Mermaid Gantt charts

Updated 2026-10-10
In short: Write gantt on the first line, set a dateFormat, then list tasks as Name :id, start, duration. Use after id to chain tasks and milestone for key dates.

A Gantt chart shows tasks on a timeline. Each task is a bar that starts on a date and runs for a duration. Mermaid lets you write a Gantt chart as plain text in a Markdown file, next to the plan it belongs to. This page covers the date format, sections, tasks, dependencies and milestones.

The smallest Gantt chart

Start a fenced code block marked mermaid, write gantt on the first line, and set a dateFormat. Then list the tasks.

gantt
    dateFormat YYYY-MM-DD
    Write draft :2026-11-02, 5d
    Review      :2026-11-09, 2d

Each task line has a name, a colon, a start date and a duration. Durations use units such as d for days, w for weeks and h for hours.

Instead of a duration you can give an end date, as in :2026-11-02, 2026-11-06. Durations are usually easier to maintain, because the plan still makes sense when a start date moves. The spaces before the colon are only there to line things up. Mermaid ignores them.

Title, date format and axis

A few setup lines go at the top of the chart.

  • title adds a heading above the chart.
  • dateFormat tells Mermaid how to read the dates you type.
  • axisFormat sets how dates appear on the axis, using codes like %d %b for “02 Nov”.
  • excludes weekends skips Saturdays and Sundays when counting days.
gantt
    title Website relaunch
    dateFormat YYYY-MM-DD
    axisFormat %d %b
    excludes weekends
    Content       :2026-11-02, 10d
    Design        :2026-11-02, 6d

With excludes weekends, a 10-day task covers ten working days, so its bar spans two calendar weeks.

Sections

Sections group related tasks under a label on the left. Start each group with section and a name. All tasks below belong to that section until the next one starts.

gantt
    title App release
    dateFormat YYYY-MM-DD
    section Build
        Feature work   :2026-11-02, 14d
        Bug fixing     :2026-11-16, 7d
    section Launch
        Store listing  :2026-11-16, 5d
        Release        :2026-11-23, 1d

Indentation is optional. It just makes the source easier to read. Tasks appear in the order you write them, from top to bottom. Sections work well for phases, teams or work streams. Pick one way to group and keep it for the whole chart.

Task IDs and dependencies

Most plans have tasks that wait for others. Give a task an ID, then start the next task with after and that ID. Mermaid works out the dates for you.

gantt
    dateFormat YYYY-MM-DD
    section Docs
        Outline       :d1, 2026-11-02, 2d
        First draft   :d2, after d1, 5d
        Edit          :d3, after d2, 3d
        Publish       :d4, after d3, 1d

The order of the parts is: optional tags, optional ID, start, then duration or end date. If you change the length of Outline, every later task moves with it.

A task can wait for several others. List the IDs after after, separated by spaces. The task then starts when the last of them ends.

gantt
    dateFormat YYYY-MM-DD
    Backend   :b1, 2026-11-02, 6d
    Frontend  :f1, 2026-11-02, 4d
    Testing   :t1, after b1 f1, 3d

Milestones

A milestone marks a single moment, like a deadline or a release. Add the milestone tag and give it a duration of 0d. It appears as a diamond.

gantt
    dateFormat YYYY-MM-DD
    section Beta
        Beta build      :b1, 2026-11-02, 10d
        Beta ships      :milestone, m1, after b1, 0d
    section Final
        Feedback round  :f1, after m1, 5d
        Release         :milestone, m2, after f1, 0d

Status tags

Tags change how a bar looks. They go first, before the ID.

  • done marks finished work.
  • active marks work in progress.
  • crit highlights critical tasks, often in red.

You can combine tags, for example crit, active.

gantt
    dateFormat YYYY-MM-DD
    section Sprint
        Spec            :done, s1, 2026-11-02, 3d
        Implementation  :active, s2, after s1, 5d
        Security review :crit, s3, after s2, 2d
        Release         :milestone, s4, after s3, 0d

The exact colours depend on the theme of the tool that draws the chart.

Comments and common mistakes

Lines that start with %% are comments.

  • If the chart does not draw, check that your dates match dateFormat exactly.
  • An after reference must point to an ID, not a task name.
  • Keep task names free of colons. The first colon starts the task data.
  • Very long charts get hard to read. Split them by phase or by team.

Viewing Gantt charts on a Mac

The text form of a Gantt chart is easy to read and easy to diff. To see the bars you need a tool that renders Mermaid, such as GitHub, an editor preview, or a Markdown viewer. Markko Pro draws Mermaid charts in its window and in Quick Look. Live reload updates the chart each time you save the file.

For all options, see the Gantt page of the official Mermaid documentation at mermaid.js.org.

FAQ

Which date format should I use?

YYYY-MM-DD is the safest choice. It is unambiguous and is the format most examples use. The dateFormat line tells Mermaid how to read your dates, and axisFormat controls how they appear on the axis.

How do I make a task start when another one ends?

Give the first task an ID and use after followed by that ID as the start of the second task, for example :t2, after t1, 3d.

How do I skip weekends?

Add excludes weekends. Durations then count only working days, and the excluded days are shaded on the chart.

Why does a milestone need a duration?

The milestone tag marks a point in time. Give it 0d so it does not take up a span on the chart.

Related

Mermaid diagramsMermaid flowchartsMermaid diagramsMermaid sequence diagrams
Read your Markdown in MarkkoFree on the Mac App Store. Quick Look, live reload and themes included.
Coming soon to the Mac App Store
Markko — the Markdown viewer for Mac. Free.Coming soon to the Mac App Store