Mermaid support

When creating markdown pages I want to add mermaid-syntax diagrams so that I can display nicely rendered diagrams

https://mermaid-js.github.io/mermaid/#/

Acceptance

• I can have have mermaid blocks and they render correctly ✅2022-08-16 see https://flowershow.app/docs/mermaid

```mermaid
graph TD

a --> b
\```

Tasks

• research options e.g. existing remark plugins
• Select one to try
• Try it
• Deploy
• Document
• …

Notes

We want a solution that renders client side (we do not want to render svg and insert)

Options

• https://github.com/temando/remark-mermaid 2022-07-26 this looks pretty promising for what we want 2022-08-02 summary: adding as a plugin in remark just throws error as seen in notes below
• https://github.com/sjwall/mdx-mermaid - Plug and play Mermaid in MDX 2022-08-02 summary:
  • adding as a plugin in remark just outputs the component as a string.
  • Adding the component in MDX components client side ie. Pre.js is complicated as rehype-prism-plus converts the graph to span elements and <Mermaid char={...} /> needs the graph as a string.
• https://github.com/remcohaszing/remark-mermaidjs - A remark plugin to render mermaid diagrams using puppeteer 2022-08-02 summary: not considering as puppeteer is a large dependency even if it works without much configuration needed

remark-mermaid

• throwing errors: Expected usable value, not 'undefined' Looks like it’s trying to parse wrong values.

mdx-mermaid with remark-code-extra (UPDATE)

Using this remark plugin - https://github.com/s0/remark-code-extra - to replace pre tag elements created by rehype-prism-plus, I have managed to make mdx-mermaid work nicely with it. See screenshots below for result and modified code in contentlayer.config.js

Brief summary of modified code:

Transforming the nodes for <Pre> elements and removing the ones created by rehype-prism-plus …

• Added the remark plugin in contentlayer with following configuration within it:
  • create a new pre tag element with just the string value as child and a new className .code-mermaid
  • remove the previous pre tag element created by rehype-prism-plus
• Modified the Pre.js component to check for the new className (code-mermaid) from props and if so, use Mermaid component ie. <Mermaid chart={children} />

The remark-code-extra plugin in contentlayer.config.js looks like this:

mdx-mermaid

• adding mdx-mermaid as a remark plugin just outputs a string as seen below. Probably happening since import statements in md are not working/resolved.

using mermaid component from mdx-mermaid in Pre.js component works after removing rehype-prism-plus plugin

Why rehype-prism-plus conflicts:

rehype prism plus modifies all the code blocks including mermaid. for example below markdown

graph LR
     Start --> Stop

would generate individual span elements for each line

<span>graph LR</span>
<span>Start --> Stop</span>

Since mdx-mermaid component takes only a string <Mermaid chart={'graph LR ....'} />, we have to map each span element and join them as strings. This gets complex when there are elements within.

A better approach would be to somehow make rehype-prism-plus to discard modifying the language-mermaid code block.

remark-mermaidjs

https://github.com/remcohaszing/remark-mermaidjs

• works and probably should go with this …
• needs some style fixes

Mermaidjs

https://mermaid-js.github.io/mermaid/#/

• If using this option we have to:
  • configure Pre.js component used in MDXComponents to make this work
  • Also have to do more nested stuff since rehype-prism-plus converts code blocks to components

    if (/^language-mermaid/.test(children.props.className.toLocaleLowerCase())) {
      useEffect(() => mermaid.initialize({ startOnLoad: true }), [])
      return <div className="mermaid my-12">{children.props.children.map(el => el.props.children).join().replace(/,/g, "")} </div>
    }
    

  • Additional configuration for color code support required (not implemented)

[rufuspollock]

@khalilcodes if this is working and relatively clean let’s go with this, perhaps documenting clearly here the approach and what improvements we would like in future (with perhaps some comments in code e.g. in contentlayer segment - that can also ref here - explaining that this is for mermaid support). That way 6m or a year from now when we look at the code we can understand why we did what we did and how we would improve or replace it if a new remark plugin comes out.

My other question is whether we want a standalone remark-mermaid plugin like we had with remark-wiki-link-plus?

[rufuspollock]

@khalilcodes thanks. I just refactored notes section to be a bit clearer. Could you update the bulleted list at the top of the notes with a summary of current evaluation and recommendation including effort to make it work and reliability (detail can be left out there and can go below in dedicated section for each option)