Mermaid Timeline Diagrams: Syntax, Examples & Live Editor

What Are Timeline Diagrams?

Timeline diagrams are a diagram type introduced in Mermaid 9.4 for displaying chronological sequences of events grouped into named sections. Unlike Gantt charts, which model tasks with durations and dependencies, timeline diagrams focus on discrete events in time — the kind of information you would put on a wall-mounted project board or a company history page. The syntax is intentionally simple: you name a section, then list events with a label and an optional description.

The result is a horizontally scrolling, visually distinctive diagram that communicates a story through time. Timelines are particularly effective in engineering contexts where you need to explain how a product evolved, document the sequence of events during an incident, or show a sprint's key milestones to stakeholders. If you are trying to decide between a timeline and a Gantt chart, use a Gantt when duration and parallelism matter, and use a timeline when you care primarily about the chronological narrative.

Every playground widget below is fully editable. Change the section names, add or remove events, and watch the diagram update in real time. When you have a diagram you are happy with, click Open in editor to load it into our full Mermaid Diagram Renderer, where you can switch themes and export to SVG or PNG.

Basic Syntax

Every timeline diagram starts with the timeline keyword. The optional title keyword adds a heading above the diagram. Sections divide the timeline into named groups, and each event under a section has a label (before the colon) and an optional description (after the colon). Both the label and description are plain text — no special markup is required.

timeline
    title My Timeline
    section First Section
      Event Label : Optional description text
      Another Event : Another description
    section Second Section
      Third Event : Events can span multiple sections

Indentation is not strictly required but strongly recommended for readability. The colon separator between label and description is optional — if you omit it, the entire text becomes the event label. Sections create visual groupings with a distinct background color; events within a section are displayed as cards beneath the section header.

The playground below shows a minimal but complete example. Try editing the section names or adding new events to get a feel for the syntax before moving on to the real-world examples.

Real-World Examples

The examples below cover six common engineering and product use cases. Each widget is independently editable — the changes you make in one do not affect the others. Use these as starting points for your own documentation.

Product Release Timeline

A product release timeline is one of the most common uses for this diagram type. It shows the version history of a product, grouped by year or quarter, with brief notes on what changed in each release. This kind of diagram works well in a product changelog, a README, or a pitch deck showing how the product has matured over time.

The key design decision is choosing the right granularity for sections. Grouping by year keeps the diagram manageable for products with frequent releases, while grouping by quarter or sprint works better for newer products with fewer data points.

Incident Response Timeline

After a production incident, the timeline of events is critical for writing an accurate postmortem. A Mermaid timeline diagram makes this narrative scannable and easy to share across tools like Confluence, Notion, or GitHub. Sections map naturally to incident phases — detection, triage, resolution, and follow-up — while individual events capture the specific actions taken and their timestamps.

This format also has a psychological benefit: documenting the response in a structured diagram can help separate the facts of what happened from the emotional experience of working through a stressful incident, making for more objective postmortems.

Company History

Investors, new employees, and press contacts all want to understand a company's story. A company history timeline provides this at a glance. Sections can represent eras or phases of growth, while events capture funding rounds, product launches, acquisitions, and other milestones. This diagram type is particularly effective because it requires no legend or explanation — the structure itself communicates the progression from founding to scale.

For engineering teams, this pattern also applies to service histories: when was the service created, when was it migrated to a new platform, when was a major feature shipped?

Sprint Retrospective

Agile teams often struggle to remember exactly what happened in a sprint by the time the retrospective arrives. A sprint timeline created incrementally during the sprint — with team members adding events as they complete work — produces a natural retrospective artifact. Sections map to weeks, and events capture completed tasks, notable discoveries, and decisions made along the way.

This approach is more honest than a summary document written after the fact, because the events are recorded when they happen. The resulting diagram becomes an accurate record of the sprint that the team can use to identify patterns across multiple retrospectives.

Technology Evolution

Explaining the history of a technology ecosystem is a common task for technical writers, educators, and conference speakers. A timeline diagram communicates this history far more efficiently than a wall of text. Grouping by era allows you to show how the landscape shifted over time, which makes it easy to explain why the current state of the ecosystem looks the way it does.

This pattern is also useful internally for documenting the evolution of your own technology stack — showing when services were introduced, deprecated, or replaced — which gives new engineers important context about architectural decisions.

Employee Onboarding

Onboarding documentation is some of the most important writing an engineering team produces, and also some of the most frequently neglected. A timeline diagram can make an onboarding plan immediately clear to a new hire: here is what you will do on day one, here is what the first week looks like, and here is what we expect from you by the end of month three. Sections map to time periods, and events capture the specific activities and milestones within each period.

Unlike a checklist, the timeline format shows progression and time-boxing explicitly. New engineers can see at a glance how the expectations ramp up, which reduces anxiety and sets clear expectations for both the new hire and their manager.

Using Timelines in Markdown

Mermaid timeline diagrams are embedded in Markdown the same way as any other Mermaid diagram — using a fenced code block with the mermaid language identifier:

```mermaid
timeline
    title My Timeline
    section Phase 1
      Event : Description
```

Platform support for the timeline diagram type (introduced in Mermaid 9.4) is slightly less universal than for classic diagram types like flowcharts and sequence diagrams, since platforms need to bundle a recent enough version of Mermaid. As of 2026, GitHub renders timeline diagrams natively in Markdown files, wiki pages, and issue comments. Obsidian supports timelines via its built-in Mermaid renderer. Docusaurus 3.x includes Mermaid 10+ through the @docusaurus/theme-mermaid plugin, so timelines render out of the box with the correct configuration.

GitLab and Notion support Mermaid but may be running older versions depending on when they last updated their bundled Mermaid library. If a timeline fails to render in a specific platform, check which Mermaid version that platform uses. As a fallback, you can always use our Mermaid Diagram Renderer to export the diagram as an SVG image and embed the image directly. For a detailed breakdown of platform support across all diagram types, see our guide on using Mermaid in Markdown.

Styling and Customization

Mermaid timeline diagrams pick up their colors from the active theme. The four built-in themes — default, dark, forest, and neutral — each assign a distinct palette to section backgrounds and event cards. You can select a theme using the %%{init: {theme: 'dark'}}%% directive at the top of your diagram:

%%{init: {theme: 'dark'}}%%
timeline
    title Dark Theme Example
    section Phase 1
      Event A : Description
    section Phase 2
      Event B : Description

Section grouping is the most powerful tool for controlling the visual density of a timeline diagram. If your diagram has many events spread across a long period, grouping them into sections creates visual breathing room and makes the diagram easier to scan. Conversely, a single-section timeline produces a flatter, more compact layout that works well for short sequences.

Mermaid's timeline diagram does not currently support per-event or per-section color overrides through inline styling — colors are determined by the theme. For full visual control, the cScale theme variable allows you to customize the color palette used for sections. You can configure this through the init directive's themeVariables key, though this is an advanced use case best explored in the full editor where you can see the result immediately.