Mermaid timeline examples

A mermaid timeline starts with the timeline keyword, followed by an optional title and one line per time period — period : event, with extra colons for extra events. Every example below is rendered live from the code next to it; copy any of them as a starting point. Updated August 29, 2026.

Basic timeline

The whole syntax in four lines: the timeline keyword, an optional title, then one time period per line with events after colons.

timeline
    title History of Social Media
    2002 : LinkedIn founded
    2004 : Facebook launches
    2006 : Twitter goes live
    2010 : Instagram appears

Multiple events per period

Chain extra events onto one period with additional colons — either on the same line or indented on the following lines.

timeline
    title Product Year One
    Q1 : Prototype built
       : First user interviews
    Q2 : Private beta
       : Pricing decided
    Q3 : Public launch
       : First 1,000 users
    Q4 : Break even

Sections (eras)

Group periods into named eras with the section keyword. Each section gets its own background color band automatically.

timeline
    title Programming Languages by Era
    section Foundations
        1957 : Fortran
        1972 : C
    section Object Orientation
        1983 : C++
        1995 : Java : JavaScript
    section Modern Era
        2009 : Go
        2014 : Swift

Project roadmap

Timelines read better than Gantt charts for high-level roadmaps where exact durations don’t matter — only order and grouping do.

timeline
    title Migration Roadmap
    section Preparation
        Week 1 : Audit current schema
        Week 2 : Write migration scripts
               : Set up staging
    section Execution
        Week 3 : Dry run on staging
        Week 4 : Production migration
    section Cleanup
        Week 5 : Remove legacy tables
               : Retro

How do you embed a timeline in markdown?

Put the code in a fenced block tagged mermaid (the copy buttons above include the fence). GitHub, GitLab, Obsidian, Notion, and Docs MD share pages render it as a diagram automatically — paste one into the editor here to see it live, or check the full fence syntax on the cheat sheet.

Why is my timeline not rendering?

The usual causes: the renderer ships a mermaid version older than 9.4 (when timeline landed); the fence is tagged with nothing or text instead of mermaid; or a colon appears inside an event's text — colons are the delimiter, so write “Launch — v2” with a dash instead. Long event text wraps automatically, but very long period labels don't; keep periods short.

Timeline vs Gantt — which should you use?

A timeline shows what happened when — discrete periods with events, no durations or dependencies. A Gantt chart (mermaid's gantt keyword) models start dates, durations, and task dependencies. If your data is “era → things that happened”, timeline reads far better; if it's “task A blocks task B”, use Gantt.