Docusaurus: Integrate with mermaidjs

[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;

1. 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.