remark, gfm and mermaid support

[ChristianMurphy]

GitHub is currently planning to add mermaid support to GitHub.com github/roadmap#372
With support coming to GitHub, interest in using mermaid with remark will grow.
There are currently a few community plugins to support mermaid, but none appear to support the latest version of remark (currently version 14):

• https://github.com/temando/remark-mermaid supports remark 10
• https://github.com/remcohaszing/remark-mermaidjs supports remark 13
• https://github.com/Braincoke/gridsome-plugin-remark-mermaid supports remark 11
• https://github.com/aloisklink/remark-mermaid-dataurl supports remark 13
• https://github.com/remcohaszing/gatsby-remark-mermaid supports remark 13?

There is also a rehype plugin

• https://github.com/bitekong/rehype-mermaid supports rehype 12

Is there interest in adopting one of these plugins into the remarkjs org?
Or perhaps creating a new plugin which could attempt to cover the use cases of most or all of the above?

[remcohaszing]

There’s also gatsby-remark-mermaid. I didn’t create it, but the original owner didn’t want to maintain it anymore.

[ChristianMurphy]

Thanks! Added to the list, it looks like it is designed for remark 13? Is that accurate?

[remcohaszing]

I don’t know to be honest. It’s for Gatsby specifically (because Gatsby can’t handle regular remark plugins for some reason). I used it with Docz at the time, but never really looked at what remark version was being used under the hood.

[ChristianMurphy]

Thinking some more on this, and based off some discussion with @remcohaszing.
I wonder if we may want a similar solution to https://github.com/remarkjs/remark-math

A mono-repo with several packages. A generic remark plugin to parse/annotate mermaid blocks, along side several rehype backends to generate the charts. Allowing for flexibility for running mermaid inside puppeteer, playwright, a browser, a virtual dom, etc.

[remcohaszing]

I don’t think there’s much value in splitting them into multiple plugins for parsing and rendering. Mermaid is used for both parsing and rendering.

[ChristianMurphy]

I don’t think there’s much value in splitting them into multiple plugins for parsing and rendering

The main consideration I had on the parsing/transform side, was avoiding a conflict with syntax highlighting.
But that could be addressed in other ways.

In general I agree that Mermaid can take care of most of the parsing/rendering of it's own content.
And that the output (HTML) would likely fit best in rehype plugin(s).

[wooorm]

I’m thinking of porting it to a version that doesn‘t require the DOM. Similar to lowlight/refractor/remarkjs/remark-math#41. If possible

[ChristianMurphy]

This would be good, especially since jsdom doesn't seem to work (credit: remcohaszing/remark-mermaidjs#3 (comment))
https://github.com/mermaid-js/mermaid/issues?q=is:issue+jsdom

[remcohaszing]

This is not a small task though, and it’s a lot of maintenance to keep up feature parity with the original mermaid library.

[wooorm]

I don’t think mermaid is “keeping up”. It heavily depends on https://github.com/dagrejs/graphlib for example. And has 500 open issues. 😬

[remcohaszing]

I also want to mention remark-mermaidjs uses svgo to minimize the svg output and inlines styles, because it’s heavily unoptimized and the generated class names are very prone to conflict with user styles.

[remcohaszing]

Another thing that might be interesting to consider is support for responsive light/dark mode.

[remcohaszing]

I have been thinking that maybe rehype is a better fit for processing mermaid charts than remark since mermaid produces SVG elements.

rehype-mermaid is not a regular rehype plugin. It’s written specifically for react-markdown.

[aloisklink]

If you're looking for a pure remark/CommonMark Markdown plugin, my https://github.com/aloisklink/remark-mermaid-dataurl was recently updated to be tested with Remark 14.

Essentially, it converts the SVG produced by mermaid into images that point to data URLs, ![Diagram generated via mermaid](data:image/svg+xml;charset=UTF-8,%3Csvg...).

Unfortunately, to achieve CommonMark compatibility, it has two major downsides:

• It's stored as an image, so interactive mermaid diagrams aren't possible.
  This does mean that styles wouldn't conflict with the main page, so that's a minor benefit.
  You could chain it with rehype-inline-svg after a remark-rehype conversion, if you'd rather have an inline SVG.
• It uses puppeteer for rendering the mermaid diagrams to SVG, so it's kinda slow/heavy to run.

There's also a remark-mdx plugin called https://github.com/sjwall/mdx-mermaid, which I really like. It injects the mermaid JavaScript code to render mermaid diagrams in the browser/mdx viewer (client-side rendering). It's also the basis of the upcoming docusaurus mermaid support: facebook/docusaurus#7490 Edit: This plugin is out-of-date. My recommendation is to use rehype-mermaidjs, unless you really need a Remark plugin.

