Mermaid Timeline Diagram Tutorial: Build Chronological Diagrams from Text
The Mermaid timeline diagram turns a list of dates and events into a clean chronological visual. This guide covers the exact syntax, the grouping tricks, and where it fits.
A timeline is one of those diagrams that everyone understands instantly and almost nobody enjoys drawing by hand - the moment you add a new event in the middle, every box after it has to shift. Mermaid's timeline diagram removes that pain entirely: you write the periods and their events as indented text, and the renderer handles the spacing, the alternating placement, and the section coloring for you. Because it is text, inserting an event between two others is a one-line edit rather than a re-layout.
This guide walks through the timeline syntax from the first keyword to the finished chart, with real examples you can paste into the Mermaid editor at /diagram-tools/mermaid-editor to see rendered immediately. Everything runs inside Atlas Diagram Studio at /diagrams, where a Mermaid timeline becomes an editable, styleable diagram rather than a flat picture, and where the AI diagram generator at /diagram-tools/ai-diagram-generator can draft one for you from a plain description of the history you want to show.
The basic timeline syntax
Every timeline begins with the keyword "timeline" on its own line, optionally followed by a "title" line. After that, each time period is a line ending in a colon, and each event under it is written after the colon. The simplest form pairs one period with one event: a line like "2021 : Company founded" places a single event under the label 2021. Mermaid reads the text left of the colon as the time period and the text right of it as the event, then lays the periods out horizontally in the order you wrote them.
A time period is not restricted to a year - it can be any label, such as a quarter, a decade, an age, or a phase name like "Discovery." This flexibility is what makes the timeline useful beyond calendar history: product roadmaps, project phases, and personal biographies all fit the same structure. The renderer never tries to interpret the label as a real date, so you are free to use whatever chronological unit your story needs.
Multiple events and grouping into sections
Real timelines rarely have one event per period, and Mermaid handles multiples cleanly. You can attach several events to the same period either by separating them with additional colons on one line or by adding indented lines beneath the period. Sections group a run of periods under a colored band with a heading, using the "section" keyword, which is what turns a flat list into a diagram that communicates eras or phases at a glance.
The bullets below capture the constructs you will reach for most often. Combine them freely - a section can contain many periods, and each period can carry many events, so a decade of company history compresses into a compact, readable block.
- Start the diagram with "timeline" and optionally a "title My Roadmap" line directly beneath it.
- Write a single event as "period : event", for example "2020 : Seed round".
- Add multiple events on one line by chaining colons: "2020 : Seed round : First hire : Beta launch".
- Or list events on their own indented lines under the period for readability when they are long.
- Group periods with "section Growth Phase", and every period until the next "section" falls under it.
- Each section gets its own color automatically, so eras read as distinct bands without any manual styling.
- Order matters - periods and sections render left to right in exactly the order you write them.
Styling, wrapping, and readability
Long event text wraps automatically, but you control how much fits by keeping each event concise - a timeline is a summary, not a paragraph store. When an event genuinely needs more words, Mermaid wraps it within the event box, and sections keep the layout balanced by distributing periods evenly. If you want to influence colors beyond the automatic section palette, Mermaid's theming applies, and inside Atlas Diagram Studio you can restyle the rendered result directly without touching the source.
A practical readability tip is to lead each event with the most important word, because timelines are scanned, not read. "Launched" or "Acquired" at the start of an event lands faster than a full sentence. Keep periods evenly spaced conceptually too - if one period has ten events and the next has one, consider splitting the crowded period so the visual weight stays balanced across the timeline.
When to reach for a timeline
The timeline is the right tool whenever the story is fundamentally "things happened in this order over time" and the exact durations do not need to be to scale. Company histories, product roadmaps, project retrospectives, personal résumé visuals, and the phases of a research program all fit naturally. If you need proportional time - where the gap between events should reflect real elapsed duration - a Gantt chart is the better Mermaid diagram, since the timeline spaces periods evenly regardless of the real interval.
Because the source is plain text, a timeline is easy to keep current: as a roadmap evolves, you edit a line instead of redrawing. Draft one quickly by describing your history to the AI diagram generator at /diagram-tools/ai-diagram-generator, then refine the wording in the Mermaid editor at /diagram-tools/mermaid-editor. For the broader language, the Mermaid guide at /guides/mermaid-js-complete-guide covers how timelines sit alongside the dozen other diagram types you can write the same way.