Mermaid Timeline Syntax: Live Editor & Examples

For the current grammar, see the official Mermaid timeline reference. Host applications can bundle different versions, so verify the exported source in your destination.

Mermaid timeline syntax (quick reference)

A timeline in Mermaid turns plain-text milestones into an interactive chronological roadmap. Mermaid positions dates, groups, and nodes automatically without manual pixel alignment or heavy third-party chart libraries.

Every diagram adheres to strict rules defined by the mermaid timeline syntax. The parser processes your code from top to bottom, organizing periods into horizontal columns and rendering events beneath their parent periods.

Core Keywords and Structure

• timeline: The mandatory declaration keyword that tells Mermaid to render a timeline. It must appear at the top of your diagram code (following any optional frontmatter or %%{init}%% directives).
• title: An optional keyword placed directly below timeline. Any text following title renders as the primary header above the timeline container.
• section: An optional grouping keyword that divides consecutive time periods into distinct phases, eras, or quarters. When sections are defined, Mermaid tints the background track with distinct color bands.
• {period} : {event}: The foundational time unit. The period label sits to the left of the colon delimiter, and the event description sits to the right. Spaces around the colon are automatically trimmed.
• Multiple events per period: Attach several events to one period either by chaining colons on a single line (2026 : Alpha : Beta) or by placing subsequent events on new lines starting with a leading colon (: Next event).
• %% Comments: Any line or token starting with double percentage signs (%%) is treated as a comment and excluded from rendering.
• %%{init: {'theme': 'dark'}}%%: In-diagram initialization directive to customize theme palettes and typography directly in your snippet.

Syntax Cheat-Sheet Table

Syntax Limitations and Edge Cases

Keep these structural constraints in mind when writing mermaid timeline syntax:

• Discrete Ordinal Slots (No Continuous Time Scale): Unlike Gantt charts, timelines do not calculate calendar duration or scale distances proportionally. A span between 1950 and 2000 occupies the exact same column width as a span between 2025 and 2026. For proportional durations or dependency arrows, use a Gantt chart instead.
• Colon Delimiters Inside Event Text: Because colons (:) act as delimiters, placing an unescaped colon inside an event label (e.g. 2026 : Status: Shipped) splits your label into two separate events. Use em-dashes (—), hyphens (-), or parentheses instead.
• Long labels: Wrapping and overflow depend on the Mermaid version and destination renderer. Preview long labels in the intended host and use deliberate line breaks where supported.
• Section Color Cycling: Mermaid cycles through its 12-color categorical palette (cScale0 to cScale11) by default. Setting disableMulticolor: true forces a clean monochrome aesthetic.

Mermaid timeline chart examples

Explore these copy-paste templates to kickstart your diagrams. Each mermaid timeline chart example is verified against Mermaid v11.17 and can be loaded directly into our editor above with a single click.

Choosing the right mermaid timeline chart example saves hours of trial and error when documenting roadmap milestones or engineering history.

timeline
    title Project Genesis
    2023 : Project conceived
    2024 : Architecture finalized
    2025 : Public beta launch
    2026 : Global enterprise rollout

timeline
    title Product Evolution by Era
    section Research Phase
        2021 : Market discovery
        2022 : Proof of concept
    section Build Phase
        2023 : Core engine v1
        2024 : Cloud platform migration
    section Scale Phase
        2025 : Multi-region clustering
        2026 : Autonomous AI agents

timeline
    title 2026 Release Milestones
    January : Security audit : SOC2 certification
    February : API v2 redesign
    March : Open-source SDK : Developer docs portal
    April : Multi-tenant support : Global edge caching

timeline
    title 2026 Product Roadmap
    section Q1 Foundation
        Jan : Auth revamp : Webhook engine
        Feb : Database sharding
        Mar : SOC2 Type II audit
    section Q2 Collaboration
        Apr : Real-time presence
        May : Multiplayer canvas
        Jun : Team workspaces

timeline
    title Zero-to-One Startup Launch
    section Pre-Seed
        Month 1 : Customer interviews : Problem validation
        Month 2 : Wireframes & interactive prototype
        Month 3 : Angel check closed ($250k)
    section Alpha
        Month 4 : Core MVP built
        Month 5 : 50 design partners onboarded
        Month 6 : Iteration on user retention

