Closed frank-lenormand closed 10 months ago
Thank you for your contribution! This is very appreciated.
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:
Thanks.
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:
If mermaid
library can be configured to be stored in the same repo as documentation's code, that would fit no. 3 :).
Thanks, it totally makes sense.
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
Thanks. I have re-read documentation and the following trick worked for me:
docs/javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs
extra_javascript:
- javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs
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?
I would rather keep versioning information.
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.
Sure. As soon as the library is improved, I will improve my configuration.
Good. I have created an experimental version 1.0.9 on Github.
Example:
plugins:
- search
- mermaid2:
javascript: js/mermaid.min.js
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.
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).
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?
Unfortunately, it does not work in my use case.
My steps:
site
)mermaid.esm.min.mjs
https://github.com/fralau/mkdocs-mermaid2-plugin/tree/master/mermaid2
to my local venv environment (overwritten)extra_javascript
in my mkdocs.yaml
fileplugins:
- mermaid2:
javascript: javascripts/mermaid/10.1.0/dist/mermaid.esm.min.mjs
mkdocs build --verbose
sites/index.html
) using IntelliJ IDEA & Google ChromeGoogle 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?
@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.
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?
Yes, see here, e.g.:
https://cdn.jsdelivr.net/npm/mermaid@10.2.0/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.
Looks good, thanks for the work!
If it works on your side, could you please release a new version and close this issue?
It works for me with the file from the following location: https://cdn.jsdelivr.net/npm/mermaid@10.4.0/dist/mermaid.min.js
Thanks.
🚀 Published in release 1.1.0 on Pypi.
Hi,
The documentation states that including a local version of
mermaid
is a hack, but I would like to be able to do it for offline support.I’m assuming that
mermaid
itself doesn’t depend on online resources, but in that case, I’d work on getting them offline as well.It would also be great if the plugin didn’t silently drop libraries that do not contain
\bmermaid\b
in their base name. But I assume this is a requirement of the below point.Instead of relying on
extra_javascript
(which would include the library in all pages, as far as I know), maybe an extra option to themermaid2
plugin section inplugins
could work?Thanks!