Offline/SSR rendering of Mermaid diagrams

[matevz]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

The mermaid plugin in the recent Docusaurus 2.2.0 release works on the client-side only. Add support for rendering mermaid graphs offline while building the static site.

Has this been requested on Canny?

No response

Motivation

In some cases (e.g. scraping the website, disabled javascript in the client's browser, avoidance of repositioning/flickering esp. on mobile phones) it would be useful to render the diagrams into .svg resources while building the static site already and then only serve static images.

API design

No response

Have you tried building it?

No response

Self-service

• [ ] I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

Hey

Unfortunately, this is a known limitation that I'm aware of, and it's not easy to solve this in an efficient way.

• https://github.com/facebook/docusaurus/pull/7490#issuecomment-1279170541
• https://github.com/mermaid-js/mermaid/issues/3650#issuecomment-1279165405

---

Note even GitHub doesn't support Mermaid without JS:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Displays without JS:

[Airkro]

For now, mermaid SSR needs to run a browser instance or use online services.

Many remark plugins can do that: https://www.npmjs.com/search?ranking=maintenance&q=remark%20mermaid

You can integrate one of them into the docusaurus.

In my case, I using Kroki / https://github.com/nice-move/remark-kroki to do that.

[slorber]

Users can already add remark plugins if they want this.

I'd rather let user use all these things in userland and provide feedback on what works best - before introducing anything relying on a headless browser in core.

[matevz]

FYI how we're currently attacking this problem is having diagrams in separate .mmd files and then use mmdc to generate the corresponding .svg files. Those are then referenced in the markdown as ordinary images. Our approach works, but involves some additional checks in CI so that the .svg files are always up-to-date with the original .mmd. Also, since the images are static svg's, switching to dark theme requires separate .svg files.

[slorber]

package worth exploring: https://github.com/remcohaszing/rehype-mermaid (conversation https://twitter.com/sebastienlorber/status/1717913171992690980)