Gantt chart

gantt
  title Website relaunch
  dateFormat YYYY-MM-DD
  todayMarker off
  section Discovery
  Project brief          :done, brief, 2024-03-04, 4d
  Stakeholder interviews :done, 2024-03-06, 5d
  section Design
  Wireframes             :active, wire, after brief, 6d
  Visual design          :2024-03-18, 5d
  section Build
  Front end              :crit, build, after wire, 8d
  QA pass                :qa, after build, 3d
  Launch                 :milestone, launch, after qa, 0d

timeline:
  enter section:1 fade, enter brief fade, enter task1 fade
  enter section:2 fade, enter wire slide-right, enter task2 slide-right
  enter section:3 fade, enter build slide-right, enter qa fade
  enter launch fade, highlight launch glow

gantt. Statement keywords (section, dateFormat, title and the rest) are read in any case; the tags (done, crit and the rest) and the duration units are not.

Tasks

A task is Name :data. The data is comma-separated: first any of the tags, then one, two or three fields.

  • Tags, in lower case: done, active, crit, milestone and vert (see Vert markers). crit combines with done or active.
  • end alone: the task starts where the task written before it ends. The first task cannot use this form.
  • start, end.
  • id, start, end. A fourth field is an error.

A start is a date in the dateFormat, or after a b: the latest end of the tasks named. An end is a date in the dateFormat, a duration, or until a b: the earliest start of the tasks named. An id that names no task is warned about; when none of them does, the task starts or ends at the start of today.

  • Durations are a number and a unit: ms, s, m, h, d, w, M (month) or y, as in 3d, 2w or 1.5h. A fraction of a day or longer is rounded to a whole one.
  • Always write dateFormat (YYYY-MM-DD, DD/MM/YYYY, YYYY-MM-DD HH:mm, x for epoch milliseconds, and so on). Without one, an end written as a date is not read, and the task is drawn with no length.
  • inclusiveEndDates makes an end date include its own day.
  • Rows are drawn in the order the tasks are written, whatever their dates, unless the chart is compact.
  • A task’s label is drawn inside its bar when it fits, and beside it otherwise, as in Mermaid.
  • Dates are local time, as in Mermaid.

Sections

section Name starts a section, which runs to the next section. Two sections of the same name are one section. The rows alternate between two band colors.

Excluded days

gantt
  dateFormat YYYY-MM-DD
  excludes weekends, 2024-05-27
  todayMarker off
  section Build
  API    :api, 2024-05-20, 8d
  Client :after api, 3d
  • excludes takes weekends, day names (friday) and dates, comma- or space-separated, and may be written more than once. A task’s end moves past each excluded day it crosses, unless the end is written as a YYYY-MM-DD date. Excluded days are shaded.
  • includes names days that stay working days anyway.
  • weekend friday makes the weekend Friday and Saturday; the default is saturday.

Axis

  • axisFormat takes d3 time-format codes: %Y-%m-%d by default, or %b %d, %H:%M and so on.
  • tickInterval is a whole number and one of millisecond, second, minute, hour, day, week or month (1week, 2day). With week, ticks fall on the weekday, sunday by default.
  • An interval that would draw more than 10,000 ticks is ignored with a warning, so match it to the chart’s span.

Today line

A line is drawn at today. todayMarker off removes it; any other text after todayMarker is a style for the line, with , between declarations (todayMarker stroke-width:3px,stroke:#d6336c). On this site, under a Style or a Custom theme alike, that style is taken over and the line is drawn in --siren-gantt-today-stroke; see Themes.

“Today” is the moment the page draws the chart, so a chart showing the line looks different on another day. The examples on this site turn it off so they always look the same.

Vert markers

gantt
  dateFormat YYYY-MM-DD
  todayMarker off
  section Build
  API         :api, 2024-05-13, 8d
  Code freeze :vert, freeze, 2024-05-20, 0d
  Client      :after api, 5d

A vert task is a thin line up the chart at its start, with its label below the axis. It takes no row and belongs to no section, but it is still the task the next one-field task starts after, it counts toward task1, task2, …, and its dates widen the axis. It is usually written with 0d.

Compact display mode

---
displayMode: compact
---
gantt
  dateFormat YYYY-MM-DD
  todayMarker off
  section Team
  Spec   :2024-05-06, 3d
  Review :2024-05-09, 2d
  Docs   :2024-05-07, 4d

Compact display mode packs each section’s tasks onto shared rows: taken by start, a task goes on the first row whose last task has ended by then. Turn it on with displayMode: compact at the top of the front matter, with config.gantt.displayMode, or with %%{init: {"gantt": {"displayMode": "compact"}}}%%. Only compact, spelled exactly so, packs; any other value draws the usual chart.

A vert marker still reaches as far down as on the unpacked chart, so in a compact chart its line and label run past the chart’s foot, as in Mermaid.

Width

A gantt chart is 1200px wide wherever it is drawn. Front matter config: { gantt: { useWidth: 900 } } sets another width. Every other config.gantt key except displayMode is warned about and not applied.

Interaction

click id href "url" makes a task a link, and click id call fn(args) hands fn to the page. One click may name several ids, comma-separated with no spaces (click a,b href "…"), and may have both a call and an href.

Colors

The row bands, the grid, each status’s bar, the today line, excluded days and vert markers each have a --siren-gantt-* design token; a plain task’s bar is drawn like a node. Task labels, section titles and tick labels take --siren-node-text. See Themes.

Accessibility

title text draws a title above the chart. accTitle: text, accDescr: text and the braced accDescr { … } block give the chart its accessible title and description.

Timeline targets

Element id Example
Task The id written in its data brief (Project brief :done, brief, 2024-03-04, 4d)
Task without an id taskN, counting only the tasks written without one, vert markers included task1
Vert marker Its id, as for a task freeze
Section section:N, in the order the section names first appear section:1
  • A task’s bar and label animate together, as do a vert marker’s line and label.
  • A section’s id reveals its row bands and title, not its tasks; enter the tasks as well.
  • taskN also works after after and until (after task1).

Not yet supported

Syntax Current behavior
topAxis Error, as Mermaid 12.2.0 itself fails on it
A task name starting with a date (2024-05-01 kickoff :…) Error; a year alone (2024 plan :…) is fine
A task name starting with a statement keyword (Title page :…) Read as that statement, as in Mermaid
A line whose second character is % (5% done :…) Read as a comment, with a warning
Mermaid’s bold, recolored label on a clickable task Not copied; the task gets the pointer cursor only