timeline
    title History of Artificial Intelligence (1950 - 2026)
    section Foundations
        1950 : Turing Test proposed
        1956 : Dartmouth Workshop : AI coined
        1966 : ELIZA chatbot
    section Modern Era
        2017 : Transformer architecture
        2022 : ChatGPT launches
        2026 : Autonomous vibe-coding agents

Mermaid timeline example code you can copy

Below you will find production-ready mermaid timeline example code snippets ready for direct inclusion in GitHub READMEs, Obsidian vaults, or internal Notion engineering wikis.

Copy any mermaid timeline example code block below to paste directly into your documentation or try inside our live tool.

Comprehensive 4-Quarter Engineering Roadmap

This full-year roadmap coordinates infrastructure, collaboration tools, AI capabilities, and enterprise governance across four distinct quarters.

timeline
    title 2026 Full-Stack Platform Roadmap
    section Q1 Infrastructure
        Jan : Auth revamp : Webhook engine
        Feb : Database sharding
        Mar : SOC2 Type II audit
    section Q2 Collaboration
        Apr : Real-time presence
        May : Multiplayer canvas
        Jun : Team workspaces
    section Q3 Intelligence
        Jul : Semantic code search
        Aug : Context window expansion
        Sep : Background agent workers
    section Q4 Enterprise
        Oct : Single sign-on (SAML)
        Nov : Audit log exports
        Dec : Custom SLA tier

History of AI: From Symbolic Logic to Vibe Coding (1950–2026)

A multi-era historical breakdown illustrating how timeline sections create clear visual separation between the Dartmouth workshop, expert systems, deep learning breakthroughs, and modern agentic development.

timeline
    title History of Artificial Intelligence (1950 - 2026)
    section Foundations
        1950 : Turing Test proposed
        1956 : Dartmouth Workshop : AI coined
        1966 : ELIZA chatbot
    section Winters and Rules
        1974 : First AI winter begins
        1980 : Expert systems emerge
        1997 : Deep Blue defeats Kasparov
    section Deep Learning
        2012 : AlexNet wins ImageNet
        2017 : Transformer architecture (Attention Is All You Need)
        2020 : GPT-3 released
    section Agentic Frontier
        2022 : ChatGPT public rollout
        2024 : Frontier reasoning models (o1, R1)
        2026 : Autonomous vibe-coding workflows

Two-Week Agile Sprint Execution Plan

A granular daily breakdown showing how to organize sprint planning, schema definition, code freeze, QA smoke tests, and production releases over a ten-day delivery cycle.

timeline
    title Sprint 42 Execution Plan (2 Weeks)
    section Week 1 Kickoff & Core
        Day 1 : Sprint planning : Story backlog grooming
        Day 2 : API schema definition : Database migration script
        Day 3 : Backend endpoints completed : Unit tests written
        Day 4 : Frontend UI wireframes implemented
        Day 5 : Code freeze for Week 1 : First integration test
    section Week 2 Polish & Release
        Day 6 : QA smoke test : Bug triage
        Day 7 : Performance benchmarking : Query optimization
        Day 8 : Staging deployment : End-to-end regression run
        Day 9 : Security vulnerability scan approved
        Day 10 : Production deploy : Sprint retrospective

How to style a Mermaid timeline

Styling a mermaid timeline is straightforward using %%{init: ...}%% directives or YAML frontmatter configuration. When customizing your diagram, you can switch themes, customize hex color palettes, and toggle color cycling.

Built-In Themes

Mermaid includes five standard themes: default, dark, forest, neutral, and base. To apply a theme directly within your code snippet, declare the directive at line 1:

%%{init: {'theme': 'dark'}}%%
timeline
    title Dark Mode Timeline
    2025 : Alpha release
    2026 : Production launch

Overriding Palette Colors with themeVariables

