DEV Community

Cover image for Creating Timeline Charts with Mermaid.js
Matt Eland
Matt Eland Subscriber

Posted on • Originally published at newdevsguide.com

Creating Timeline Charts with Mermaid.js

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:

Timeline of .NET ReleasesIn 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
Enter fullscreen mode Exit fullscreen mode

This generates a simple timeline with the time periods I defined:

Timeline Chart with Year BucketsIt'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
Enter fullscreen mode Exit fullscreen mode

Timeline ChartAdding 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
Enter fullscreen mode Exit fullscreen mode

Timeline Chart with SectionsThis 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
Enter fullscreen mode Exit fullscreen mode

Full Timeline ChartAnd 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)

Collapse
 
ant_f_dev profile image
Anthony Fung

This looks like such a versatile library. Thanks for the demo articles on it!

Collapse
 
integerman profile image
Matt Eland

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.

Collapse
 
ant_f_dev profile image
Anthony Fung

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!

Thread Thread
 
integerman profile image
Matt Eland

I'll be writing a lot more about it in coming weeks.

Collapse
 
iz profile image
IZ

Nice, Thanks!