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>
As discussed in #1174, this adds a documentation section to UI Components > Code > Mermaid that describes the usage of mermaid with AsciiDoc.
Regarding the comment on asciidoctor-diagram in my edits, I cannot stress enough how much pain this is to set up (this was the first thing I tried before switching to JTD's client-side mermaid support). It basically pre-renders mermaid diagrams in a headless chromium browser. This requires manual configuration of Puppeteer, along with additional config for Jekyll to keep the images the extension creates. And when you managed to get the image on your site, it looks horrible. This is why I wrote „not recommended“.
Hi there!
Thank you for the great theme! I am a happy user and was delighted to see that mermaid support has landed.
In some cases the usage of jsDelivr might not be possible for technical or compliance reasons.
This commit adds a second way to include the mermaid lib by specifying a path in the mermaid config. This way a local version of the lib can be used.
It should be fully backwards compatible, not requiring any action by users that already include the lib from the CDN.
I already added some documentation, but I am also happy to extend this, if this change is generally well-received.
Cheers,
Christian
In #1058, I noted:
> Tangentially related work:
> ...
> - better annotate new features (motivated by writing these docs)
> - we should add "New" to new features :)
> - we should note when a feature was introduced (I think this is a core part of most software documentation)
> - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge
>
This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later.
This PR is me doing that. I:
- have added a headings-level "New" label to every new heading introduced since `v0.3`
- added, when possible, inline YAML comments when new configuration options have been introduced
I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation.
I may have also missed any new features, so some double-checking would be helpful!
This PR has a bit of scope creep! This PR now:
- changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857
- changes the behaviour of mermaid configuration
- instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js`
- the include is loaded directly into the contents of `mermaid_initialize`
- by default, it is an empty object (i.e. `{}`), triggering the defaults
- updates docs
- adds an example to the markdown kitchen sink
It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward!
