How to Create Timeline Diagrams with Mermaid.js

What Is a Mermaid Timeline Diagram?

A mermaid timeline diagram lets you visualize events, milestones, and phases in chronological order — using nothing but text. No drag-and-drop tools, no image editing, no external software. Just write the syntax, and Mermaid renders a clean, shareable timeline.

Timeline diagrams are perfect for:

- Product roadmaps and release schedules

- Historical events and project retrospectives

- Onboarding docs showing company or project history

- Sprint planning visuals embedded in your README

In this guide you'll learn the complete Mermaid timeline syntax, see multiple real-world examples, and pick up tips for writing timelines that are easy to maintain.

Basic Mermaid Timeline Syntax

The timeline diagram type was introduced in Mermaid v9.4. The core structure is straightforward:

timeline
    title History of Mermaid.js
    2014 : Knut Sveidqvist releases Mermaid on GitHub
    2016 : First major adoption in developer docs
    2019 : GitHub integration discussions begin
    2022 : GitHub natively renders Mermaid in Markdown
    2023 : Mermaid v10 released with major improvements
    2024 : Over 60,000 GitHub stars

Breaking down the syntax:

• timeline — declares the diagram type
• title — optional chart title displayed at the top
• 2014 : Event text — a time period followed by : and the event label

Multiple events can share the same time period by adding more lines with the same period label.

Adding Multiple Events Per Period

One of the most useful features is grouping multiple events under a single time label:

timeline
    title 2025 Product Roadmap
    Q1 : Launch beta
        : Onboard first 100 users
        : Set up analytics
    Q2 : Public launch
        : Email campaign
    Q3 : Mobile app release
        : Paid tier introduced
    Q4 : Enterprise plan
        : Partner integrations

Each additional : event line (indented, without repeating the period) is added to that period's column. This keeps related events grouped without cluttering the timeline axis.

Sections — Adding Colour-Coded Groups

For longer timelines, you can organise periods into named sections. Each section gets its own colour in the rendered diagram:

timeline
    title Company Growth Timeline
    section Early Stage
        2020 : Company founded
             : Seed funding ($500K)
        2021 : First product shipped
             : 5-person team
    section Growth Stage
        2022 : Series A ($3M)
             : 20-person team
             : First enterprise customer
        2023 : Product line expanded
             : Reached profitability
    section Scale Stage
        2024 : Series B ($15M)
             : 80-person team
        2025 : International expansion
             : IPO preparation

Sections are declared with section Name and apply to all subsequent periods until another section is declared. They're great for separating phases of a project, company lifecycle stages, or sprint cycles.

Real-World Example: Software Release History

Here's a mermaid timeline diagram documenting a product's version history — a common use case for developer docs and README files:

timeline
    title My App — Release History
    section Alpha
        v0.1 : Core authentication
             : Basic CRUD operations
        v0.2 : REST API stabilised
             : Unit tests added
    section Beta
        v0.5 : Public beta launched
             : Dashboard UI
             : Email notifications
        v0.9 : Performance optimisations
             : Bug fixes from beta feedback
    section Production
        v1.0 : General availability
             : Stripe payments integrated
        v1.1 : Team collaboration features
        v2.0 : Real-time sync
             : Mobile app (iOS + Android)

Because the source is plain text, this lives right in your repo. When you ship v2.1, you add two lines — no image exports needed.

Example: Project Sprint Timeline

Timeline diagrams also work well for sprint planning or retrospective documentation:

timeline
    title Q1 Sprint Overview
    section Sprint 1 (Jan)
        Week 1 : Kick-off and backlog grooming
               : Environment setup
        Week 2 : User auth module
        Week 3 : Profile management
        Week 4 : Sprint review and demo
    section Sprint 2 (Feb)
        Week 5 : Dashboard v1
               : API rate limiting
        Week 6 : Notifications service
        Week 7 : Data export feature
        Week 8 : Sprint review
    section Sprint 3 (Mar)
        Week 9  : Mobile-responsive UI
        Week 10 : Performance profiling
        Week 11 : Load testing
        Week 12 : Q1 retrospective

Example: Historical Technology Timeline

Mermaid timeline diagrams aren't just for software projects. They're equally useful for educational content, articles, and documentation that places events in historical context:

timeline
    title Key Moments in Web Development
    section Web 1.0
        1991 : Tim Berners-Lee publishes the first website
        1994 : Netscape Navigator launches
        1995 : JavaScript created by Brendan Eich
             : Java applets introduced
        1996 : CSS 1 specification released
    section Web 2.0
        2004 : Gmail launches, proving rich web apps are possible
        2005 : AJAX popularised by Google Maps
             : YouTube founded
        2006 : jQuery released
        2008 : V8 JavaScript engine by Google
        2009 : Node.js created by Ryan Dahl
    section Modern Web
        2013 : React released by Facebook
        2014 : Vue.js introduced
        2016 : Angular 2 released
        2017 : WebAssembly becomes a W3C recommendation draft
        2020 : Deno 1.0 released
        2022 : Bun JavaScript runtime released

Embedding Timelines in Your Docs

Mermaid timeline diagrams render natively in GitHub Markdown (wrap in a mermaid code fence), Notion (paste using the Mermaid block), Obsidian, Docusaurus, MkDocs, and anywhere Mermaid is supported.

For GitHub specifically:

timeline

title My Project Milestones

2024 : MVP shipped

2025 : 1,000 users

You can also try and iterate on your timeline syntax in the Mermaid Live Editor before committing — it gives instant visual feedback as you type, so you can see how sections and event groupings look before they go into your docs.

Mermaid Timeline vs Gantt Chart

Mermaid offers two diagram types that handle time-based content differently:

If you need to show how long tasks take, use a Gantt chart. If you want to place events and milestones in chronological context, use a timeline diagram.

Tips for Better Timeline Diagrams

Keep event labels short. The timeline renders each event as a chip inside a column. Long text wraps awkwardly. Aim for 3-6 words per event.

Use consistent period granularity. Mixing Q1 2024 with Week 3 in the same diagram looks messy. Pick a granularity (quarters, months, sprints) and stick to it.

Use sections for long timelines. Anything with more than 6-8 periods benefits from section groupings — they add colour contrast and logical separation.

Put the most important events first in a period. Mermaid displays events top-to-bottom within a period column. Lead with the headline event.

Test in the live editor first. Before adding a timeline to your repo's README or docs, paste it into mermaideditor.lol to see how it renders. Easier to tweak there than after pushing a commit.

Troubleshooting Common Issues

Timeline not rendering? Check that you're on Mermaid v9.4+. GitHub, Notion, and most modern integrations are already there, but self-hosted tools may lag behind.

Events appearing in wrong order? Mermaid renders periods in the order they appear in the source — there's no automatic date sorting. Write them top-to-bottom in chronological order.

Text overflowing? Shorten event labels or split into multiple sections.

Section colours look off in dark mode? Mermaid's built-in themes handle dark mode differently. Use the dark or default theme directive at the top of your diagram if needed.

Conclusion

Mermaid timeline diagrams are a quick, maintainable way to visualise chronological information in your documentation. The syntax is minimal, the output is clean, and because diagrams live as text in your repo, they stay up-to-date as your project evolves.

Start with a simple 4-5 period timeline, add sections when it grows, and you'll have professional-looking roadmap and history diagrams without ever opening a design tool.

Try building your timeline diagram for free at mermaideditor.lol →