Creating Timeline Charts with Mermaid.js
Tags: dotnet, mermaid, beginners, markdown
Published: 2023-04-16 19:07:06

---
title: Creating Timeline Charts with Mermaid.js 
published: true
series: Mermaid.js
description: Mermaid.js Timeline charts let you quickly represent high-level timelines for projects and product development cycles using simple markdown.
tags: dotnet, mermaid, beginner, markdown
canonical_url: https://newdevsguide.com/2023/04/16/mermaid-timeline-charts/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nikirlk8j1dn105chpvx.png
---

Earlier this week I wrote about [using Mermaid.js to create Gantt charts](https://newdevsguide.com/2023/04/14/mermaid-gantt-chart/) 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 Releases](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-84.png?resize=1024%2C555&ssl=1)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](https://mermaid.live/) 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:

![Timeline Chart with Year Buckets](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-85.png?resize=1024%2C191&ssl=1)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
```


![Timeline Chart](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-86.png?resize=1024%2C444&ssl=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
```


![Timeline Chart with Sections](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-87.png?resize=1024%2C499&ssl=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
```


![Full Timeline Chart](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-88.png?resize=1024%2C534&ssl=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](https://mermaid.js.org/syntax/timeline.html) and watch as more integrations support these powerful little charts.