use mkdocs-mermaid2-plugin in airgapped systems

[belfagor93]

Hello,

I'm trying to use mkdocs-mermaid2-plugin in an air-gapped system and I get errors because the plugin is trying to download from the internet https://unpkg.com/mermaid@8.8.0/dist/mermaid.min.js.

I tried to save the content of https://unpkg.com/mermaid@8.8.0/dist/mermaid.min.js in a local mermaid.min.js file but unfortunately, if I pass it in this way:

extra_javascript:
  - /full/path/mermaid.min.js

the website will be published but without the proper image display:

$ mkdocs build
INFO     -  MERMAID2  - Initialization arguments: {}
INFO     -  MERMAID2  - Explicit mermaid javascript library:
   ./mermaid.min.js
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /builds/nico.oppido/calculator/site
INFO     -  MERMAID2  - Page 'Calculation Docs': found 1 diagrams (with <pre><code='[language-]mermaid'>), converting to <div>...
INFO     -  MERMAID2  - Page 'Calculation Docs': found 1 diagrams, adding scripts
INFO     -  Documentation built in 0.43 seconds

I'm using python:3.10-buster with these requirements:

certifi==2022.12.7
charset-normalizer==2.1.1
click==8.1.3
colorama==0.4.6
ghp-import==2.1.0
griffe==0.24.1
idna==3.4
Jinja2==3.1.2
Markdown==3.3.7
MarkupSafe==2.1.1
mergedeep==1.3.4
mkdocs==1.4.2
mkdocs-autorefs==0.4.1
mkdocs-material==8.5.11
mkdocs-material-extensions==1.1.1
mkdocs-mermaid2-plugin==0.6.0
mkdocstrings==0.19.0
mkdocstrings-python==0.8.2
packaging==22.0
Pygments==2.13.0
pymdown-extensions==9.9
python-dateutil==2.8.2
PyYAML==6.0
pyyaml_env_tag==0.1
requests==2.28.1
six==1.16.0
urllib3==1.26.13
watchdog==2.2.0

Can someone help me with the air-gapped scenario?

[github-actions[bot]]

Thank you for your contribution! This is very appreciated.

[fralau]

Apparently mkdocs can't find your downloaded library. It seems that you must use a relative path to the docs directory:

See:

• https://www.mkdocs.org/user-guide/configuration/#extra_javascript
• https://squidfunk.github.io/mkdocs-material/customization/#additional-javascript (if you are using mkdocs material)

The doc does not say whether absolute paths are allowed. If you really want to, I would either ask the question to the mkdocs team (or else try to figure out what the code is doing).

[belfagor93]

@fralau

Thanks for the answer. Unfortunately I just tried to move the file into docs/ or into docs/javascript and give in the mkdocs.yml the relative path but again, no error, no problems:

extra_javascript:
  - docs/javascript/mermaid.min.js

INFO     -  MERMAID2  - Initialization arguments: {}
INFO     -  MERMAID2  - Explicit mermaid javascript library:
   docs/mermaid.min.js

but the website still have the wrong render for the diagrams.

[fralau]

Remove the reference to docs/?

[belfagor93]

putting the file under docs/ folder only and removing the reference from the mkdocs.yml is working!

do you think that is something that I should add in the readme and open a PR?

[fralau]

Well, if you omit the reference in the mkdocs.yml file, it inserts the https call to the javascript library on its own! If you look at the generated code html/css, it's probably not what you want.

In the repository, look at the test directory; there are examples of calls to local javascript files in the mkdocs.yaml file.