Include local `mermaid` library for offline support

[frank-lenormand]

Include local `mermaid` library for offline support

[volphy]

In my current project/platform we are striving to achieve CI/CD workflow detached from public Internet.
In order to achieve it, we do the following:

1. store some 3rd party dependecies either in our controlled repository server (e.g., Nexus)
2. store some 3rd party dependencies in our controlled storage (e.g., AWS S3)
3. store some 3rd party dependencies in the same repository as documentation's code

If mermaid library can be configured to be stored in the same repo as documentation's code, that would fit no. 3 :).

[fralau]

Thanks, it totally makes sense.

[volphy]

Thanks. I have re-read documentation and the following trick worked for me:

• download specific version of mermaid JS to the following location: docs/javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs
• refer to it in my mkdocs.yaml configuration file:

extra_javascript:
  - javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs

[frank-lenormand]

Hi,

The issue is that the Mermaid library is fetched from the internet, I would like it to be versioned along the documentation (c.f. @volphy scenario #3).

Sources:

• https://github.com/fralau/mkdocs-mermaid2-plugin/blob/master/webdoc/docs/index.md?plain=1#L237-L239

  You may, however, specify your own call, with the use of the extra_javascript directive in the configuration file. This is considered as a hack, if the default procedure doesn't work.

• https://github.com/fralau/mkdocs-mermaid2-plugin/blob/master/mermaid2/plugin.py#L104

  if  libname(lib) == 'mermaid':
      return lib

[volphy]

I would rather keep versioning information.

[frank-lenormand]

As mentioned in the first message, using extra_javascript would include the library in all the pages, which is not desirable.

I would like the plugin to keep selectively inject the library, but from a local directory.

[volphy]

You are right. Using the following JavaScript file works:
https://github.com/fralau/mkdocs-mermaid2-plugin/blob/master/test/extra_javascript/docs/js/mermaid.min.js
👍

Is it possible to use any version of mermaid JS:
https://github.com/mermaid-js/mermaid/tree/v10.1.0
?

If yes, how can I do it?

[frank-lenormand]

Looks good, thanks for the work!

If it works on your side, could you please release a new version and close this issue?

[volphy]

It works for me with the file from the following location:
https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js

Thanks.

[fralau]

🚀 Published in release 1.1.0 on Pypi.

[github-actions]

Thank you for your contribution! This is very appreciated.

[fralau]

Thanks and I can see more or less the requirement but I would need more information.

Could you also tell me more about the exact problem you are facing with the current situation, and why an off-line load of the library would be the solution for you?

Could I also ask you to provide links for the following statements:

• "The documentation states that including a local version of mermaid is a hack"
• "The plugin didn’t silently drop libraries that do not contain \bmermaid\b in their base name. "

Thanks.

[fralau]

Excellent, and thanks for the additional info. Wouldn't it be better to remove the subdirectories?

extra_javascript:
  - javascripts/mermaid.esm.min.mjs

Unless you want to keep the various versions?

[volphy]

Sure. As soon as the library is improved, I will improve my configuration.

[fralau]

Good. I have created an experimental version 1.0.9 on Github.

Example:

plugins:
  - search
  - mermaid2:
      javascript: js/mermaid.min.js    

1. If the parameter javascript is present (either a URL or a local pathname, relative to the docs directory), then it is used, no questions asked.

2. Otherwise the plugin will look at the parameter version and look for the online version of the javascript library. In the presence of javascript this version parameter is ignored (I suppose you can use it for documentation).

3. If no argument is provided, it will use the MERMAID_LIB_VERSION specified in the plugin.

It is still possible to use the extra_javascript mechanism (which will bypass the above mechanism), but this it is now deprecated. It will detect any library with the string mermaid in the filename.

Note I tested the local version of the mermaid.min.js file, which is shipped with the package; you can find the test website under test\simple_local_lib. In theory it would also work with an .mjs, but I haven't tested that (and I wouldn't know how to do install it cleanly). I have also tested the other cases (see test\extra_javascript and test\simple).

Could I ask you to test this and give me your feedback?

[volphy]

Unfortunately, it does not work in my use case.

My steps:

1. removed previously generated HTML files (site)
2. removed all mermaid JS files apart from mermaid.esm.min.mjs
3. copied the latest files from https://github.com/fralau/mkdocs-mermaid2-plugin/tree/master/mermaid2 to my local venv environment (overwritten)
4. disabled extra_javascript in my mkdocs.yaml file
5. enabled new mkdocs-mermaid2-plugin feature:

plugins:
  - mermaid2:
      javascript: javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs

6. generated new HTML files: mkdocs build --verbose
7. viewed locally generated HTML files (sites/index.html) using IntelliJ IDEA & Google Chrome

Google Chrome Developer Tools reports the following error on all HTML pages with mermaid diagrams embedded:

Uncaught TypeError: Failed to resolve module specifier "javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs". Relative references must start with either "/", "./", or "../".

Could you test the new feature with MJS files?

[fralau]

@volphy As mentioned in my message, the recommendation is to use the traditional, all-in-one mermaid.min.js file, since it is still provided by the developers.

It is important to distinguish between the .js (traditional javascript script) and the .mjs file (entry point for the new type of ESM modules, since version 10).

if you use a .mjs file, from a package, you will need the whole hierarchy of directories that comes with it. Deleting the other files will wreck the library.

I have never tried to make the ESM library work with mkdocs-mermaid2, but it might be possible. If you have success with that, please let us know the steps.

[fralau]

Yes, see here, e.g.:

https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js

As long as you use a valid version number, it should work (it is not guaranteed that the earliest version of 10 contain that file). The best thing is to check for yourself.