Reference
Mermaid timeline syntax — the complete reference
Mermaid's timeline diagram turns indented text into a horizontal timeline of periods and events. The entire syntax is five ideas — here they all are, with copy-paste examples, the common errors, and where the diagram type stops being the right tool.
The basic syntax
A timeline starts with the timeline keyword. Every following line is either a title, a section, or a time period with events attached by colons:
timeline
title History of social media
2002 : LinkedIn founded
2004 : Facebook launches
: Google acquires Picasa
2005 : YouTube goes live
2006 : Twitter opens to the publicEach period : event line becomes a column. A line that begins with a bare : adds another event to the period above it — that's how one year holds several entries.
Sections group periods
section lines band the timeline into colored eras. Every period after a section belongs to it until the next section:
timeline
title Product roadmap
section Q1 — Foundation
January : Kickoff : Hiring complete
February : Architecture locked
section Q2 — Build
April : Private alpha
May : Feedback sprint
section Q3 — Launch
July : Public beta
September : GA releaseMultiple events per period
Two equivalent forms: chain colons on one line, or continue on the next line with a leading colon. Long event text wraps automatically inside its box.
timeline
2023 : GPT-4 ships : Llama leaks : Mistral founded
2024 : Reasoning models arrive
: Open weights close the gapStyling and configuration
Each section cycles through the theme palette automatically. To turn the multicolor banding off, set disableMulticolor; to restyle, override the cScale0–cScale11 theme variables in an init directive:
%%{init: { 'theme': 'base', 'timeline': { 'disableMulticolor': true },
'themeVariables': { 'cScale0': '#1f6f8b', 'cScale1': '#99a8b2' } }}%%
timeline
title Muted palette
2024 : One
2025 : TwoCommon errors and fixes
| Symptom | Cause → fix |
|---|---|
| “No diagram type detected” | The first line isn't exactly timeline — check spelling and remove leading spaces before the keyword. |
| Events merge into one box | A colon is missing between events — every event needs its own : text segment. |
| Everything lands in one section | section lines must be less indented than their periods; inconsistent indentation attaches periods to the wrong section. |
| A colon inside event text breaks the row | Colons are the delimiter. Rephrase (use a dash) — there is no escape character in timeline syntax. |
| Renders as plain text in your tool | The host doesn't support Mermaid 9.3+ — timeline is newer than flowchart/sequence support in many wikis. GitHub, GitLab, Obsidian and Notion render it; check your tool's Mermaid version. |
Where timeline syntax stops scaling
Timeline is deliberately minimal: no dependencies, no durations, no overlapping eras — for those you want a Gantt chart or a real flowchart. And once the content outgrows hand-written syntax, describing what you want becomes faster than maintaining it: ChartCraft's AI diagram generator takes the plain-English description — “a roadmap with three phases, kickoff in January…” — and draws the diagram with no syntax at all. It's a different notation (flowcharts, ERDs, sequence, state, BPMN rather than timelines), but for process and system diagrams it replaces the syntax-error loop entirely, and it's why this reference lives here: we read a lot of diagram syntax so you don't have to.
Questions
How do I make a timeline in Mermaid?
Start a code block with the keyword timeline, optionally add a title line, then write one line per time period in the form “2024 : What happened”. Add more events to the same period with additional colon-prefixed segments or continuation lines.
How do I add multiple events to one period in a Mermaid timeline?
Chain them with colons on one line (2024 : Event one : Event two) or continue on the next line starting with a colon. Both render as stacked event boxes above the same period.
Does GitHub render Mermaid timelines?
Yes — GitHub Markdown renders timeline diagrams in mermaid code fences, as do GitLab, Obsidian, and Notion. Tools pinned to Mermaid versions older than 9.3 will show the code as text instead.
How do I change the colors of a Mermaid timeline?
Sections color automatically from the theme's cScale palette. Override cScale0 through cScale11 via an %%{init}%% directive with theme “base”, or set timeline.disableMulticolor to true for a single color.
Can a Mermaid timeline show durations or dependencies?
No — periods are evenly spaced labels, not scaled time, and there are no arrows between events. For durations and dependencies use a Gantt chart; for branching processes use a flowchart.