Mermaid timeline diagrams for project roadmaps and milestones

A timeline diagram is a simple tool that's somehow easy to get wrong. Too much detail and it becomes unreadable; too little and it doesn't answer the question. Mermaid timeline diagrams strike the balance: they show when things happen and what order they occur in, without requiring every date to be pixel-perfect or every event to fit a predefined template.

Timelines work for product roadmaps, release schedules, historical narratives, and any story where the sequence and approximate timing matter more than the exact hour.

When to use a timeline

Use a timeline when:

• You're communicating a product roadmap to stakeholders (Q1: foundations, Q2: scaling, Q3: analytics)
• You want to show key milestones in a project that spans weeks or months
• You're documenting a historical narrative — how a system or process evolved over time
• You need to align teams around a phased rollout or staged migration
• You're planning a release schedule and want to show feature clusters by phase

A timeline won't work if you need:

• Day-by-day granularity (use a Gantt chart instead)
• Parallel tracks or dependencies between workstreams (Gantt again)
• The exact duration of each phase (Gantt handles this; timeline doesn't)

Timeline syntax

A Mermaid timeline starts with the timeline keyword. Each section is a phase or period, and lines under it are events:

timeline
    title Product Roadmap 2026
    section Q1: Foundation
        Jan: API design review
        Jan: Database schema finalized
        Feb: Core endpoints implemented
        Mar: Auth service live
    section Q2: Scaling
        Apr: Load testing
        May: Cache layer added
        Jun: Multi-region deployment
    section Q3: Analytics
        Jul: Event capture system
        Aug: Dashboard prototypes
        Sep: Analytics API released

Each event gets a month prefix (or any time unit) that groups them visually. Mermaid arranges sections horizontally and events vertically within each section.

A practical example: SaaS feature rollout

Here's a timeline showing how a new billing feature rolls out to customers:

timeline
    title Usage-Based Billing Rollout
    section Development
        Jan: Spec and design
        Feb: Database migration
        Mar: API implementation
    section Alpha Testing
        Apr: Internal testing
        Apr: Early customer preview
    section Beta
        May: Beta customer cohort (50%)
        Jun: Monitor & fix issues
    section General Availability
        Jul: Full rollout
        Aug: Monitoring & support

This tells a story without requiring specific dates. A reader sees the phases, can estimate when each happens, and understands the logical progression.

Building timelines from real dates

If you have actual dates, you can still use a timeline — just convert them to month labels or quarters:

Before: A spreadsheet of launch dates

Feature A: 2026-04-15
Feature B: 2026-05-10
Feature C: 2026-06-01

After: A Mermaid timeline

timeline
    title Q2 Release Schedule
    section May
        2026-05-01: Design reviews complete
        2026-05-10: Feature B ships
    section June
        2026-06-01: Feature C ships
        2026-06-15: Bug fixes & polish

Use consistent section labels (months, quarters, phases) so the visual order matches the chronological order.

Timeline vs. Gantt chart

Both show sequences of events, but they're meant for different questions.

Aspect	Timeline	Gantt
Best for	Roadmaps, narratives, phases	Task scheduling, dependencies, resource allocation
Granularity	Weeks or months	Days or hours
Shows duration?	Roughly, by position	Exactly, by bar length
Shows dependencies?	No	Yes, with arrows
Best audience	Non-technical stakeholders	Project managers, engineers
Complexity	Low (quick to scan)	Higher (more info to parse)

Use a timeline to tell a story and align teams. Use a Gantt when you need to track task duration and dependencies.

Tips for effective timelines

Group logically, not just chronologically. Use sections to separate concerns: one for infrastructure, one for features, one for testing. This helps readers understand why events cluster when they do.

timeline
    title Website Migration
    section Preparation
        Week 1: Audit old platform
        Week 1: Plan content mapping
    section Build
        Week 2-3: Content migration
        Week 3-4: New site development
    section Validation
        Week 4: QA and testing
        Week 5: User acceptance testing
    section Launch
        Week 5: Cutover
        Week 6: Monitoring

Be consistent with time units. If one section uses months and another uses weeks, the diagram becomes confusing. Pick a granularity that fits the entire timeline and stick to it.

Limit the number of events per section. If a section has more than 5–7 events, consider breaking it into subsections or splitting the timeline into multiple diagrams.

Add a title and context in prose. The diagram shows the skeleton; explain the story around it. "We're shipping this in three phases to reduce risk and gather feedback between releases."

Building and sharing timelines

Draft your timeline in the MermaidCreator editor. Paste the Mermaid syntax, adjust the events and sections, then copy the code into your repo, wiki, or docs site.

Timelines render natively on GitHub and GitLab, so you can embed them directly in README files, wiki pages, and PR descriptions. No image exports needed — the diagram lives alongside the code and updates with it.

Real-world examples

Product launch phases:

timeline
    title New Search Experience Launch
    section Alpha (Internal)
        Mar: Design finalized
        Apr: MVP implementation
    section Beta (Customers)
        May: Early access signup
        May: Gather feedback
    section GA (Everyone)
        Jun: Global rollout
        Jul: Monitor & optimize

Infrastructure modernization:

timeline
    title Kubernetes Migration
    section Planning
        Jan: Audit services
        Feb: Design cluster layout
    section Pilot
        Mar: Deploy test cluster
        Apr: Run workloads in parallel
    section Rollout
        May: Migrate 25% of traffic
        Jun: Migrate remaining traffic
    section Cleanup
        Jul: Decommission old infrastructure

Release timeline for a developer tool:

timeline
    title V2 Release Timeline
    section Foundation
        Q1: Core API redesign
        Q1: New plugin system
    section Expansion
        Q2: Official plugins launch
        Q2: IDE integrations
    section Polish
        Q3: Performance tuning
        Q3: Docs & examples
    section Launch
        Q4: RC / beta phase
        Q4: General availability

FAQ

Q: Can I use exact dates in a timeline? A: Yes — you can use any text as the prefix (dates, months, quarters, phase names). The visual order follows the section order in the file, not the dates themselves, so arrange sections chronologically.

Q: How do I show that Event A must finish before Event B starts? A: Timelines don't support dependencies. If order matters because of constraints, use a Gantt chart instead.

Q: Can I add colors or highlight certain events? A: Not in the core Mermaid syntax yet. Use consistent event naming to group related items (e.g., all "Testing" events, all "Launch" events) so readers see the pattern.

Try sketching a timeline for your current project in the MermaidCreator editor — you'll find it's the fastest way to align a team around a schedule.