← All diagram types

Mermaid timeline syntax: periods, events and sections with examples

Mermaid timeline syntax with rendered examples: periods on a lane, several events per period, titled charts and section bands grouping the chronology.

A timeline puts events on a horizontal line in date order: releases, company milestones, project phases. Mermaid's timeline syntax is little more than a list of period : event lines, and the layout does the rest.

Everything on this page is rendered by makesPDF's own Mermaid renderer, so a ```mermaid block produces exactly this in the PDF.

Periods and events

Each line starts with the period label, then a colon, then the event text. Periods run left to right in the order written:

mermaid
timeline
  title Release history
  2023 : First public beta
  2024 : Templates API
  2025 : Canvas support
  2026 : PDF/UA validation
Render this to PDF →How diagram blocks work

title is optional; without it the lane starts straight at the first period.

Several events per period

A second colon adds another event to the same period. Both are stacked underneath it, so a busy year stays in one column instead of stretching the width:

mermaid
timeline
  title Company milestones
  2019 : Founded : First paying customer
  2021 : Seed round : Team of five
  2023 : Series A : 10,000 users
  2025 : Profitable : Opened an office
Render this to PDF →How diagram blocks work

Event text wraps inside the card, so a sentence is fine — but short phrases read better on a crowded lane.

Sections

section groups periods under a coloured band with a heading of its own. Use it for phases, years, or departments:

mermaid
timeline
  title Website rebuild
  section Discovery
    January : Stakeholder interviews : Analytics review
    February : Content audit
  section Build
    March : Design system : Component library
    April : Page templates
  section Launch
    May : Beta : Redirect map
    June : Public launch
Render this to PDF →How diagram blocks work

The section band spans the periods below it and cycles through the palette, so two sections are visually distinct without any configuration.

A period can be anything: Q1 2026, Week 12, Phase 2. Mermaid does not parse the label as a date — it is drawn as written, which is what makes quarters and sprints work as well as years.

Not supported in makesPDF yet: event cards are laid out one under another as written; there is no way to colour an individual period or event (styling statements are parsed and ignored), and the lane does not scroll — a timeline with many periods simply gets wider.