mgaitan/sphinxcontrib-mermaid

Bundle the JS dependency in the built HTML folder

nils-van-zuijlen opened this issue · 1 comments

nils-van-zuijlen commented

As experienced with the recent version hiccups, using a public CDN is not a reliable way to have dependencies loaded.

It is really annoying that old versions of a documentation became unreadable without a regeneration of an adjusted version of that doc.

It notably has the following drawbacks (non exhaustive list):

  • It leaks your IP to a third party, which requires explicit consent under the GDPR
  • The CDN may change its URL
  • The CDN may cease to exist
  • The CDN may change the files it serves, aka supply-chain attack
  • The CDN may be unreachable from some places in the world due to firewalls

Would it be possible to bundle all dependency files by default in the built package?

It could be done in a few ways:

Dynamically downloading the dependency at build time

This still has some issues about CDN availability, but they can be seen at build time, not a few years after the doc generation.

This is the route I would prefer.

Vendoring mermaid in this repo then copied over at build time

Not that great for maintenance here, as any mermaid release would require a new release here

mgaitan commented

@nils-van-zuijlen I agree pointing to a CDN could be problematic, For example a a change in the last Mernaid release broke a lot of documentations (and I needed to release the version 0.8.1 urgently)

However, it's already possible to rely on locals JS as the readme explain by setting

mermaid_version = ""

html_js_files = [
   'js/mermaid.js',
]

and put the file/s in _static/js/mermaid.js

If needed you can customize mermaid_init_js.

I'd accept if you want to send a PR poiting out more clearly this option (with its advantages) in readme/docs