Earlier this week I wrote about using Mermaid.js to create Gantt charts that help you visualize tasks or major phases in a larger project. This can be great for detailed task analysis, but sometimes you just want to look at a high-level view of what's going on in a time period. Mermaid.js gives us Timeline Charts to help with that.
Timeline charts allow you to generate visuals like the following timeline showing the releases of .NET over the years:
In this article I'll walk you through the process of building this chart, step by step.
One note before I get into this article, however: at the time of this writing, Timeline charts are one of the newer features of Mermaid.js. That means that many tools won't yet be on a version of Mermaid.js that supports timelines.
For now, I recommend you use the Mermaid.js live editor to generate these charts until various tools update to be on Mermaid.js version 10.0.0 or later.
Defining Time Ranges
First, let's start by defining the major sections of time that exist in our timeline.
We can do this by adding a timeline root node that tells Mermaid.js to create a timeline chart and then adding a new line for every range of time that we want to exist as a column.
The timeline of dotnet is fairly involved and so I'm choosing to represent several ranges of time together in certain columns using the following markdown:
timeline
2000 - 2005
2006 - 2009
2010 - 2015
2016 - 2017
2018 - 2019
2020
2021
2022
This generates a simple timeline with the time periods I defined:
It's important to note that Mermaid.js doesn't see these values as years or time ranges or anything else. These are just text categories that we can use to describe each column.
Adding Timeline Entries
Next, let's add the raw entries to our timeline chart.
If you only have one entry in a timeline column, you can add it on a single line, such as:
2021 : .NET 6
Subsequent entries should be separated by a : so you could define several items on a single line like this:
2022 : .NET 7 : .NET Framework 4.8.1
However, I vastly prefer separating out each entry onto its own row for readability. This produces the following markdown and chart:
timeline
2000 - 2005
: .NET Framework 1.0
: .NET Framework 1.0 SP1
: .NET Framework 1.0 SP2
: .NET Framework 1.1
: .NET Framework 1.0 SP3
: .NET Framework 2.0
2006 - 2009
: .NET Framework 3.0
: .NET Framework 3.5
: .NET Framework 2.0 SP 1
: .NET Framework 3.0 SP 1
: .NET Framework 2.0 SP 2
: .NET Framework 3.0 SP 2
: .NET Framework 3.5 SP 1
2010 - 2015
: .NET Framework 4.0
: .NET Framework 4.5
: .NET Framework 4.5.1
: .NET Framework 4.5.2
: .NET Framework 4.6
: .NET Framework 4.6.1
2016 - 2017
: .NET Core 1.0
: .NET Core 1.1
: .NET Framework 4.6.2
: .NET Core 2.0
: .NET Framework 4.7
: .NET Framework 4.7.1
2018 - 2019
: .NET Core 2.1
: .NET Core 2.2
: .NET Framework 4.7.2
: .NET Core 3.0
: .NET Core 3.1
: .NET Framework 4.8
2020
: .NET 5
2021
: .NET 6
2022
: .NET 7
: .NET Framework 4.8.1
Adding Sections to our Timeline Chart
This timeline is already useful, but the colors don't convey much other than a gradual progression forwards in time.
You can group together multiple columns into a section to help convey meaning or relationships.
In our timeline, for example, .NET has really had 3 major phases of its life:
- The original .NET Framework, covering versions 1.0 to 4.8
- The open-source cross-platform revision known as .NET Core
- Modern .NET that dropped the ".NET Core" label to illustrate that this is the path going forward for .NET development.
We can add section nodes to convey this in our diagram:
timeline
section .NET Framework
2000 - 2005
: .NET Framework 1.0
: .NET Framework 1.0 SP1
: .NET Framework 1.0 SP2
: .NET Framework 1.1
: .NET Framework 1.0 SP3
: .NET Framework 2.0
2006 - 2009
: .NET Framework 3.0
: .NET Framework 3.5
: .NET Framework 2.0 SP 1
: .NET Framework 3.0 SP 1
: .NET Framework 2.0 SP 2
: .NET Framework 3.0 SP 2
: .NET Framework 3.5 SP 1
2010 - 2015
: .NET Framework 4.0
: .NET Framework 4.5
: .NET Framework 4.5.1
: .NET Framework 4.5.2
: .NET Framework 4.6
: .NET Framework 4.6.1
section .NET Core
2016 - 2017
: .NET Core 1.0
: .NET Core 1.1
: .NET Framework 4.6.2
: .NET Core 2.0
: .NET Framework 4.7
: .NET Framework 4.7.1
2018 - 2019
: .NET Core 2.1
: .NET Core 2.2
: .NET Framework 4.7.2
: .NET Core 3.0
: .NET Core 3.1
: .NET Framework 4.8
section Modern .NET
2020 : .NET 5
2021 : .NET 6
2022 : .NET 7
: .NET Framework 4.8.1
This now quite clearly segments the 3 major phases of .NET into sections - at least at the header levels.
Adding a Title
Our Mermaid.js timeline chart is doing quite well, but adding a title would help orient readers to what they're looking at.
We can do this in mermaid by adding a title row to the beginning of the markdown as shown below:
timeline
title Major .NET Releases
section .NET Framework
2000 - 2005
: .NET Framework 1.0
: .NET Framework 1.0 SP1
: .NET Framework 1.0 SP2
: .NET Framework 1.1
: .NET Framework 1.0 SP3
: .NET Framework 2.0
2006 - 2009
: .NET Framework 3.0
: .NET Framework 3.5
: .NET Framework 2.0 SP 1
: .NET Framework 3.0 SP 1
: .NET Framework 2.0 SP 2
: .NET Framework 3.0 SP 2
: .NET Framework 3.5 SP 1
2010 - 2015
: .NET Framework 4.0
: .NET Framework 4.5
: .NET Framework 4.5.1
: .NET Framework 4.5.2
: .NET Framework 4.6
: .NET Framework 4.6.1
section .NET Core
2016 - 2017
: .NET Core 1.0
: .NET Core 1.1
: .NET Framework 4.6.2
: .NET Core 2.0
: .NET Framework 4.7
: .NET Framework 4.7.1
2018 - 2019
: .NET Core 2.1
: .NET Core 2.2
: .NET Framework 4.7.2
: .NET Core 3.0
: .NET Core 3.1
: .NET Framework 4.8
section Modern .NET
2020 : .NET 5
2021 : .NET 6
2022 : .NET 7
: .NET Framework 4.8.1
And there we go. That's a nice and compact visual that illustrates the major releases of .NET over the last 20 years.
Closing Thoughts
As you can see, Mermaid.js timeline charts are fairly simple, but can be useful for creating high-level timelines that break things down by buckets of time.
However, I could easily see timelines being used for other things, such as representing work items by status, resource assignments, or other categorical variables.
Whenever you want to organize things by sequential columns and just need a simple card to display, a Mermaid.js Timeline chart might be worth considering.
While Mermaid.js Timeline charts aren't supported everywhere yet, I encourage you to look into their documentation and watch as more integrations support these powerful little charts.
Top comments (5)
This looks like such a versatile library. Thanks for the demo articles on it!
Not a problem. These are all to illustrate what Mermaid.js can do. I'm doing the series to help support a larger series on everything Polyglot Notebooks can do, which includes Mermaid.js. That series ultimately forms the basis of a talk I'm giving in early May.
I didn't know what Polyglot Notebooks was, so I looked it up and did some brief reading. I still don't know exactly what it is (I'll take another look when I have a bit more time), but it certainly looks very cool!
I'll be writing a lot more about it in coming weeks.
Nice, Thanks!