steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-12 21:03:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

Fix mermaid v10, bundle all mermaid code in component (#1190)

Browse Source 
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>
This commit is contained in:
Matt Wang
2023-04-12 12:05:51 -07:00
committed by GitHub
parent 786678a6a2
commit 5e5e2438d2
4 changed files with 58 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/ui-components/code.md
View File

@@ -150,14 +150,24 @@ graph TD;
### Using a local mermaid library
In order to use a local version of the mermaid library instead of one provided by jsDelivr, you can specify a `path` key in the mermaid configuration instead of a `version` key.
To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g.
```yaml
mermaid:
# To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
path: "/assets/js/mermaid.min.js"
version: "10.1.0"
# for (v10+)
path: "/assets/js/mermaid.esm.min.mjs"
# for (<v10):
# path: "/assets/js/mermaid.min.js"
# Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated
# `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
```
For mermaid versions `>=10`, this file is imported directly as an ESM module (rather than as a plain `<script>` tag); users should use the `mermaid.esm.min.mjs` file. In contrast, for mermaid versions `<10`, this file is loaded as a script tag; it should be a standalone CJS file (i.e. `mermaid.min.js`).
{: .warning }
Mermaid versions `10.0` - `10.1` (and possibly, future releases) still encode relative imports in `mermaid.esm.min.mjs`. Local users must copy *all* of the contents of the `dist` folder to the specified path (preserving the relative location of the files). Just the Docs is actively monitoring mermaid releases; an upstream fix is planned.
### Using mermaid with AsciiDoc
Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.