Mermaid Timeline Diagrams for Project History and Roadmaps

Timeline Diagrams in Mermaid

Timeline diagrams display events along a chronological axis. They are ideal for project history, product evolution, technology roadmaps, and historical documentation. Mermaid's timeline syntax groups events by time period.

Basic Syntax

timeline
    title Project History
    2022 : Project kickoff
         : Team formation
    2023 : v1.0 release
         : First 1000 users
    2024 : v2.0 release
         : Series A funding

Each time period (like 2022) is followed by events marked with :. Multiple events can belong to the same period by adding more : lines.

Using Sections

Sections add a second level of grouping:

timeline
    title Technology Evolution
    section Frontend
        2020 : jQuery dominant
        2021 : React takes over
        2022 : Next.js rises
        2023 : Server components
    section Backend
        2020 : Express.js standard
        2021 : Fastify gains traction
        2022 : Edge functions emerge
        2023 : Bun runtime released

Detailed Time Periods

You can use any text as a time period — it doesn't have to be a year:

timeline
    title Sprint 23 Progress
    Week 1 : Design review complete
           : API spec finalized
    Week 2 : Backend endpoints built
           : Database migration run
    Week 3 : Frontend integration
           : Unit tests written
    Week 4 : QA testing
           : Bug fixes
           : Release to staging

A Product Roadmap Example

timeline
    title DevToolbox Roadmap
    section Phase 1 - Foundation
        Q1 2024 : Core tools (JSON, Base64, JWT)
                : Design system
                : SEO framework
    section Phase 2 - Expansion
        Q2 2024 : 20 additional tools
                : Programmatic SEO pages
                : Internationalization
    section Phase 3 - Growth
        Q3 2024 : Community contributions
                : API access
                : Premium features
    section Phase 4 - Scale
        Q4 2024 : 100+ tools milestone
                : Mobile app
                : Enterprise tier

Tips

1. Keep events concise — use short phrases, not full sentences.
2. Group logically — use sections for different teams, products, or themes.
3. Limit events per period — 2-4 events per time period is ideal for readability.
4. Pair with Gantt charts — use timelines for high-level overviews and Gantt charts for detailed schedules.

Timeline diagrams were introduced in Mermaid v10 and are one of the newer diagram types. They render as a horizontal flow from left to right.