Include diagrams in your Markdown files with Mermaid

This page summarizes the projects mentioned and recommended in the original post on news.ycombinator.com

Our great sponsors
  • Appwrite - The Open Source Firebase alternative introduces iOS support
  • InfluxDB - Build time-series-based applications quickly and at scale.
  • Sonar - Write Clean JavaScript Code. Always.
  • asciiflow

    ASCIIFlow

    This is interesting, but I personally really like that markdown is almost as legible as plain text as when rendered, which things like this sort of break.

    So I think I'd prefer ASCII art diagrams for this sort of thing. (In fact there was recently an ASCII diagram drawing tool on the front page, https://asciiflow.com/ )

  • Mermaid

    Edit, preview and share mermaid charts/diagrams. New implementation of the live editor.

    I’m not impressed with what I see of the three that there are.

    The most recent one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-2328372: I would be very concerned about trusting code that could be in any way adjacent to security written by whoever wrote (and whoever committed) this original sanitizeUrl function <https://github.com/mermaid-js/mermaid/commit/066b7a0d0bda274...>. .replace(/javascript:/g, '') is obviously catastrophically wrong, breaking valid (though uncommon) URLs and completely failing to guard against javascript: URLs. Yes, it’s fixed now, but its existence is highly alarming.

    The middle one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-1314738: the patch provided is utterly misguided and does not fix the alleged security vulnerability in the slightest—it barely even puts a bandaid over it, and it definitely breaks legitimate and reasonable stuff. See <https://github.com/mermaid-js/mermaid/pull/2123/commits/3d22...>: this is trivially insufficient and catastrophically wrong in its approach, so that if anything is actually depending on this code for security, it’s certainly broken. I haven’t immediately got an XSS in https://mermaid.live (something else is evidently providing the actual protection—the report may never have been invalid, or it’s still there), but it ruins reasonable labels like “Consider javascript: it’s not compiled” or “Do you strip javascript: URLs?” by removing the “javascript:” (eww!), but I can easily sneak a javascript: in there because of the sequential replacement done, with the likes of `javaI’ve looked at two of them, might as well look at the third, https://security.snyk.io/vuln/SNYK-JS-MERMAID-174698. Oh wow. The first patch <https://github.com/mermaid-js/mermaid/commit/c33533082c598a0...> introduced /javascript:./g removal, which is sufficient but excessive (thus bad), implemented separately for flowchart and gantt (that’s a terrible idea that will consistently lead to divergent changes and missed places; this is library functionality that needs* to be maintained in one place). Then the second patch <https://github.com/mermaid-js/mermaid/commit/f11d1a6fa1a5350...> switches to a real sanitiser, but leaves the terrible first approach around in a comment in one instance. And removes a bunch of console.log() calls that should never have been there. And starts escaping = as &equals; for no reason (if you need this, something is badly wrong). And changes some conf to getConfig().flowchart for some reason. All in the one commit, with a nigh-useless commit message. This is not a clean code base.

    From what I’ve seen so far, I’m fairly confident that an audit of the code base will reveal multiple fairly severe security vulnerabilities. Also that if I started actually reviewing it I’d be crying out to drastically refactor large parts of it. I’m going to tip-toe away before I start poking this 20,000 line code base (excluding tests). :-)

  • Appwrite

    Appwrite - The Open Source Firebase alternative introduces iOS support . Appwrite is an open source backend server that helps you build native iOS applications much faster with realtime APIs for authentication, databases, files storage, cloud functions and much more!

  • kroki

    Creates diagrams from textual descriptions!

    Re: https://github.com/github/markup/issues/533

    I’m the main author of KeenWrite (see screenshots), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.

    First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).

    Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)

    Third, see the CommonMark discussion thread referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.

    Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:

        ``` diagram-mermaid

  • mermaid

    Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

    I’m not impressed with what I see of the three that there are.

    The most recent one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-2328372: I would be very concerned about trusting code that could be in any way adjacent to security written by whoever wrote (and whoever committed) this original sanitizeUrl function <https://github.com/mermaid-js/mermaid/commit/066b7a0d0bda274...>. .replace(/javascript:/g, '') is obviously catastrophically wrong, breaking valid (though uncommon) URLs and completely failing to guard against javascript: URLs. Yes, it’s fixed now, but its existence is highly alarming.

    The middle one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-1314738: the patch provided is utterly misguided and does not fix the alleged security vulnerability in the slightest—it barely even puts a bandaid over it, and it definitely breaks legitimate and reasonable stuff. See <https://github.com/mermaid-js/mermaid/pull/2123/commits/3d22...>: this is trivially insufficient and catastrophically wrong in its approach, so that if anything is actually depending on this code for security, it’s certainly broken. I haven’t immediately got an XSS in https://mermaid.live (something else is evidently providing the actual protection—the report may never have been invalid, or it’s still there), but it ruins reasonable labels like “Consider javascript: it’s not compiled” or “Do you strip javascript: URLs?” by removing the “javascript:” (eww!), but I can easily sneak a javascript: in there because of the sequential replacement done, with the likes of `javaI’ve looked at two of them, might as well look at the third, https://security.snyk.io/vuln/SNYK-JS-MERMAID-174698. Oh wow. The first patch <https://github.com/mermaid-js/mermaid/commit/c33533082c598a0...> introduced /javascript:./g removal, which is sufficient but excessive (thus bad), implemented separately for flowchart and gantt (that’s a terrible idea that will consistently lead to divergent changes and missed places; this is library functionality that needs* to be maintained in one place). Then the second patch <https://github.com/mermaid-js/mermaid/commit/f11d1a6fa1a5350...> switches to a real sanitiser, but leaves the terrible first approach around in a comment in one instance. And removes a bunch of console.log() calls that should never have been there. And starts escaping = as &equals; for no reason (if you need this, something is badly wrong). And changes some conf to getConfig().flowchart for some reason. All in the one commit, with a nigh-useless commit message. This is not a clean code base.

    From what I’ve seen so far, I’m fairly confident that an audit of the code base will reveal multiple fairly severe security vulnerabilities. Also that if I started actually reviewing it I’d be crying out to drastically refactor large parts of it. I’m going to tip-toe away before I start poking this 20,000 line code base (excluding tests). :-)

  • aasvg

    Turn ASCII art into SVG

    > I think so-called ASCII-art is more in the spirit of Markdown.

    If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful.

    In some ways this is what the DOT language does in Graphviz:

    * https://graphviz.org/gallery/

    > The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.

    I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find:

    * https://github.com/martinthomson/aasvg

  • step-ca-on-rpi

    Smallstep Certificate Authority on Rpi4 with Yubikey

    I use Monodraw on macOS and then embed the ASCII art into the Markdown in my README.

    For example, https://github.com/mafrosis/step-ca-on-rpi#sso-for-ssh

    I'd usually commit the source .monodraw files to the repo, but for some reason I didn't in that example repo :/

  • markup

    Determines which markup library to use to render a content file (e.g. README) on GitHub

    Re: https://github.com/github/markup/issues/533

    I’m the main author of KeenWrite (see screenshots), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.

    First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).

    Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)

    Third, see the CommonMark discussion thread referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.

    Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:

        ``` diagram-mermaid

  • InfluxDB

    Build time-series-based applications quickly and at scale.. InfluxDB is the Time Series Platform where developers build real-time applications for analytics, IoT and cloud-native services. Easy to start, it is available in the cloud or on-premises.

  • svgbobrus

    Convert your ascii diagram scribbles into happy little SVG

  • gravizo

    How to include graphviz graphs in github README

  • spongedown

    Markdown with svg bob support

  • mexdown

    A lightweight integrating markup language

    I like this approach of using the tag associated with a code block to determine how to render the output. It's the same approach I take in my markdown-derived markup language: https://github.com/smasher164/mexdown.

    The top example there takes a GraphViz description and passes it into the dot command, placing the resultant SVG into the HTML output.

  • viz.js

    Graphviz for the web (Viz.js on a diet) (by rapidlua)

  • Joplin

    Joplin - an open source note taking and to-do application with synchronisation capabilities for Windows, macOS, Linux, Android and iOS.

    This is a known issue which hopefully should be fixed soon: https://github.com/laurent22/joplin/issues/6074

  • asciitosvg

    Create beautiful SVG renderings of ASCII diagrams.

  • HedgeDoc

    HedgeDoc - The best platform to write and share markdown.

    Shoutout for Hedgedoc a fork of CodiMD - Hedgedoc supports Mermaid already next to a lot of other markdown syntax:

    https://hedgedoc.org/

  • obsidian-releases

    Community plugins list, theme list, and releases of Obsidian.

  • Zettlr

    A Markdown Editor for the 21st century.

    Zettlr[1] (FOSS) has mermaid support included. Zettlr is a markdown editor for personal knowledge management and/or distraction free (scientific) writing w/ PDF publishing.

    [1] https://github.com/Zettlr/Zettlr

  • backendlore

    How I write backends

    A good example of ASCII diagrams: https://github.com/fpereiro/backendlore

  • Sonar

    Write Clean JavaScript Code. Always.. Sonar helps you commit clean code every time. With over 300 unique rules to find JavaScript bugs, code smells & vulnerabilities, Sonar finds the issues while you focus on the work.

NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a more popular project.

Suggest a related project

Related posts