Exploring Mermaid Timeline Diagrams: A Comprehensive Guide
- Overview
1.1 What is a Mermaid Timeline Diagram?
Mermaid is a lightweight, text‑based diagramming tool that allows developers and technical writers to generate charts and graphs from simple plain‑text descriptions. This approach simplifies creation, maintenance, and version tracking of diagrams. Among its supported diagram types, the timeline diagram is designed to display a sequence of events in chronological order, making it ideal for project roadmaps, historical analysis, product lifecycles, and educational materials.
A timeline visually represents the passage of time, typically using dates or relative time periods as markers. The diagram arranges events from left to right (or top to bottom) according to the order they are listed in the source text. While Mermaid’s timeline diagrams are not as visually customizable as dedicated drawing software, they excel in rapid prototyping and integration with version‑controlled documentation.
1.2 A Quick Example
%%{init: {'theme':'default'}}%%
timeline
title My Personal Milestones
section Education
2015: High School
2018: University
section Career
2023: First Job
2024: Freelancing
Explanation of the elements:
%%{init: {'theme':'default'}}%%– sets the diagram theme (here, the default theme).timeline– declares that this is a timeline diagram.title– (optional) adds a main title to the timeline.section …– groups events under a category (e.g., "Education", "Career").2015: High School– defines an event: the time period left of the colon, followed by the event description. Multiple events can be separated by colons or placed on separate lines.
- Detailed Usage
2.1 Defining Events
Events are the core building blocks. The time period can be any textual label (not necessarily numeric). The order of events in the source text determines their left‑to‑right placement on the timeline. The first event for a given period appears at the top of that column; the last event appears at the bottom.
timeline
title Sorting Rule Example
Phase One : First Item Left : Second Item Left
Phase Two : Middle Item
Phase Three : Right Item A : Right Item B : Right Item C
In this example, events under "Phase One" appear leftmost, "Phase Two" in the center, and "Phase Three" rightmost. Within each phase, events stack vertically in the order given.
2.2 Grouping with Sections
The section keyword allows you to logically partition the timeline into stages, age groups, project phases, or any meaningful category. This improves readability and helps viewers quickly grasp the structure of the timeline.
timeline
section Initiation
2023-01-10 : Kick‑off Meeting
2023-02-10 : Requirements Gathering
section Execution
2023-04-15 : Development Starts
2023-04-25 : First Sprint Release
section Closure
2023-05-15 : Testing Phase
2023-07-01 : Production Deployment
2.3 Multi‑line Event Text
When event descriptions are long, you can insert line breaks using the <br> HTML tag inside the event text. This keeps the diagram clean and prevents overflow.
timeline
section Research
2023-01-15 : Collect & analyze requirements<br>including user interviews and market surveys
section Development
2023-04-25 : First iteration release<br>implements core features
section Deployment
2023-07-01 : Final testing && go‑live<br>ensure performance and security
2.4 Customizing Colors
By default, each section receives a distinct color from a predefined palette. To force a uniform color scheme across all sections, use the disableMulticolor option.
%%{init: { 'theme': 'base', 'timeline': {'disableMulticolor': true} } }%%
timeline
title Uniform Color
2023: Employee
2024: Freelancer
2025: Entrepreneur
For full control over the palette, define theme variables cScale0 through cScale11. Each variable sets both background and label colors. The diagram uses up to 12 distinct colors; beyond that, the pattern repeats.
%%{init: { 'theme': 'base', 'themeVariables': {
'cScale0': '#ff0000', 'cScaleLabel0': '#ffffff',
'cScale1': '#00ff00',
'cScale2': '#0000ff', 'cScaleLabel2': '#ffffff'
} } }%%
timeline
title Custom Red / Green / Blue
2023: Employee
2024: Freelancer
2025: Entrepreneur
2.5 Changing the Overall Theme
Mermaid provides several built‑in themes accessible via the theme parameter in the init directive. The supported themes include base, forest, dark, default, and neutral. Each theme changes the background, font, and accent colors.
%%{init: { 'theme': 'forest' } }%%
timeline
title Forest Theme Demo
2002 : LinkedIn
2004 : Facebook : Google
2005 : Youtube
2006 : Twitter
2007 : Tumblr
2008 : Instagram
2010 : Pinterest
Experiment with different themes to find one that best fits your documentation’s visual style.