Displaying Gantt charts on GitHub

GitHub Markdown can render Mermaid diagrams including Mermaid Gantt charts. I discovered this from Simon Willison who shared Bryce Mecum’s post on using Mermaid Gantt diagrams to display traces.

A Gantt diagram can be created and rendered within a code block tagged mermaid, a simple example copied from the docs can be seen below.

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d

I previously used MarkWhen’s Meridiem online editor to create Gantt charts to visualise the service life on Dutch Sprinter trains, this required me to share screenshots of the chart unless I created a view-only copy. Using GitHub I can share a gist with the details of the chart, which others can then use or modify. The migration from MarkWhen to Mermaid isn’t perfect, but it’s a start.

The MarkWhen code looked like this:

#PlanV
#SGM
#SM90
#SLT
#SNG
#FLIRT
title: Sprinter Service Timeline

1962-2014: Mat '64 in service #PlanV
1975-2021: SGM in service #SGM
1994-2005: SM '90 in service #SM90
2009-now: SLT in service #SLT
2016-now: FLIRT in service #FLIRT
2018-now: SNG in service #SNG

The same description in Mermaid looks like this:

gantt
    title Sprinter Service Timeline
    dateFormat YYYY
    tickInterval 12month
    axisFormat %Y
    todayMarker off

    section Section
    Mat'64  :1962, 2014
    SGM     :1975, 2021
    SM '90  :1994, 2005
    SLT     :2009, until now
    FLIRT   :2016, until now
    SNG     :2018, until now
    today   :now, 2024, 2024

The generated diagrams differ in a few ways

1. Color: There isn’t a way I’ve found to set the colour of each “task” within Mermaid. Using MarkWhen I’ve added a tag for each rolling stock that generates a random colour in the diagram, I can also choose a specific colour within the defintion.
2. Time interval: The time internal ticks are automatically set in MarkWhen depending on the tasks you add in the definition and their date range. Within Mermaid you can see I’ve set the axis to only show the year, and set the interval to 12 months which is the maximum length of time possible. The date axis is a little cramped but you cannot adjust the rotation of the text (without injecting CSS) or increase the interval to show every other year, to my knowledge. Removing the tickInterval parameter defaults to showing every 5 years, missing the first and last year.
3. Lastly, in Mermaid I’ve not found a way to set a start date for a task and have it continue till the present day. So I create a task labelled today with the variable name now. I then refer to now in every task that I want to continue until the present day. When the year changes (for example to 2025), I will have to update the today task and it will update all the tasks that refer to it.

With all that said, here’s the GitHub Gist created for the Gantt diagram. The Mermaid description was created using the Mermaid Live editor. Even though GitHub renders Mermaid diagrams, if you edit a markdown file the preview only shows the code block without rendering the diagram, so you’ll need to use a Mermaid editor.

When it comes to readability and visual aesthetics MarkWhen still wins for me. The code is also less verbose and easier to use. MarkWhen has many more options to edit Gantt charts a whole ecosystem of tools and integration that I don’t use but Mermaid has more capabilities on rendering options on the web and in other tools as well as the ability to render other diagram types. Tough choice between the two for Gantt charts.