Mermaid Gantt diagrams for displaying distributed traces in Markdown (2023)

We are doing some fundamental changes to how diagrams are rendered, which would enable us to support more renderers. This will enable us to do server side rendering without a browser.

The main reason why we need a browser currently is size calculations of the SVG boxes, which libraries like jsdom does not support.

I was going to point to https://github.com/mermaid-js/mermaid-cli, but it uses puppeteer and chromium under the hood. That seems...excessive, to render an SVG.

https://github.com/mermaid-js/mermaid/issues/2485

Mermaid diagrams do not render correctly using the following programs and libraries:

    Adobe FrameMaker 2020
    Apache Batik
    EchoSVG
    svgSalamander
    resvg
    rsvg-convert
    svglib
    prawn-svg
    CairoSVG
    ConTeXt
    QtSVG
    MS Word
    PlutoSVG

I don’t disagree, but aren’t we actually using kind of a headless browser rendering toolkit for SVG anyway?

PlantUML also has gantt chart (https://plantuml.com/gantt-diagram ) support. unfortunately does not scale below days. There is a chronology diagram(https://plantuml.com/chronology-diagram) available but not linked from the main documentation or documented very much at all. Though it looks like the correct diagram in plantuml for the data in OP is a timing diagram (https://plantuml.com/timing-diagram)

Graphviz is hard. I only need a graph making tool three or four times a year and when I go back to mermaid, only 5 minutes of going through the documentation get's me up to speed. But graphviz is much more complex in a way I often don't need. It's also pretty verbose; You first need to define nodes then the connections while in mermaid both are done in a single line.

However mermaid's experience and output is definitely subpar. Under the saved graphs section you find randomly saved graphs and there is no way to organize multiple graphs in the web editor.

I've even thought of writing a simple script to translate mermaid charts into dot language.

It is very difficult to save the images as bitmap (.jpeg, .mpng) or vector (.svg)

Huh? It's quite trivial, and even some tools for VS Code and other environments support it.

You basically have to use a headless browser rendering toolkit, and guess what? The images aren't consistent (different rendering styles)

Is your problem saving Mermaid as images or lamenting cross browser rendering consistency?

If it's the former, why is the latter a problem? Use a single headless browser rendering toolkit and stick with it. Who said you need to use multiple and compare?

And there are other ways to do it, like exporting from an actual in-browser render, or even a VS Code extension - it can also be found in other tools based on Electron.

I work on Scroll (https://scroll.pub), which currently compiles to HTML/TXT et cetera.

Compiling to JPG, SVG, PDF, MKV, MP4, et cetera, are high on my todo list, but I really haven't seen a standout way to do that, beyond that would run through Chromium.

I wonder if Ladybird (https://ladybird.org/) might be appropriate for that use case? Not sure if it's a new rendering engine or what.

May I suggest my favorite: blockdiag (including seqdiag, nwdiag, and actdiag, and rackdiag (rackdiag super slept on!))

I've evaluated every diagrams-as-code tool in existence just about, and revisit them every year or two, and I keep coming back to blockdiag. Mermaid looked nice but had many issues I ran into.

blockdiag doesn't look as pretty out of the box, but when done right it looks really good, especially as an SVG

While I agree in principle, in practice the result would probably be terrible.

Just look at tables in GFM, which mostly were designed as you propose. They look like tables even before rendering, however the experience of actually creating and editing the tables is not fun at all.

I have a horse in this race (co-founder of a markdown-based note-taking app) and to me, the benefit of markdown is easy + explicit editing, not that it looks the same in plain text vs rendered.

Yea, I have to agree. I don't agree with the title. It may be convenient to put Mermaid Gantt diagram SPECIFICATIONS in a Markdown document, but they are not great for displaying the Gantt charts in Markdown.

To me a more accurate title and summary of the article is "TIL: Mermaid Gantt diagram specifications can be embedded and processed in Markdown documents".

I've been loving this service called CodeRabbit that auto generates these diagrams off my pull requests, it's fantastic -> https://github.com/jsonresume/jsonresume.org/pull/131#issuec...

Yes, looks like they could be adapted to create Story Maps

I love diagrams to represent how systems are setup and run. At one employer, they had hundreds of spreadsheets around the network drive which often linked together via formula or VBA code, along with queries out to databases.

I built a file parser (in VBA, because that is what was available) to log every file reference to a big table, the generate graphviz code to visualize it.

It's easy to say "tons of stuff uses $datasource", but it's way better if you can show exactly how much and the impact of changes.

It was incredibly useful when we changed our domain and all network drive mappings broke.

#1. mermaid is a syntax for diagrams that is markdown native, in that it is designed to be fit well in MD, and shares goals like ex. a progressive upgrade from text to render that is readable in either format

#2. Graphviz and gnuplot also render diagrams

#3. Sort of like asking if you can get a Markdown renderer in not JS: most direct answer is yes. If the Q is more "can Mermaid be rendered as SVG?", yes, the render format is SVG

Not a complete answer to your question, but Mermaid is a plain-text diagram format which, while far from perfect, is supported by Github. So if you're looking to include a simple chart in your Readme or Markdown docs, it's a good choice.

1. In markdown you can specify a language to perform syntax highlighting within code blocks -- e.g. ```java ... ```. If you use "mermaid" there you can get the mermaid plugin to render that block. This is useful when providing a system overview, etc. in a project readme file.

2. Mermaid is a diagram rendering tool similar to graphviz and D3.js. It uses a different syntax for each chart type with the intention of making it easy to write and to read when looking at markdown source.

3. You would need to use a separate program like graphviz to do the layout and generate an SVG, PNG or other file that you can reference in your markdown or other document files. If/when mermaid provides a similar capability you'll be able to use that instead.

https://nomnoml.com/ does allow export to SVG if I remember right. But does not do GNATT Diagrams AFAIK.

I just tried the LIVE Editor: https://mermaid.live/

Yes, it does allow SVG export. Nice!

Popular (or at least relevant) markdown implementations support mermaid charts. GitHub and gitlab do, for example.

Ha, I was pondering the exact same question after reading this, for this use-case and in more widespread sense. I've came to the conclusion that it's a form of outsourcing your costs. The clients want to view your charts? They pay for it with their electricity, instead of your server doing handouts for everyone.

I think that the point is to be easy to be changed, since Mermaid's first use case is to be used in building diagrams/graphs with data fetched at runtime like telemetry or finances data. I guess you can probably use Mermaid and take the resulting html and add it to the resulting document if you really want.

With SVG and PNG export! And MIT licensed! Looks great, thanks.

https://nomnoml.com/

Oh this is nice.

You need at least two leading spaces to get that to render as code and preserve the layout, like:

     Out of office: 
            [John Doe]
                         [Stacy]
     Release:
            [code freeze]
                           [Staging date]
                                            [Release!]

Thanks for the shoutout, glad you like it!

Also available for VS code[0] and Obsidian[1]

[0] https://marketplace.visualstudio.com/items?itemName=Markwhen...

[1] https://obsidian.md/plugins?search=Markwhen

If mermaid came with a similar integration in IDE and collaborative tooling, would you switched back?

It bothered me too. Apparently a single CSS addition makes it more reasonable:

    .grid .tick line { opacity: 0.3; }