OOTB Mermaid code block

[amimas]

🚀 Feature

mermaidjs seems to be a pretty neat tool that allows drawing diagrams using markdown. It'd be nice if Docusaurus can be integrated with that.

Have you read the Contributing Guidelines on issues?

yes

Motivation

Most documentation needs to show diagrams. The current method involves using some external tool and then create an image (i.e. png, svg, jpg, etc). You'll need to manage those diagrams yourself separate from the content.

Pitch

Draw diagrams in the markdown along with the actual content where they are going to be used. This will make it a lot easier to maintain document (contents + diagrams) all in one place.

[leonardfactory]

Non sure if the plugin is still updated but there is remarkable-mermaid. I’m interested in this too but I haven’t found the time to test it

[endiliey]

I think this is best left to markdown parser plugins.

[hassanfarid]

This should be really good addition to support product technical documentation in Docusaurus.

[endiliey]

After much consideration, this is indeed best left to markdown plugin

https://github.com/temando/remark-mermaid on v2 and remarkable-mermaid on v1

[ntsd]

@endiliey

Hey did anyone did it on version 2 yet?

Maybe I can help contribute?

[eugenenelou]

Hey did anyone did it on version 1? remarkable-mermaid is not even on npm and I cannot make it work as is.

[ericfourrier]

any update on this ?

[18dew]

Nope i dont think so any one has writen any code over this yet ...

[chmelevskij]

With the current version it's pretty straightforward to integrate:

// siteConfig.js
    scripts: [
        'https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.4.4/mermaid.min.js',
        '/init.js',
    ],
    markdownPlugins: [ (md) => {
        md.renderer.rules.fence_custom.mermaid = (tokens, idx, options, env, instance) => {
            return `<div class="mermaid">${tokens[idx].content}</div>`;
        };
    }],

Then in init simply

/* eslint-disable */
window.addEventListener('load', function() {
    mermaid.initialize({startOnLoad:true});
});

Usage:

```mermaid
graph TB
    a-->b'

[bodiam]

Hi @chmelevskij , thanks for sharing. Is there any way to get this to work on Docusaurus 2?

[ghost]

Hi @chmelevskij , thanks for sharing. Is there any way to get this to work on Docusaurus 2?

in v2, you can make your own Component an import it into your markdown.

1. install mermaid yarn add mermaid
2. create file in your src/theme/Mermaid.js
3. Mermaid.js

import React, { useEffect } from "react";
import mermaid from "mermaid";

mermaid.initialize({
	startOnLoad: true
});

const Mermaid = ({ chart }) => {
	useEffect(() => {
		mermaid.contentLoaded();
	}, []);
	return <div className="mermaid">{chart}</div>;
};

export default Mermaid;

4. doc1.md

import Mermaid from '@theme/Mermaid';
...
<Mermaid chart={`
	graph LR;
		A-->B;
		B-->C;
		B-->D[plop lanflz eknlzeknfz];
`}/>
...

[bodiam]

Thank you so much!! That's easier than I thought!

[mbykovskyy]

After much consideration, this is indeed best left to markdown plugin

https://github.com/temando/remark-mermaid on v2 and remarkable-mermaid on v1

@endiliey, is there away to specify a data.destinationDir on a currently processed MD vFile? Without such configuration remark-mermaid writes SVGs into the same directory as the MD file.

[lucaslz2020]

Hi @chmelevskij , thanks for sharing. Is there any way to get this to work on Docusaurus 2?

in v2, you can make your own Component an import it into your markdown.

1. install mermaid yarn add mermaid
2. create file in your src/theme/Mermaid.js
3. Mermaid.js

import React, { useEffect } from "react";
import mermaid from "mermaid";

mermaid.initialize({
	startOnLoad: true
});

const Mermaid = ({ chart }) => {
	useEffect(() => {
		mermaid.contentLoaded();
	}, []);
	return <div className="mermaid">{chart}</div>;
};

export default Mermaid;

1. doc1.md

import Mermaid from '@theme/Mermaid';
...
<Mermaid chart={`
	graph LR;
		A-->B;
		B-->C;
		B-->D[plop lanflz eknlzeknfz];
