TryMermaid

Mermaid Timeline Diagram

Write timelines in Mermaid code and watch them render as you type. Start from the example below, then export PNG or SVG, share a link or embed the diagram.

Updated · Code editor with live preview

Timeline example

Rendering preview…

timeline
    title History of the web
    1991 : First website goes live
    1995 : JavaScript is created
    2004 : Web 2.0 era begins
    2008 : Google Chrome is released
Open this example in the editor Start a blank diagram

What is a timeline?

A timeline diagram lists events in chronological order, with one or more events under each date or period. It is a simple way to tell the story of a product, a project or a stretch of history. In Mermaid a timeline starts with the timeline keyword.

When to use a timeline

  • Company or product history pages
  • Release and version histories
  • Project retrospectives
  • Explaining how something changed over time

How to make a timeline in Mermaid

  1. Step 1

    Open the editor

    Open TryMermaid with the example on this page, or start a new diagram with timeline on the first line.

  2. Step 2

    Add periods and events

    Write one period per line followed by its events, separated by colons, such as 2008 : Google Chrome is released.

  3. Step 3

    Group into sections

    Add section lines, such as section 1990s, to group periods into eras that share a color.

  4. Step 4

    Export or share

    Check the live preview, then export the timeline as PNG or SVG or copy a share link.

Mermaid timeline syntax at a glance

A Mermaid timeline is plain text. The first line is the timeline keyword. An optional title line follows. Every other line is a period, then a colon, then an event: 1991 : First website goes live.

A period is any text before the first colon, so it can be a year, a date, a quarter, a sprint or a name. Mermaid draws one column per period, left to right, in the order you write them.

Sections and colors

Add section lines to group periods into eras, such as section 1990s or section Beta. Every period below a section line belongs to it until the next section, and the periods in one section share a color.

Without sections, Mermaid gives each period its own color. To draw the whole timeline in one color, set disableMulticolor to true under timeline in the diagram config.

Timeline or Gantt chart?

Use a timeline when the order of events matters more than the gaps between them: a company history, a changelog, a retrospective or the background to a decision.

Use a Gantt chart instead when you are planning work with start dates, durations and dependencies. A timeline has no calendar, so it cannot show that one task takes longer than another.

More worked examples

A release history with sections

Sections group periods into eras, and every period in a section shares its color. Periods are plain text, so quarters work as well as years.

Rendering preview…

timeline
    title Product release history
    section 2025
        Q1 : Private beta
        Q3 : Public launch : Free plan opens
    section 2026
        Q1 : Visual editor
        Q2 : Spanish site
           : API for AI agents

A project retrospective by week

Periods do not have to be dates. Weeks, sprints or phases read just as well, and an event on its own line under a period adds to that period.

Rendering preview…

timeline
    title Website redesign
    Week 1 : Kickoff : Audit the old site
    Week 2 : Wireframes
    Week 3 : Visual design
    Week 4 : Build
           : Content migration
    Week 5 : Launch

Historical events with line breaks

A <br> inside an event breaks the text onto a second line, which keeps long labels from stretching the column.

Rendering preview…

timeline
    title Space exploration milestones
    1957 : Sputnik 1<br>first artificial satellite
    1961 : Yuri Gagarin orbits Earth
    1969 : Apollo 11 lands on the Moon
    1990 : Hubble Space Telescope launched

Timeline syntax cheat sheet

ElementSyntaxWhat it does
Titletitle History of the webHeading above the timeline
Event2004 : EventPeriod and one event
Several events2004 : Event one : Event twoMore events for one period
Event on its own line: Another eventContinues the period above
Sectionsection 1990sGroups periods into an era

Common mistakes and how to fix them

  • An event shows up as an empty period

    Fix: Put the colon between the period and the event: 2008 : Chrome is released. A line with no colon is read as a period with no events.

  • One event is split into two boxes

    Fix: Remove the colon from the event text or replace it with a dash. Each colon starts a new event, so v1.0: launch becomes two events.

  • Events appear out of order

    Fix: Write the periods in the order they happened. Mermaid draws them in the order they appear in the code and does not sort dates.

  • The timeline is very wide and hard to read

    Fix: Shorten the label or break it with <br>. Long events widen every column, which squeezes the whole timeline.

Timeline FAQ

How do I add a title to a Mermaid timeline?

Put title and the text on the second line, directly after the timeline keyword, for example title History of the web. The title is optional; without it the timeline starts straight at the first period.

Can one date have more than one event?

Yes. Either chain events on the same line, such as 2004 : Event one : Event two, or put each extra event on its own line, starting with a colon, directly below the period.

Can I use a colon inside a timeline event?

No. The colon is what separates a period from its events and one event from the next, so a colon inside the text splits it in two. Rephrase with a dash or the word "to" instead, as in v2 - the big rewrite.

Can I make a timeline chart from code?

Yes. A timeline is a chart drawn from code: write the timeline keyword, then one period per line with its events after a colon, such as 2008 : Chrome is released. Paste that into any Mermaid renderer, or the editor on this page, and it draws the chart.

Are the periods on a Mermaid timeline spaced to scale?

No. Every period gets a column of the same width, whether the gap between them is a day or a century. If the spacing has to reflect real time, use a Gantt chart, which draws tasks on a calendar.

Does GitHub render Mermaid timelines?

Yes. Put the code in a fenced code block marked mermaid in any Markdown file, issue or pull request, and GitHub draws the timeline in place.

What is the difference between a timeline and a Gantt chart?

A timeline lists events in order without durations, which suits histories and changelogs. A Gantt chart places tasks on a real calendar with start dates, durations and dependencies, which suits planning future work.

Other Mermaid diagram types