Skip to main content

Mermaid 11.15.0

Mermaid timeline cheat sheet

A timeline groups short events under ordered period labels. Pick Gantt when dates, durations or dependencies matter; timeline periods are text categories, not a scaled calendar.

Build this in Mermaid Timeline Generator →

Quick start

Write a period, then a colon and its event. A second colon adds another event to the same period.

Mermaid
Open in editor → 
timeline
  title Document lifecycle
  Draft : Outline agreed
  Review : Comments collected : Changes approved
  Release : Guide published

Loading…

Syntax reference

Syntax reference
SyntaxMeaning
timeline / title TextDeclare the timeline and optionally add its heading.
section TextGroup the following periods into a named section.
Period : Event : Another eventOne period can contain several colon-separated events.
: Another eventContinue the preceding period with another event on a new line.
<br>Insert a line break in a period or event label.
config.timeline.disableMulticolorUse one section color for periods instead of cycling colors in an unsectioned timeline.
theme: base / themeVariables.cScale0…cScale11Customize section fills; cScaleLabel0…cScaleLabel11 control label text colors.
%% / accTitle: / accDescr:Add comments and accessible descriptions without adding periods.

Multiple events and continuation lines

Period labels need not be dates. Events after additional colons or on continuation lines belong to the current period. Source order controls the sequence; Mermaid does not sort or validate a calendar.

Mermaid
Open in editor → 
timeline
  title Review notation
  Pass 1 : Structure checked
         : References checked
  Pass 2 : Wording checked : Links checked

Loading…

Sections and readable line breaks

Section applies to the periods that follow it, until another section begins. Keep labels short; use <br> for a deliberate line break rather than adding a new period.

Mermaid
Open in editor → 
timeline
  title Editorial stages
  section Preparation
    Outline<br>review : Scope settled
  section Delivery
    Final<br>review : Corrections merged
    Publication : Readers notified

Loading…

Single-color periods

An unsectioned timeline normally cycles colors by period. Disable multicolor when the periods should share a color. This option changes presentation and does not add time scale or relationships.

Mermaid
Open in editor → 
---
config:
  timeline:
    disableMulticolor: true
---
timeline
  title Approval steps
  Draft : Submitted
  Review : Accepted
  Release : Archived

Loading…

Section colors with a base theme

Use the base theme to customize cScale fills and matching cScaleLabel text colors. Keep contrast readable. Section colors repeat after the palette ends; the configuration belongs before the diagram keyword.

Mermaid
Open in editor → 
---
config:
  theme: base
  themeVariables:
    cScale0: "#d3e5ff"
    cScaleLabel0: "#171717"
    cScale1: "#f5f5f5"
    cScaleLabel1: "#171717"
---
timeline
  title Two-stage review
  section Drafting
    Outline : Ready
  section Publishing
    Guide : Available

Loading…

Common mistakes

Leaving an event empty

Every colon needs event text. A period without a colon is allowed but has no events.

Invalid syntax — corrected example below

timeline
  :

Expecting calendar spacing

A year and a month are only labels here. For proportional time spacing, use a Gantt chart.

Limitations

  • Periods are ordered categories, not dates with proportional spacing.
  • Timeline syntax has no task durations, dependency arrows or point-level coordinates.
  • Long labels and many events can make the rendered layout difficult to read.

Frequently Asked Questions

Can one period contain several events?
Yes. Add more colon-separated events, or continue on a new line beginning with a colon.
How do I change timeline colors?
Use a base theme with cScale0 through cScale11 and matching cScaleLabel variables in frontmatter.
When should I use Gantt instead?
Choose Gantt for actual date intervals, task dependencies and durations. Timeline works better for a short narrative sequence.