`}/>
...

This way is still more troublesome.

expect:

graph
A --> B

[sjwall]

I have taken the Mermaid component example given above and bundled it in a package mdx-mermaid

The package also includes a remark plugin so that it can be used with code blocks

There are setup instructions and examples here

If you run into problems, please raise an issue on the github repo

[slorber]

Thanks for creating a package @sjwall ! btw you can add it there: https://docusaurus.io/community/resources

[emerxom]

I have taken the Mermaid component example given above and bundled it in a package mdx-mermaid

The package also includes a remark plugin so that it can be used with code blocks

There are setup instructions and examples here

If you run into problems, please raise an issue on the github repo

@sjwall Is it possible to set the theme dark when it is used in docusaurus? In a way it would update when the theme is switched on the interface

[sjwall]

@botteroxom The enhancement to the plugin to follow the docusaurus theme is being tracked here https://github.com/sjwall/mdx-mermaid/issues/4

[SimenB]

Since GH is adding support natively (https://github.com/github/roadmap/issues/372), any chance of docusaurus having native support as well? Not a huge issue adding the above plugin of course, but more feature parity out of the box sounds like a win to me 😀

[slorber]

Didn't know thanks.

Are there similar Github features that Docusaurus does not support?

@wooorm do you think you'll do anything inside of Remark GFM? https://github.com/remarkjs/remark-gfm

This feature is now GFM but is not strictly related to Markdown syntax so not sure where it should live 🤷‍♂️ but probably more in Docusaurus that Remark-GFM IMHO

[wooorm]

Thanks for the ping. Will likely depend on how they do it.

With footnotes, they didn’t bother to update the GFM spec, but it’s a syntax extension to their parser, so it is a de-facto part of GFM.

I’m assuming that mermaid will be implemented at a different level, similar to say, syntax highlighting code. That’s not part of GFM, but part of what github.com does on their site.

So, likely, it’d would be a different project.

[slorber]

Thanks 👍

Let's wait and see then ;)

[felipecrs]

It's live now:

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Native support for Mermaid in Docusaurus would be nice. :)

[Josh-Cena]

Has anyone experimented with remark-mermaid and checked if it works with Docusaurus? Does it have to be built-in? I'm not against making it OOTB, but better see if there has been community work being done already.

[antonk52]

@Josh-Cena I could not get it working out of the box. However, I was able to get mermaid work in a GFM compatible way. It works by introducing a theme component Mermaid(like the one shown above) that is also in MDXComponents. And adding a custom remark plugin. It does not handle all cases but works as a proof of concept.

custom remark plugin

function remarkMermaid() {
  return function transformer(root: any) {
    root.children = root.children.map(x => {
        if (x.type === 'code' && x.lang === 'mermaid') {
          const loc = {
            start: {line: x.position.start.line, column: x.position.start.column},
            end: {line: x.position.end.line, column: x.position.end.column},
          };
          const start = x.position.start.offset;
          const end = x.position.end.offset;
          const range = [start, end];
          const mermaidNode = {
            type: 'mdxJsxFlowElement',
            name: 'Mermaid',
            data: {_xdmExplicitJsx: true},
            children: [],
            attributes: [{
                type: 'mdxJsxAttribute',
                name: 'chart',
                value: {
                  type: 'mdxJsxAttributeValueExpression',
                  value: ['`\n', x.value, '`'].join('\n'),
                  data: {
                    estree: {
                      body: [{
                        type: "ExpressionStatement",
                        start,
                        range,
                        loc,
                        expression: {
                          loc,
                          range,
                          start,
                          end,
                          type: "Literal",
                          value: x.value,
                          raw: ['`\n', x.value, '`'].join('\n'),
                        },
                      }],
                      comments: [],
                      end,
                      loc,
                      range,
                      sourceType: "module",
                      start,
                      type: "Program",
                    },
                  },
                },
                position: x.position,
              }],
          };
          return mermaidNode;
        }

        return x;
    });
  };
};

[Josh-Cena]

Going to re-open. I think it would be very helpful to have this out-of-the-box.

[Josh-Cena]

VS Code has also added support for Mermaid: https://twitter.com/mattbierner/status/1522003140777701376

Many Markdown renderers also support it. I see a general trend to make this available out-of-the-box. If anyone wants to try their hands at a remark plugin, PRs are welcome.

[garyng]

I've been using mdx-mermaid mentioned in https://github.com/facebook/docusaurus/issues/1258#issuecomment-894703484 - it works fine for me!

[sjwall]

@Josh-Cena I am looking at merging in mdx-mermaid, should hopefully have a PR together this week

[jpadams]

Super excited to see this land! Thanks for all of the hard work!