mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-20 10:02:23 -06:00
5e5e2438d2
This PR does two things: 1. fixes using mermaid version `>= 10` from the CDN, by importing the ESM module instead 2. moves script loading code from `head.html` to the mermaid include I've also added some light documentation to clarify how using mermaid with local paths should work (users should specify a version, and they should only use fully-minified bundles with no local references). The nice thing about this approach is that it's a breaking change for nobody, and only adds functionality (v10 support). Eventually, we should remove support for mermaid <10, which should make this much easier! Closes #1206. ## Context In v10, Mermaid has implemented a few (admittedly, very frustrating to deal with) breaking changes: 1. they've removed CJS support, which is fine, *but* 2. that means that the `dist` they publish to JSDelivr now has a **different URL**: for versions `10.0.0` - `10.0.2`, **they do not have a minified bundle -- you have to load the ESM version with relative imports** 3. and, separately the `init` function has been deprecated 2 is really the issue, and so I've had to go into the code to now load mermaid by ESM by default when the user is on mermaid > v10. I've tested this with: - CDN version < 10 (v9) - CDN version 10 - local path with version < 10 (v9) - local path with version 10 (new: also loaded as an ESM module) Separately, I chose to put all the mermaid stuff in one include because: - I think @pdmosses requested something like this - it's a bit confusing that some mermaid code is *not* in the include, and this makes modular components ... more modular - from a developer perspective, it's more clear what's happening with mermaid - mermaid is not render-blocking, so it shouldn't be in the `head` anyways --------- Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
46 lines
1.5 KiB
HTML
46 lines
1.5 KiB
HTML
{% comment %}
|
|
The complexity of this file comes from a breaking change in Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work earlier?).
|
|
|
|
So, we check whether the user's Mermaid version is >= 10; if not, we fall back to the previous init syntax.
|
|
|
|
If a user is using a custom mermaid file and doesn't specify a version, we default to the < v10 behaviour. Users who use version v10 or above should specify this in the version key.
|
|
{% endcomment %}
|
|
|
|
{% if site.mermaid.version %}
|
|
{% assign mermaid_major_version = site.mermaid.version | split: "." | first | plus: 0 %}
|
|
{% else %}
|
|
{% assign mermaid_major_version = 9 %}
|
|
{% endif %}
|
|
|
|
{% if mermaid_major_version > 9 %}
|
|
|
|
<script type="module">
|
|
{% if site.mermaid.path %}
|
|
import mermaid from '{{ site.mermaid.path | relative_url }}';
|
|
{% else %}
|
|
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.esm.min.mjs';
|
|
{% endif %}
|
|
|
|
var config = {% include mermaid_config.js %};
|
|
mermaid.initialize(config);
|
|
mermaid.run({
|
|
querySelector: '.language-mermaid',
|
|
});
|
|
</script>
|
|
|
|
{% else %}
|
|
|
|
{% if site.mermaid.path %}
|
|
<script src="{{ site.mermaid.path | relative_url }}"></script>
|
|
{% else %}
|
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
|
|
{% endif %}
|
|
|
|
<script>
|
|
var config = {% include mermaid_config.js %};
|
|
mermaid.initialize(config);
|
|
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
|
|
</script>
|
|
|
|
{% endif %}
|