Optionally Disable Mermaid Feature?

[codrcodz]

When using Lighthouse to enhance SEO and performance on a website built with Insiders and the privacy plugin enabled (to avoid sending users to download external assets), the mermaid js file is always shipped to users and flagged as unused js code when diagrams are not in use. It is also over 2MB in size and slows down initial load times on mobile devices significantly.

It would be really nice if a new feature was added that let you explicitly toggle off mermaid integration if you are an Insiders user and are not using it anywhere. All that bulky JavaScript would no longer impact site performance if you aren't using it. Thoughts?

[squidfunk]

Normally, Mermaid.js is only downloaded if it is actually used, i.e., if a Mermaid.js diagram was discovered on the page you're viewing. For example, look at our getting started guide, that doesn't include a diagram – Mermaid.js is not downloaded. I've just verified that the privacy plugin does not change this behavior.

This does not hold if you added Mermaid.js to extra_javascript, because now, it is always downloaded. Are you doing that? If not, and it still happens to you, it's very much not intended. Please create a new issue with a minimal reproduction, we're happy to fix it.

Also make sure to upgrade to the latest version of Insiders when testing.

[codrcodz]

Thanks for the speedy reply! I'll dig in a little more and get back to you with my findings, including a minimal reproduction.

[31ch]

Hey @squidfunk , I'm currently trying to use MkDocs in an offline environment using the offline/privacy plugins. I see the behavior/issue mentioned above where mermaid.min.js gets downloaded although it's not used by any site.

Version of mkdocs: 1.5.3
Version of mkdocs-material: 9.5.15

Minimal MkDocs configuration:

site_name: My Docs
theme:
  name: material
  font: false
plugins:
  - offline
  - privacy

If I execute mkdocs build I see the following output:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/cyone/mkdocs/site
INFO    -  Downloading external file: https://unpkg.com/[email protected]/dist/mermaid.min.js
INFO    -  Downloading external file: https://unpkg.com/iframe-worker/shim
INFO    -  Documentation built in 1.38 seconds

If I switch assets_fetch to false I see that mermaid.min.js is referenced by assets/javascripts/bundle.bd412221c.min.js.

Maybe I'm doing something wrong with my configuration as you mentioned above you verified correct operation? Otherwise let me know if I should open a bug report.

[squidfunk]

Thanks for asking. You're referring to two different meanings of "downloaded". In my previous comment, it means that the browser downloaded Mermaid so it can render in the browser. You are referring to the privacy plugin downloading and bundling the script during build time, which is correct, as the privacy plugin can not know if at any point in the site Mermaid.js is used. However, it does not influence the user experience at all, since the browser will never download it, so there's just one file sitting in your site directory that you never use – IMHO it's not a big deal.

The privacy plugin could, theoretically, parse all Markdown and check if Mermaid.js is actually used, and then bundle it, but that would need much more resources and slower builds on every instance vs. one additional file.

[31ch]

Thanks for the very quick reply! Ok, now I got it. The issue we face is that the CI we are using to publish the MkDocs site does not have access to Internet. Therefore the privacy plugin is obviously not able to download the Mermaid.js.

Our current workaround is to execute MkDocs with the privacy plugin with internet access and add the files from the .cache folder to the offline environment. We actually currently just add those files to the Git repository which is ugly, but only includes the iframe-worker and Mermaid. As we are not using Mermaid it would have been great to somehow mark it as 'disabled' to avoid the 3MB javascript dependency.

So just as a potential use case for the original request of 'optionally disable mermaid' would be 'offline mkdocs builds' to reduce dependencies :-)

[squidfunk]

Ah, I see! You can exclude Mermaid from being downloaded using assets_exclude, which will instruct the privacy plugin to just keep the original link in the source:

plugins:
  - privacy:
      assets_exclude: 
        - unpkg.com/mermaid@*

Note that this setting is currently only available in Insiders, and thus reserved to our awesome sponsors. If you need anything else, let us know.

[31ch]

Ok, nice! Thanks again for your awesome support and keep up the good work :)