💡 Feature Request - Allow using CDN hosted version of mermaid.js

[maiksprenger]

Implementation PR

No response

Reference Issues

No response

Summary

We've added the latest mermaid.js with django-mermaid to my work's product docs project - thank you again for making this so easy!

In its AppConfig.ready, django-mermaid tries to download the specified version of mermaid.js if a custom version was specified. This is downloaded into django-mermaids static folder.

This will not work for all deployment scenarios. By the time AppConfig.ready has run, collectstatic could already have been executed. In scenarios where static files are pushed to S3, we might never find the downloaded mermaid.js. In our corporate environment, the site packages directory is write-protected, so this approach doesn't work at all.

There are a few ways this could be improved (e.g. making the download directory customizable, downloading and using media files instead). But I am not a fan of side effects in AppConfig.ready, and I think there is an even simpler approach: be able to opt-in to using the CDN-hosted version of mermaid.js instead of via staticfiles.

Adding this feature presumably also would've addressed #8.

I am afraid I got moved to a different project, so likely won't be able to make a pull request this time.

Basic Example

A get_mermaid_uri could replace this, and we already have the logic to build the CDN URL.

Drawbacks

None, apart from the added complexity of one more settings variable.

Unresolved questions

No response

[ArtyomVancyan]

@maiksprenger, I see the issue. I can implement a new boolean constant for using CDN directly (without downloading on application start), but it actually has a drawback. When using CSP, you might have issues loading the script. Anyway, I like the idea of using the direct CDN in the Jinja template. Will work on it on the weekend and will keep you notified.

[maiksprenger]

@ArtyomVancyan Really happy to hear you think this is a good idea!

I agree about the CSP issues, but think that's to be expected. Either you go the easy way and use an externally hosted version, or you have to figure out to ship the javascript from your servers.

Adding a boolean to control both the downloading and which URL to use is probably the sensible approach. If you want to go fancy and address the CSP issue at the same time, you could let users define their own URL function (like KEY_FUNCTION). If it's not set, you keep the current behavior of downloading and serving via staticfiles. And if it's set, users can either define a function that returns the CDN URL, or they can define a function that returns a URL from servers under their control, addressing the CSP issue. But I'm not sure if that's too complex 🤷

I'm happy to review a PR if that helps you.

[ArtyomVancyan]

@maiksprenger, thanks again for the idea! I have implemented and published a new version that supports this direct CDN URL feature. So, you can upgrade and set the MERMAID_USE_CDN = True in your settings.py and test it out.

[maiksprenger]

@ArtyomVancyan That's amazing, thank you for adding that! I'll prep a PR to get us using that, and will let you know how it went.