Embed mermaid JS Code as base64 data-stream

[frehberg]

Imrprovement:

Currently the Mermaid JS package is downloaded using URLs in Script-tags. These may point to local files or remote web-locations. Modern browsers prevent loading scripts form local files (CORS), so file based Rust-Docs are not able to render the mermaid diagrams.

Downloading mermaid from remote web-soources may be time consuming, rendering of diagrams may be postponed by multiple seconds.

Instead of refering to external locations the mermaid JS might be embedded as base64 string the following way

<script type="text/javascript" src="data:text/javascript;base64,BASE64_STRING"></script>

The mermaid package v10.2.3 is shipped as single file of byte size 2.9MB. The estimated base64 will increase siize by 30%, around 3.8MB

The aquamarine macro might embed the mermaid JS package.

As the Rust-Docs process is creating an single Html file per Rust "mod", each of these file would require the mermaid code to be embedded.

Sadly, the Rust macro is not "told" the source file and line or mod-depth of the current Span/TokenStream. Therefor it is not possible to tell if a macro has been invoked within this Rust "mod" before. So each macro would perform the same

It might be an idea to define two macros, first one to embed the package into a Rust Doc Html file (per Rust "mod"), second macro might just rendert the diagram.

For example:

#[cfg_attr(doc, aquamarine::aquamarine, embed)]

PROS:

• Faster loading, eliminate additional download of mermaid package
• No CORS, so browsers would render mermaid diagrams also when using file based Rust-Docs

CONS:

• Increasing each Html Rust Doc file by 3MB per diagram
• Increasing total Rust-Doc byte size by N x 3MB (where N is the number of diagrams within a crate)

[mersinvald]

Cons seem to outweight the pros for me, especially considering that the browser caching already solves the re-fetching problem well.

That needs to be tested, but I suspect that even with once-per-mod embedding, second and the following reloads of the page will be slower compared to the browser-cached mermaid.js.

[Qix-]

Modern browsers prevent loading scripts form local files (CORS), so file based Rust-Docs are not able to render the mermaid diagrams.

This isn't right. Only from file:// URIs when the existing page's scheme is not itself file://. Otherwise local documentation / asset loading wouldn't work. Relative paths with <script> still work just the same, too.