Beauty Diagram
Diagram type

Mermaid Timeline Syntax & Examples

Reference for Mermaid timeline syntax — timeline keyword, title, sections, period headings, and event lines. Copy-paste examples for launch recaps, project history, and release notes.

Syntax reference, layout guidance, and ready-to-open examples for this diagram type.

At a glance

A syntax reference for Mermaid's `timeline` grammar — read this when you need the exact format for sections, period headings, or multi-line events, then try the result in the editor.

What is a Mermaid timelineBasic syntax — timeline + title + sectionsEvent format — period heading + detail bulletsWithout sections — flat chronologyWhen to pick a different chartCommon patterns & gotchas
Rendered proof
Timeline of a product launch year.
Theme · Brutalist
Open this diagram in editor
TIMELINE Product launch year Q1 Q2 Q3 Q4 Private alpha Initial design reviews First internal demo Closed beta Invite-only signup First paid customer Public beta Marketing site live Feedback sprint GA launch Pricing finalised Partner integrations
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
diagram.mmd
1timeline
2  title Product launch year
3  section Q1
4    Private alpha
5    : Initial design reviews
6    : First internal demo
7  section Q2
8    Closed beta
9    : Invite-only signup
10    : First paid customer
11  section Q3
12    Public beta
13    : Marketing site live
14    : Feedback sprint
15  section Q4
16    GA launch
17    : Pricing finalised
18    : Partner integrations

What is a Mermaid timeline

A timeline visualises events in chronological order along a single track. It is the right shape when the story is chronology-first: product launch recaps, project history, incident retrospectives, release notes, company milestones. Timelines read top-to-bottom in one pass, with periods grouping events into meaningful chunks (quarters, releases, phases). Use a Gantt chart instead when parallel work streams matter (timelines have one track, no swimlanes), or a flowchart when the events are decision-driven rather than time-driven. Timelines are simpler than both — they're for stories where the only structure is what-happened-when.

Basic syntax — timeline + title + sections

Every Mermaid timeline starts with the `timeline` keyword. Add a title on the next line with `title <Text>`. Then declare sections with `section <Period Name>` — each section groups events under a period heading. Events under a section are listed as bullet-style lines: `Period Label` followed by colon-prefixed `: event description` lines. Sections render as horizontal bands with the section label on the left, and events flow vertically under each section in source order. Mermaid auto-handles colour rotation across sections so each period reads distinctly.

  • `timeline` — diagram type keyword (always first)
  • `title <Text>` — chart title (appears at the top)
  • `section <Period Name>` — period grouping (Q1, Phase 1, etc.)
  • Events are bullet-formatted lines under each section

Event format — period heading + detail bullets

Inside a section, an event has two parts. The first line is the period label or main event name: `Public beta`. Following lines starting with `:` are detail bullets attached to that event: `: Marketing site live`, `: Feedback sprint`. The colon-prefixed bullets render under the main event heading. This format lets each event tell a small story — the period label is the headline, the bullets are the supporting details. You can have multiple events per section, each with its own bullets, by repeating the pattern.

Without sections — flat chronology

Sections are optional. If your timeline is short or doesn't have natural period groupings, list events directly under the title without any `section` declarations. The events still render in source order but without the horizontal banding. This is appropriate for short timelines (5-8 events) where every event is roughly equal weight. Once a timeline gets longer or has natural chunks (quarters, phases, releases), sections make it much more scannable — readers can jump to the section that interests them rather than reading top-to-bottom.

When to pick a different chart

Timelines are deliberately minimal — no swimlanes, no dependencies, no parallel tracks. When the content needs those features, pick a different diagram type. Gantt chart: parallel work streams (multiple teams or phases running concurrently), task dependencies ("X starts after Y finishes"), specific date math (durations in days/weeks). Git graph: branching workflows where things diverge and merge. Flowchart: decision-driven processes where the order depends on outcomes. Pick timeline only when the story is genuinely a single linear chronology — even one parallel branch makes a Gantt chart a better fit.

Common patterns & gotchas

Three patterns cover most real timelines. Product launch year (Q1 alpha / Q2 beta / Q3 public beta / Q4 GA) is the most common — sections per quarter, 2-3 events per quarter. Incident retrospective (Detection / Triage / Recovery / Postmortem) is the second — sections per phase, events showing what happened in each phase. Company milestones (Founded / First customer / Series A / IPO) is the third — usually no sections, just a flat list of significant events. The most common gotcha: forgetting that event detail bullets must start with `:` — without the colon, the line becomes a separate event rather than a detail of the previous one. Second gotcha: trying to use a timeline for a roadmap with parallel work — switch to Gantt before you fight the syntax.

  • Detail bullets must start with `:` — otherwise they parse as new events
  • 6-8 events per section is the readability sweet spot
  • For parallel work streams or task dependencies, use Gantt instead
FAQ

Mermaid Timeline Syntax & Examples — frequently asked questions

How do I structure a Mermaid timeline?

Start with `timeline`, add a `title` line, then declare `section` lines for each period (quarter, phase, release). Under each section, list events as alternating period headings and colon-prefixed detail bullets: `Public beta` followed by `: Marketing site live` and `: Feedback sprint`. The period heading is the headline, the colon bullets are the supporting details. Sections render as horizontal bands; events flow vertically under each. For short timelines without natural period groupings, skip sections and list events directly.

How is a timeline different from a Gantt chart?

Timelines have one track of events with no parallel streams; Gantt charts have swimlanes for multiple teams or phases running concurrently. Timelines have no task dependencies ("X starts after Y"); Gantt has full dependency notation. Timelines have no specific durations — events are just points in time; Gantt has bars with start dates and durations. Pick timeline for retrospective stories ("here's what happened in order"); pick Gantt for prospective planning ("here's what needs to happen and how the pieces depend on each other").

Can I have a timeline without sections?

Yes. Sections are optional. For short timelines (5-8 events) where every event is roughly equal weight, listing events directly under the title without `section` declarations works fine. The events still render in source order but without horizontal banding. Once a timeline gets longer or has natural chunks (quarters, phases, releases), sections make it much more scannable — readers can jump to a section that interests them rather than reading top-to-bottom. As a rule of thumb: add sections at the 6th event.

What's the difference between a period heading and a detail bullet?

A period heading is the main event name — a bare line of text under a section, no colon prefix: `Public beta`. A detail bullet is supporting context for the period above it — starts with `:` and a space: `: Marketing site live`. Each period heading can have multiple detail bullets, all starting with `:`. The heading appears as a labelled node on the timeline; bullets render under it as supporting list items. Without the colon, Mermaid treats the line as another period heading, which breaks the visual hierarchy.

Why does my timeline render with too many top-level events?

Almost always because detail bullets are missing their leading `:`. Every line that should be a sub-bullet of the period above it needs to start with `: ` (colon + space). Without the colon, Mermaid parses each line as its own period heading. Open the source and check that every detail bullet starts with `:`; lines without the prefix have been silently promoted to top-level events. This is the most common timeline syntax bug.