How to Use Mermaid Timeline Diagrams: Complete Instructions Guide (2026)

# How to Use Mermaid Timeline Diagrams: Complete Instructions Guide (2026)

Mermaid timelines are one of the most underused features in the library. Everyone knows flowcharts and sequence diagrams — but timelines? They're clean, readable, and perfect for project overviews, research plans, and historical summaries.

This guide covers everything: the full syntax, sections, multi-line events, and real working examples you can copy and run immediately.

What Is a Mermaid Timeline?

A Mermaid timeline (timeline diagram type) lets you map events to time periods using plain text. You define time sections, then list events under each one. Mermaid renders it as a horizontal or vertical visual timeline.

It's different from a Gantt chart. Gantt tracks duration and dependencies. A timeline is simpler — it's a chronological story.

When to use it:

- Project milestone overviews

- Product roadmaps

- Research planning (phases of a study)

- Historical event summaries

- Onboarding sequences

Basic Syntax — Your First Timeline

Here's the minimal structure:

timeline
    title My Project Timeline
    section Phase 1
        Kick-off meeting : 2026-01-01
        Requirements done : 2026-01-15
    section Phase 2
        Design complete : 2026-02-01
        Dev complete : 2026-03-01

What this does: Creates a timeline with two sections (Phase 1 and Phase 2), each with two events. The colon separates the event label from the date.

Key rules:

- timeline keyword starts the diagram

- title is optional but recommended

- section groups related events

- Each event: Event label : date-or-period

Understanding Sections

Sections are the backbone of Mermaid timelines. They create visual groupings that help readers scan the timeline at a glance.

timeline
    title Software Release History
    section 2024
        v1.0 Launch : Jan 2024
        v1.1 Bug fixes : Mar 2024
        v1.2 New features : Jun 2024
    section 2025
        v2.0 Major rewrite : Jan 2025
        v2.1 Performance : Apr 2025
    section 2026
        v3.0 AI features : Feb 2026
        v3.1 Mobile app : May 2026

What this does: Maps a software product's release history across three years. Each section represents a year, and events inside show individual releases.

Sections don't have to be time-based. You can use phases, themes, or any logical grouping.

Events Without Sections

You can skip sections entirely for simple timelines:

timeline
    title Key Dates for Product Launch
    Idea validated : Week 1
    MVP built : Week 3
    Beta testers recruited : Week 5
    Public launch : Week 8
    First 100 users : Week 10

What this does: Shows a linear sequence of 5 milestones without any grouping. Best for short timelines where you don't need categories.

This is the simplest form — just a title and events. Good for roadmaps where phases aren't needed.

Multi-Event Entries

One of the most useful features: multiple events can share the same time period. This is great for showing parallel tasks.

timeline
    title Q1 2026 Sprint Plan
    section January
        Backend API design
        Database schema finalized
        Team onboarding : Jan 2026
    section February
        Frontend development
        API integration
        Unit testing : Feb 2026
    section March
        QA testing
        Performance optimization
        Staging deployment : Mar 2026

What this does: Shows parallel workstreams in each month. Multiple items are listed under the same section, making it clear that these tasks happen simultaneously.

Notice that only the last item in each section gets the : date — the others are just labels. This is valid syntax and renders cleanly.

Styling Your Timeline

You can add themes and customize via Mermaid's %%{init: ...}%% directive:

%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
timeline
    title Team Milestones — Forest Theme
    section Founding
        Company incorporated : 2020
        First hire : 2020
    section Growth
        Series A raised : 2022
        50 employees : 2023
    section Scale
        International expansion : 2025
        IPO filed : 2026

What this does: Applies the "forest" color theme to the timeline. Available themes: default, forest, dark, neutral, base. The logLevel: debug helps during development when you need to troubleshoot rendering issues.

Common Mistakes (and How to Fix Them)

Mistake 1: Forgetting the timeline keyword

Every diagram needs the type declaration first. timeline must be the first non-comment line.

Mistake 2: Missing colons

Event syntax requires : period. Without the colon, Mermaid treats the line as a continuation, not a new event.

Mistake 3: Inconsistent indentation

Mermaid uses indentation to understand structure. Keep sections and events consistently indented (2 or 4 spaces — pick one).

Mistake 4: Overly long event labels

Long labels overflow on narrow screens. Keep event text under 40 characters for clean rendering.

Full Example: Product Launch Timeline

Here's a complete, real-world example combining all the concepts:

timeline
    title SaaS Product Launch — 2026 Roadmap
    section Discovery (Jan)
        Customer interviews done
        Problem validated
        Competitors analyzed : January
    section Build (Feb-Mar)
        MVP development
        Internal alpha testing
        Bug fixes complete : Feb-Mar
    section Launch (Apr)
        Beta program opens
        Press release published
        Product Hunt launch : April
    section Growth (May+)
        Paid ads start
        Content marketing live
        First 500 customers : May onwards

What this does: A complete SaaS product launch plan, from discovery to growth, mapped across 4 months. This is production-ready — you could put this in a project README today.

Tips for Better Timelines

Keep it scannable. Timelines work best when you can read them in 30 seconds. If you're adding more than 6-8 events per section, consider splitting into multiple diagrams.

Use consistent date formats. Mixing "Jan 2026", "2026-01-01", and "Q1 2026" in the same timeline looks messy. Pick one format and stick to it.

Pair with a Gantt when needed. If you need to show duration or dependencies between tasks, a Mermaid Gantt chart is a better fit. Timelines show *when*, Gantts show *how long*.

Embed in docs. Mermaid works natively in GitHub Markdown, Notion, GitLab, and most modern wikis. Write your timeline in plain text and it renders automatically.

Want to See More Timeline Examples?

Check out our post on 10 Mermaid Timeline Examples with Step-by-Step Code for real use cases including research plans, sprint schedules, and historical timelines.

For the full syntax reference, visit the Mermaid Timeline Syntax guide.

---

Try this live in our free Mermaid Editor → mermaideditor.lol

Paste any of the code blocks above and see your timeline render instantly. No sign-up, no install. Just paste and go.

---

*Related: Mermaid Cheat Sheet · Diagram Templates · Home*