🕰️ Mermaid

Timeline

Tell a story year by year

Open this example in the editor Generate one with AI

What is a Timeline?

A timeline lays events chronologically: company history, project milestones, product evolution, incident retrospectives. Mermaid timelines group multiple events per period and stay readable at any size.

Timelines are the diagram of the retrospective: incident postmortems, company history slides, the “how did we get here” section of a strategy document. They are unusually good at making gaps visible — three events in March and nothing until September is a story by itself. What they cannot do is scale: periods are labels, spaced evenly whatever the interval, and nothing is sorted for you. A period also carries nothing but text — no owner, no link, no status to filter on.

Live example

Mermaid code

timeline
    title History of the project
    2024 : Idea & prototype
    2025 : First customers
         : Seed funding
    2026 : EU expansion
         : AI features

Live example

When to use it

Present company or product history

Document incident timelines for postmortems

Show roadmap milestones by quarter or year

Common mistakes

Periods are never sorted

Mermaid draws periods in the order you wrote them, so a 2026 entry above a 2024 one stays above it. There is no chronological check and no warning — sort the source yourself before publishing.

Periods above the first section vanish

As soon as a timeline contains one section, every period declared before that first section line is dropped from the render, silently and without an error. Give those early periods a section of their own, or use no sections.

Sentences instead of events

Event text wraps at a fixed width, so a full sentence becomes four stacked lines and inflates the height of the whole chart. Keep events to a few words and put the detail in the surrounding document.

Basic syntax

.mmd

timeline
    title My timeline
    2025 : Event A
         : Event B
    2026 : Event C

timeline title History of the project
The title is optional but does the work of a caption, which matters as soon as the diagram is exported on its own into a slide or a postmortem.
2025 : First customers
The left side of the colon is the period label — a year, a quarter, Sprint 12, anything at all. It is never parsed as a date, so any format works.
2024 : Idea : Prototype
Extra colons on the same line add further events to the same period, which keeps the source compact when one year holds several notable moments.
section Early days 2024 : Idea
Sections group consecutive periods into an era and colour them together — useful to separate before and after a funding round, a migration or an outage.

Questions about this diagram

Can one period contain several events?

Yes — add extra lines starting with “:” under the same period and they stack vertically under that date.

Timeline or Gantt chart?

Timeline for past or high-level storytelling (events at dates). Gantt for planning work (tasks with durations and dependencies).

Can I add a Mermaid timeline to a Confluence postmortem?

Confluence has no native Mermaid support, so use a Marketplace macro or paste an exported SVG or PNG. GitHub and GitLab render timelines straight from a fenced block, so incident write-ups kept in a repo need no extra tooling.

How do I colour the sections of a timeline?

Sections take their colours from the theme scale. Override them with an init directive on the first line — %%{init: {"themeVariables": {"cScale0": "#4f46e5"}}}%% — where cScale0 is the first section, cScale1 the second, up to cScale11. The palette is baked into the exported SVG.

Can I make a timeline vertical?

No — timelines render horizontally and there is no direction setting. It never wraps: the diagram only gets wider. For a long history that has to fit a narrow column, a top-down flowchart or a gitGraph TB: will use the available space far better.

Can I turn an incident report into a timeline automatically?

Paste the write-up into Mermaid Studio and the AI extracts the dated events into a timeline you can then edit. Treat it as a first draft: periods keep the order they were extracted in, so check the chronology before publishing.

Timeline or another diagram type?

Timeline or user journey?

Both lay steps out left to right. A timeline is about when: dated events, no actor, no scoring. A journey is about how it felt: ordered steps, an actor, a satisfaction score. If nobody experienced the events, you want a timeline.

Timeline or Git graph?

A timeline is flat — every event sits on one line. A git graph branches, and its lanes rejoin. Release history with parallel maintenance branches needs the git graph; a product story where the sequence matters and the parallelism does not needs the timeline.

Explore other diagram types

🔀 Flowchart 💬 Sequence diagram 🧩 Class diagram 🗄️ Entity-relationship diagram 🔄 State diagram 📅 Gantt chart 🥧 Pie chart 🧠 Mind map 🌿 Git graph 🚶 User journey 🎯 Quadrant chart

Create your Timeline now

Describe it in plain language — the AI writes the Mermaid code for you.

Open Mermaid Studio