Mermaid Timeline Syntax & Examples
Reference for Mermaid timeline syntax — the timeline keyword, title, sections, and the period : event grammar in both its one-line and multi-line forms. Copy-paste examples for launch recaps, project history, and release notes.
Syntax reference, layout guidance, and ready-to-open examples for this diagram type.
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.
Mermaid timeline constructs, one per row
| Construct | Syntax | Notes |
|---|---|---|
| Diagram keyword | timeline | Must be the first line, on its own. Anything trailing on that line stops it being recognised as a timeline. |
| Chart title | title Social media history | Optional, and the keyword is case-insensitive. Renders above the track. |
| Period grouping | section 21st century | Optional. Groups the periods that follow it into a labelled band, until the next section. |
| Period with one event | 2002 : LinkedIn | Text before the first colon is the period; text after it is an event on that period. |
| Period with several events | 2004 : Facebook : Google | Every further colon starts another event on the same period — not another period. |
| Continue a period on the next line | : Flickr | A line starting with a colon appends more events to the period above it. It errors if no period precedes it. |
| Line break inside an event | 1990 : Machinery <br> Steam power | <br> becomes a real line break in the rendered label — useful for long event text. |
| Comment | %% not rendered | Everything from %% to the end of the line is stripped before parsing. |
Syntax reviewed
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
1timeline2 title Product launch year3 section Q14 Private alpha5 : Initial design reviews6 : First internal demo7 section Q28 Closed beta9 : Invite-only signup10 : First paid customer11 section Q312 Public beta13 : Marketing site live14 : Feedback sprint15 section Q416 GA launch17 : Pricing finalised18 : Partner integrationsWhat 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, on its own line)title <Text>— chart title (appears at the top)section <Period Name>— period grouping (Q1, Phase 1, etc.)<Period> : <Event>— a period and its events, written on one line or split across several
Event format — two ways to write the same rows
A timeline row is a period followed by its events, and the grammar accepts two shapes for it. The one-line form puts everything on a single line: 2002 : LinkedIn. Text before the first colon is the period — the label that sits on the track — and text after it is an event hanging off that period. Every further colon on the line starts another event on the same period, so 2004 : Facebook : Google gives one period with two events, not two periods. The multi-line form splits the same thing across lines: write the period (Public beta), then put each event on its own line starting with a colon (: Marketing site live, : Feedback sprint). Both forms parse to exactly the same diagram, so pick whichever reads better in source — one-line for short chronologies where the period is a bare year, multi-line when event text is long enough that one line becomes unreadable. You can mix them freely in the same diagram.
2002 : LinkedIn— period and event on one line2004 : Facebook : Google— one period, two events (extra colons add events, not periods): Flickr— a leading colon appends another event to the period above1990 : Machinery <br> Steam power—<br>breaks the line inside an event label
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