feat: support mermaid code blocks in Markdown

[sjwall]

Pre-flight checklist

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

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/

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

https://deploy-preview-7490--docusaurus-2.netlify.app/tests/pages/diagrams

Related issues/PRs

[netlify[bot]]

✅ [V2]

Name	Link
🔨 Latest commit	1377f4abaaaf093dc8ff87b9386808eaa0187c8a
🔍 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[bot]]

⚡️ 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

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

@sjwall I've pushed my refactors. It seems to still work as expected.

[Josh-Cena]

Bundle size doesn't look bad:

Size Change: +1.24 kB (0%)

Total Size: 799 kB

Filename	Size	Change
website/.docusaurus/globalData.json	52.7 kB	+181 B (0%)
website/build/assets/js/main.********.js	601 kB	+1.06 kB (0%)

ℹ️ View Unchanged

Filename	Size	Change
website/build/assets/css/styles.********.css	106 kB	0 B
website/build/index.html	38.9 kB	+1 B (0%)

_{compressed-size-action}

[sjwall]

Looks good to me, great rework. My only comment is on the IDs but I doubt that will actually be an issue.

[sjwall]

Hey @Josh-Cena I've resolved the conflicts with main, is there anything else I can do to help get this merged?

[Josh-Cena]

It's all good from me. Depends on when @slorber can give his review.

[Phiph]

Really looking forward to first party support for mermaid in docusarus! Great job!

[andrewnicols]

Is this likely to make 2.0? I dont' see a milestone against it but it otherwise looks ready to go.

[Josh-Cena]

No—we won't add any more features in 2.0 (which should be released in less than two weeks). Would probably be in 2.x, though.

[jpadams]

We'd love to use this feature on the Dagger docs site. 💯

[pottekkat]

🚀 Looking forward to using this on Apache APISIX.

[allanpope]

Any idea when this will be released?

[slorber]

Note I keep this PR in mind to review asap, but I'll be on holiday soon so unfortunately, it will have to wait a bit.

It shouldn't be a blocker to you: it's already possible to use Mermaid in Docusaurus with a Remark plugin

[allanpope]

No worries, enjoy your break

[AlmogBaku]

LGTM

[slorber]

Just updated the PR

---

Some other little issues I noticed: the svgs are not constrained in size and may lead to weird rendering. Particularly on mobile we really want to avoid having a horizontal scrollbar

There's also some unexpected spacing between diagrams:

Seen on https://deploy-preview-7490--docusaurus-2.netlify.app/tests/pages/diagrams

(was also the case before my update)

There are also some unexpected console logs 🤪

edit: oh apparently my upgrade fixed the logs 🤪

---

And we have the dependency review complaining

yarn.lock » [email protected] – d3-color vulnerable to ReDoS (high severity)

https://github.com/advisories/GHSA-36jr-mh4h-2g58

Not a blocker

https://github.com/mermaid-js/mermaid/issues/1969

[slorber]

will complete the PR and merge it asap 👍

[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 (https://github.com/facebook/docusaurus/pull/7490#discussion_r990243339) and https://github.com/facebook/docusaurus/issues/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 https://github.com/mermaid-js/mermaid/issues/3650#issuecomment-1279165405).

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 🎉