Timeline diagrams populate their period markers and event boxes from Mermaid's categorical color scale variables (cScale0 through cScale11). By targeting these variables inside themeVariables, you can match your company's exact brand design system:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'cScale0': '#2cba8d',
    'cScaleLabel0': '#ffffff',
    'cScale1': '#12855f',
    'cScaleLabel1': '#ffffff',
    'cScale2': '#f2705c',
    'cScaleLabel2': '#ffffff',
    'timelineFontFamily': 'Inter, sans-serif',
    'fontSize': '15px'
  }
}}%%
timeline
    title Custom Brand Styled Timeline
    2024 : Architecture Design
    2025 : System Migration
    2026 : Global Rollout

Uniform Enterprise Styling with disableMulticolor

If you prefer a clean monochrome aesthetic over rainbow period blocks, set disableMulticolor: true under the timeline configuration object. This forces all timeline nodes to follow your base theme accent rather than alternating colors:

%%{init: {
  'theme': 'neutral',
  'timeline': {
    'disableMulticolor': true
  }
}}%%
timeline
    title Clean Monochrome Timeline
    section Phase 1
        Week 1 : Kickoff
        Week 2 : Technical Spec
    section Phase 2
        Week 3 : Implementation
        Week 4 : Verification

Mermaid timeline vs Gantt chart

Deciding between a Gantt chart and a timeline depends on your project goals and audience.

When to use a Timeline: Choose a timeline when presenting strategic roadmaps, release histories, sprint themes, or product narratives. Timelines shine when you want stakeholders to grasp the sequence of events without getting bogged down in calendar math.

When to use a Gantt Chart: Choose a Gantt chart when you need to calculate exact critical paths, track task dependencies, monitor individual contractor workloads, or model precise day-by-day delivery schedules.

How to make a Mermaid timeline with ChatGPT or Claude

Large language models like Claude 3.7 Sonnet, GPT-4o, and Gemini 2.5 Pro excel at generating diagrams when given clear formatting rules. Knowing the mermaid timeline syntax ensures you can craft effective prompts and fix syntax errors quickly.

You are an expert technical documentation assistant. Generate a clean Mermaid timeline diagram based on the schedule details provided below.

Strict Syntax Rules:
1. Start directly with the "timeline" keyword on line 1.
2. Provide an informative "title [Title Text]".
3. Group major phases using "section [Section Name]".
4. Format events as "[Period Label] : [Event Text]".
5. For multiple events in the same period, chain them with colons or use leading colons on new lines.
6. CRITICAL: Never use colons (:) inside the event text itself. Replace internal colons with hyphens or dashes.
7. Return raw Mermaid code only. Do not wrap in markdown code blocks or triple backticks.

Project Details:
[Paste your project milestones, dates, or quarterly goals here]

Before running your prompt through an LLM, you can check your prompt's token count to optimize context usage, or test our improve your diagram prompt utility. To monitor your brand's AI search footprint across LLM models, visit our AI visibility checker.

Reviewing generated code in a mermaid live editor before committing catches syntax glitches early. If your AI output includes broken fences or unexpected characters, use our mermaid live editor above to inspect and preview the result.

Fixing Common AI Generation Mistakes

• Triple Backtick Code Fences: AI models often wrap output in ```mermaid ... ```. Our editor above automatically removes these fences on paste. In external editors, manually remove the opening and closing backtick lines.
• Colons Inside Event Descriptions: When an AI writes 2026 : Milestone: Beta Release, Mermaid interprets Beta Release as a secondary event. Replace the internal colon with a hyphen (2026 : Milestone - Beta Release).
• Missing Root Keyword: Some models output Gantt or flowchart syntax by mistake. Ensure line 1 begins with the timeline keyword.
• Nested Bracket Syntax: Unlike flowcharts that use [Node Text], timeline events require plain text strings without square brackets.

Where Mermaid timelines render

Mermaid diagrams render natively across major developer platforms and documentation suites. Simply enclose your diagram in a standard Markdown code block tagged with the mermaid language identifier:

```mermaid
timeline
    title My Platform Milestone
    2025 : Alpha
    2026 : Production
```

Working with structured formats or converting documentation files? Bookmark our upcoming developer utilities: [LINK: json formatter] and [LINK: html to markdown]. If you need a versatile diagram sandbox for other chart structures, this tool also functions as a full-featured mermaid editor online. Bookmark this mermaid editor online whenever you need to prototype flowcharts, sequence diagrams, or timelines without installing local CLI packages.

Frequently asked questions