What a Mermaid timeline is for
A timeline lists events in order under time periods, which makes it good for product histories, roadmaps and release notes overviews.
Timeline syntax
| Syntax | Meaning |
|---|---|
timeline |
Start a timeline |
title Text |
Title |
2026 : Event |
A period and its event |
2026 : Event A : Event B |
Several events in one period |
: Event C |
Continue the previous period on the next line |
section Name |
Group periods; each section gets its own color |
Basic example
timeline
title Product history
2023 : Prototype : First 10 users
2024 : Public beta : Mobile app
2025 : Version 1.0 : Team plans
2026 : API platformOpen this example in the Mermaid editor
More timeline examples
Roadmap with sections
Sections color related periods together.
timeline
title 2026 roadmap
section H1
Q1 : SSO login : Audit log
Q2 : Usage-based billing
section H2
Q3 : EU data residency
: Public API v2
Q4 : Mobile offline modeOpen “Roadmap with sections” in the editor
Common mistakes
- Periods are text, not dates, so “Q1” or “Sprint 3” work as well as years.
- Colons separate events; leave them out of event text.
Use it in Markdown
```mermaid
timeline
title Product history
2023 : Prototype : First 10 users
2024 : Public beta : Mobile app
2025 : Version 1.0 : Team plans
2026 : API platform
```GitHub, GitLab, Azure DevOps, Obsidian, Notion and docs generators such as Docusaurus and MkDocs (with a plugin) draw fenced mermaid blocks. Check it locally in the Markdown preview.
Other Mermaid diagrams
- Mermaid flowchart syntax
- Mermaid sequence diagram syntax
- Mermaid class diagram syntax
- Mermaid state diagram syntax
- Mermaid er diagram syntax
- Mermaid gantt chart syntax
- Mermaid pie chart syntax
- Mermaid mindmap syntax
- Mermaid git graph syntax
- Mermaid user journey syntax
- Mermaid quadrant chart syntax
- Mermaid xy chart syntax
Sources
Spotted a mistake? Email hello@devtoolsmith.com and we’ll fix it.
Frequently asked questions
How do I start a Mermaid timeline?
Begin the diagram with the keyword timeline on its own line, then add one statement per line. In Markdown, wrap the whole diagram in a fenced code block with the language mermaid so GitHub, GitLab and most docs sites draw it.
How do I export a Mermaid timeline as an image?
Paste the diagram into the editor on this page and use SVG or PNG above the preview. SVG stays sharp at any size and can be edited further; PNG is exported at twice the screen resolution for slides and documents. Nothing is uploaded.