Skip to content
MermaidViewer

Planning diagram

Mermaid timeline diagram

Mermaid timeline diagram syntax for sections and events, with a roadmap example you can edit in the browser.

By MermaidViewer editorsPublished Updated

Basic timeline example

Basic timeline example diagram
mermaid
timeline
    title Product history
    section Early days
      2021 : Idea and prototype
      2022 : First 100 users : Seed round
    section Growth
      2023 : Mobile apps launched
      2024 : AI features : 1M diagrams created
    section Today
      2025 : Teams plan
      2026 : Public API
Open in the live editor

Mermaid timelines list events in chronological order. Each line is a time period followed by one or more events, which makes them perfect for company histories, product changelogs and roadmaps that don't need exact dates.

Unlike Gantt charts, timelines don't need durations or date formats. You write the periods as plain text — years, quarters or phases — and Mermaid lays them out evenly.

When to use a timeline

  • Company and product history
  • Release changelogs
  • Quarterly roadmaps
  • History lessons and biographies

Timeline syntax reference

SyntaxWhat it does
timelineStart a timeline.
title TextTimeline title.
Period : EventA period with one event.
Period : Event 1 : Event 2Several events in one period.
section NameGroup periods into colored sections.

Timeline examples

Quarterly roadmap

Periods can be any text, such as quarters.

Quarterly roadmap diagram
mermaid
timeline
    title 2026 Roadmap
    Q1 : SSO : Audit log
    Q2 : Public API
    Q3 : Mobile editor : Offline mode
    Q4 : Enterprise plan
Open in the live editor

Periods and events, with no bar lengths, are the deal. A mermaid timeline diagram is how you show that v1 shipped, then v2 broke a contract, then v3 calmed the clients down. It won't tell you that v2 took six weeks. If you need the six weeks, you need a Gantt chart. The syntax table is short on purpose. The colon does almost all the work.

Sections, periods, and extra colons

timeline opens the diagram. title is the chart heading. section groups periods into a colored band, which is how you separate years or eras without pretending you have a scale.

A period line looks like v1 : public launch. The text before the colon is the period. The text after it's one event. Another colon adds another event in that same period: v1 : public launch : first patches. You can also continue with a line that starts with a colon if the first line gets long. Keep events as short labels. A timeline cell is narrow.

The periods aren't sorted for you as dates. They appear in the order you write them. 2024 then 2025 works because you wrote them that way. If you insert 2023 at the bottom, it'll sit at the end. There's no date parser hiding in this diagram.

Sections don't create time. They create groups. Two events in one section aren't "closer" in a measured way. They share a color. Use that for eras, and keep the period labels for the actual sequence.

Worked example

An API's public story fits in three years. The first year has two events. The later years have one each.

Mermaid diagram
mermaid
timeline
    title API history
    section 2024
      v1 : public launch : first patches
    section 2025
      v2 : breaking change
    section 2026
      v3 : stable clients
Open in the live editor

v1 is the period, and it holds both the launch and the patches. Putting them on one line says they belong to the same chapter. If the patches were a year later, they need their own period. v2 : breaking change is honest and short. A reader who needs the migration guide gets a link under the diagram, not a paragraph inside the cell.

The sections are years, which match the story. You could instead section by "Launch", "Break", and "Calm" and use quarters as the periods. Pick one axis. A timeline that sections by team and periods by year and events by version is three axes in a chart that has one line of time.

Order in the file is order on the page. If v3 is still a plan, label the event "planned" or keep it out. A timeline looks like history. Future items need a word that says they have not happened.

When this is the wrong diagram

A Gantt chart is the better picture when an event has a start date and a duration, or when one task waits on another. A git graph is the better picture when the history is branches and merges. Use a timeline when the reader wants the sequence of named moments and won't ask "how long."

Common mistakes

  1. Putting the event before the colon. public launch : v1 makes "public launch" the period and "v1" the event, which swaps the heading and the detail.
  2. A colon inside the event text, such as v2 : breaking change: auth. The second colon starts another event. Rephrase the label so the colon stays the separator.
  3. Writing dateFormat, 5d, or after in this diagram. Those belong to a Gantt chart. A timeline period is plain text.
  4. Adding a late period at the bottom and expecting chronological sort. The bottom of the file is the end of the chart.

Where to go next

The AI timeline generator will split a paragraph into periods. Read the colons in the editor before you publish, and the cheat sheet has the section form. The company history template shows the same idea across a longer span.

Keep one event per line

A timeline event is a date and a fact, not a paragraph. If the line needs a comma-separated essay, the fact is two events or it belongs in the prose under the figure. Sections are chapters (year, quarter, phase), and events inside a section stay in the order they happened. Reordering for drama makes the chart a story you cannot check.

When two events share a date, put both on that date instead of inventing a second day to separate them. The timeline syntax page is this page. The AI timeline generator can draft the sections from a list of dates you paste.

Tips and best practices

  • Use sections to color-code eras or phases.
  • Put multiple events on separate lines starting with a colon to keep long periods readable.
  • Use a Gantt chart instead when you need real dates and durations.

Generate a timeline with AI

Not sure where to start? Describe what you need and the AI timeline generator writes the Mermaid code for you. Try prompts like:

  • “History of the internet”
  • “Startup fundraising journey”
  • “Evolution of JavaScript frameworks”

Timeline templates

Timeline FAQ

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

A timeline shows events per period with no durations, while a Gantt chart uses real dates, durations and dependencies. Use timelines for history and high-level roadmaps, Gantt charts for schedules.

Can a period have multiple events?

Yes. Separate events with colons on one line, or continue on new lines that start with a colon under the same period.