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

[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

[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 #1258 (comment) - 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!