Inline mermaid.js support

I'd like to have support for inline diagrams (like mermaid.js) in rustdoc markdowns.

1 Like

I previously brought this up on Zulip. The desire is to have some way to pre-render it, which doesn't really exist without spawning a full browser (puppeteer).

https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Mermaid.20diagram.20support/near/287767979

1 Like

Took a quick look: I think it's pretty plausible to add pre-render (including under node/deno) support to mermaid.js without a complete rewrite.

The idea is that you tell it to render into a JSDOM node and serialize that at the end, then the only bits missing is the DOM layout. Since Dagre is doing the actual layout, forking or patching that to call dedicated non-browser text layout code would be the only major bit needed there.

I think getting something like rustybuzz running in WASM should be pretty doable, which would solve that. It doesn't even matter if it's a little off in measuring, you can set textLength on an SVG <text> to get predictable layout for exactly that reason.

The real time is most likely going to be chasing down spread out assumptions in mermaid or Dagre that they're running in a browser: at least D3 is explicitly JSDOM friendly for testing.

This isn't as nice an option as just porting mermaid to Rust of course :yum:

Only DOM should be needed if the output format is SVG, the browser would take care of the final render step.

1 Like

That is better than puppeteer, but doesn't help with running rustdoc on a system that doesn't have nodejs or deno installed already.

Yeah, if you're just porting mermaid then this all looks fine: just a lot of work. Possibly worth it: I'm sure GitHub and friends would appreciate the ability to server-side render too, but even disregarding the sizable work involved, it doesn't look like there's exhaustive documentation or test suites, so keeping the implementations in sync would be an issue.