[wooorm]

GitHub solves this with a custom iframe “subwebsite” (viewscreen.githubusercontent.com), that they pass data to, and which renders diagrams. They also use it for topojson/geojson/stl.
With an inspector in dev tools, you can get access to the code they use, and get an idea of how it all works:

Code for below

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

```geojson
{
    "type": "Point",
    "coordinates": [-122.43, 37.77],
    "properties": {"name": "SF", "marker-color": "ff6347"}
}
```

```topojson
{
  "type": "Topology",
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "coordinates": [-122.43, 37.77],
          "properties": {"name": "SF", "marker-color": "ff6347"}
        }
      ]
    }
  }
}
```

```stl
solid square
   facet normal -1 0 0
      outer loop
         vertex 0 100 100
         vertex 0 100 0
         vertex 0 0 100
      endloop
   endfacet
   facet normal -1 0 0
      outer loop
         vertex 0 0 100
         vertex 0 100 0
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 0 1
      outer loop
         vertex 100 100 100
         vertex 0 100 100
         vertex 100 0 100
      endloop
   endfacet
   facet normal 0 0 1
      outer loop
         vertex 100 0 100
         vertex 0 100 100
         vertex 0 0 100
      endloop
   endfacet
   facet normal 1 0 0
      outer loop
         vertex 100 100 0
         vertex 100 100 100
         vertex 100 0 0
      endloop
   endfacet
   facet normal 1 0 0
      outer loop
         vertex 100 0 0
         vertex 100 100 100
         vertex 100 0 100
      endloop
   endfacet
   facet normal 0 0 -1
      outer loop
         vertex 0 100 0
         vertex 100 100 0
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 0 -1
      outer loop
         vertex 0 0 0
         vertex 100 100 0
         vertex 100 0 0
      endloop
   endfacet
   facet normal 0 1 0
      outer loop
         vertex 100 100 100
         vertex 100 100 0
         vertex 0 100 100
      endloop
   endfacet
   facet normal 0 1 0
      outer loop
         vertex 0 100 100
         vertex 100 100 0
         vertex 0 100 0
      endloop
   endfacet
   facet normal 0 -1 0
      outer loop
         vertex 100 0 0
         vertex 100 0 100
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 -1 0
      outer loop
         vertex 0 0 0
         vertex 100 0 100
         vertex 0 0 100
      endloop
   endfacet
endsolid
```

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Loading

{
    "type": "Point",
    "coordinates": [-122.43, 37.77],
    "properties": {"name": "SF", "marker-color": "ff6347"}
}

Loading

{
  "type": "Topology",
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "coordinates": [-122.43, 37.77],
          "properties": {"name": "SF", "marker-color": "ff6347"}
        }
      ]
    }
  }
}

Loading

solid square
   facet normal -1 0 0
      outer loop
         vertex 0 100 100
         vertex 0 100 0
         vertex 0 0 100
      endloop
   endfacet
   facet normal -1 0 0
      outer loop
         vertex 0 0 100
         vertex 0 100 0
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 0 1
      outer loop
         vertex 100 100 100
         vertex 0 100 100
         vertex 100 0 100
      endloop
   endfacet
   facet normal 0 0 1
      outer loop
         vertex 100 0 100
         vertex 0 100 100
         vertex 0 0 100
      endloop
   endfacet
   facet normal 1 0 0
      outer loop
         vertex 100 100 0
         vertex 100 100 100
         vertex 100 0 0
      endloop
   endfacet
   facet normal 1 0 0
      outer loop
         vertex 100 0 0
         vertex 100 100 100
         vertex 100 0 100
      endloop
   endfacet
   facet normal 0 0 -1
      outer loop
         vertex 0 100 0
         vertex 100 100 0
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 0 -1
      outer loop
         vertex 0 0 0
         vertex 100 100 0
         vertex 100 0 0
      endloop
   endfacet
   facet normal 0 1 0
      outer loop
         vertex 100 100 100
         vertex 100 100 0
         vertex 0 100 100
      endloop
   endfacet
   facet normal 0 1 0
      outer loop
         vertex 0 100 100
         vertex 100 100 0
         vertex 0 100 0
      endloop
   endfacet
   facet normal 0 -1 0
      outer loop
         vertex 100 0 0
         vertex 100 0 100
         vertex 0 0 0
      endloop
   endfacet
   facet normal 0 -1 0
      outer loop
         vertex 0 0 0
         vertex 100 0 100
         vertex 0 0 100
      endloop
   endfacet
endsolid

Loading

[remcohaszing]

I created rehype-mermaidjs, which may also be added to this list. :)

Also remark-mermaidjs supports remark 14.