MermanDraw
Open Editor

Mermaid guide

Mermaid Timeline Diagram: Periods, Events, and Sections

The timeline diagram lists periods in order, each with one or more events, and draws them as a horizontal strip. Periods are free text: years, quarters, months, or version numbers all work because Mermaid does not parse them as dates.

Choose a timeline when you want to show what happened and when, without durations or dependencies. Choose a Gantt chart when bars with start and end dates matter.

  • changelogs
  • project history
  • biographies and case studies
  • release notes

Example

Mermaid Timeline example2024 Q1JanProject startedCore editor builtFebMermaid rendering7 themes addedMarShare featureCloudflare deploy2024 Q2AprPan & ZoomLocal historyMayMonokai Pro themeSyntax highlightJunv1.0 public launchMermanDraw History
timeline
    title MermanDraw History
    section 2024 Q1
        Jan : Project started
            : Core editor built
        Feb : Mermaid rendering
            : 7 themes added
        Mar : Share feature
            : Cloudflare deploy
    section 2024 Q2
        Apr : Pan & Zoom
            : Local history
        May : Monokai Pro theme
            : Syntax highlight
        Jun : v1.0 public launch
Open in editor → Cheatsheet →

Syntax

Periods and events

timeline
    title Product history
    2024 : Prototype
         : First users
    2025 : Public launch
    2026 : Mobile app
         : 10k monthly users
Periods and events — Mermaid timeline2024PrototypeFirst users2025Public launch2026Mobile app10k monthly usersProduct history

A period line is period : event. Continue the same period with lines that start with :.

Try this snippet →

Sections

timeline
    title Release train
    section Early access
        v0.1 : Editor
        v0.2 : Themes
    section General availability
        v1.0 : Share links
        v1.1 : Guides
Sections — Mermaid timelineEarly accessv0.1Editorv0.2ThemesGeneral availabilityv1.0Share linksv1.1GuidesRelease train

Sections colour-band the periods beneath them.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • Long event text that wraps badly.

    Fix: Keep events to a few words. Put detail in the prose under the diagram, or split into more periods.

  • Colon inside an event (2024 : Launch: beta).

    Fix: Only the first colon on a line is structural, but a second one makes the text look like a new event. Rephrase.

Real-world examples

Complete, copy-ready timelines for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

Can periods be dates with days?

Yes, any text works, including 2026-03-14. Ordering is the order you write, not chronological sorting.

Can I make the timeline vertical?

Not in Mermaid 11. For a vertical chronology use a flowchart TD with one node per period.