feat: support mermaid code blocks in Markdown

[sjwall]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes OOTB Mermaid code block #1258) and the maintainers have approved on my working plan.

Note for third-party plugin authors using mdx loader

You should pass this new mdx loader option:

const loader = {
  loader: require.resolve('@docusaurus/mdx-loader'),
  options: {
    markdownConfig: siteConfig.markdown,
  },
}

Motivation

#1258 Have Mermaid diagrams supported OOTB. Merged code from mdx-mermaid library

Test Plan

There are unit tests for the remark plugin. There are also diagram examples from the Mermaid docs in the dogfooding pages

For the config here is an example docusaurus.config.js themeConfig:

themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      mermaid: {
        theme: {
          light: 'dark',
          dark: 'forest'
        },
        config: {
          // Mermaid config
        }
      },
  })

Test links

Deploy preview:

• https://deploy-preview-7490--docusaurus-2.netlify.app/docs/markdown-features/diagrams/
• https://deploy-preview-7490--docusaurus-2.netlify.app/tests/pages/diagrams

Local:

• http://localhost:3000/docs/markdown-features/diagrams/
• http://localhost:3000/tests/pages/diagrams

Related issues/PRs

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	1377f4a
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/63497ee6d6a0660009ec620b
😎 Deploy Preview	https://deploy-preview-7490--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 86	🟢 98	🟢 100	🟢 100	🟠 80	Report
/docs/installation	🟠 77	🟢 100	🟢 100	🟢 100	🟢 90	Report

[Josh-Cena]

We need to make this opt-in.

Before we allow plugins to provide Markdown plugins (#6370), what about keeping the MDX loader part but hiding it behind a siteConfig.markdown.mermaid option that defaults to false, and also create another @docusaurus/theme-mermaid package for the theme components?

[sjwall]

I shall have a look at making those 2 changes. Should I move the mermaid and theme config into siteConfig.markdown.mermaid?

Something like:

export type DocusaurusConfig = {
  markdown?: {
    mermaid?: boolean | {
      theme?: {
        light: mermaidAPI.Theme;
        dark: mermaidAPI.Theme;
        [htmlTheme: string]: mermaidAPI.Theme;
      };
      config?: mermaidAPI.Config;
    }
  }
}

[Josh-Cena]

Theme options should be still in theme config. The markdown.mermaid option will be read by the MDX loader only to decide whether the mermaid plugin should be loaded. It's a bit redundant now, but in the future when it's populated by more definitions it will make more sense.

[Josh-Cena]

Sorry, left a bunch of random review comments... There's a bit left to be desired in this PR's approach. Let me know if you need help with any of the refactors. We are not in a rush anyways.

[sjwall]

Sorry, left a bunch of random review comments... There's a bit left to be desired in this PR's approach. Let me know if you need help with any of the refactors. We are not in a rush anyways.

No worries, I wasn't at all familair with how Swizzle works before this PR so there was bound to be teething problems :) Hopefully now all good 🤞

[Josh-Cena]

Thanks, this is starting to look good!

I don't have much feedback for you to change. I'll play with this myself over the following days and push to your branch.

[Josh-Cena]

This looks very unsafe to have every effect mutate something... Effects aren't guaranteed to run in any order or run at any particular time, so this is practically not much better than assigning a random number to each SVG. This should be fixable with React 18's useId hook?

[sjwall]

I think so, shouldn't be an issue for now though 🤞

[slorber]

All diagrams on the same page will have the exact same ID because the counter is distinct for each instance.

I don't understand why Mermaid want an ID, can you explain?

If it's only used client-side, you could just wrap the component in <BrowserOnly> and generate a random number for each instance? (ie no need to increment)

[slorber]

Note for future self: I'm removing the MDXComponents from the Mermaid theme:

import MDXComponents from '@theme-init/MDXComponents';
import Mermaid from '@theme/Mermaid';

export default {
  ...MDXComponents,
  mermaid: Mermaid,
};

We want the mermaid theme to be able to register a theme component to the MDX context so that mdx loader can render it. Unfortunately, we want a plugin lifecycle API to allow it, but we don't have it yet.

The code above is not ideal because we can only wrap and "enhance" MDXComponents once, cf my comment (#7490 (comment)) and #4530, so I'd prefer not to use this solution.

Instead I'm doing like the SearchBar: render nothing by default in the theme classic, and let the theme enhancer override the implementation. Having a NOOP Mermaid component in theme-classic allows it to register it automatically to the MDXComponents so that we don't need to enhance this map

[slorber]

Note: this implementation does not support server-side-rendering and has a few limitations:

• does not work without JS, no progressive enhancement
• produces layout shifts on page load, due to diagrams appearing after React hydration

Unfortunately Mermaid does not make it easy to pre-render SVGs at build time (see mermaid-js/mermaid#3650 (comment)).

It would require to run a headless browser like Puppeteer, and for dark/light mode support we would have to build each diagram twice, which is also not ideal. For now let's keep things simple and only render client-side with the known limitations.

[SimenB]

Wooooooooo 🎉