Offline site without internet access / question + proposal

[fccagou]

Hello all

My last work to use mermaid in my personal mkdocs site makes me creating a PR without issue and for an exiting solution.
All is my bad because I red the doc to quickly, I made assumptions on how it should work...

Francis's reply on my PR makes me take a pause to think about what happens 🤔

1. My need was making offline site so getting all assets locally with my site. The way to do this is clearly defined in Specifying the javascript. In getting started documentation, there is a link but I didn't understand the link was useful for the purpose of an offline site.

2. I don't well know JS "bazar" and I didn't understand I can use the xxxx.min.js file instead of module as defined in doc's example.

3. After reading the doc correctly, I do the good configuration and it works fine \o/ ... for mermaid only... /o\

4. Moreover, even if the site is configured to use local mermaid.min.js, it still not working because mkdocs hard links highlight.js to cdn.
   To make it working, I have to,

   • create docs/assets/js directory
   • download mermaid and highlightsjs needed files
   • made a custom_dir/ to redefine link to locals highligth.js files in mail.html template

That's why I some help here

• Is this the good way or did I miss something ?
• If not, I can propose to update the doc for this purpose and a PR to mkdocs to allow local highlights. What do you think ?

In any case, all those mistakes allowed me to learn about JS, mermaid, mkdocs and (to much?) hard links to internet/cdn.

Thanks a lot

[fralau]

Thanks. To better understand what's going on, I would need to see the content of the config file (mkdocs.yml) concerning mkdocs-mermaid2, and the directory plan you adopted.

[fccagou]

Hello.

Actually

To make it working, the mkdocs.yaml contains common configuration and the js files are in docs/assets/js/ (mermaid.min.js and highlight.js) ...

#...
theme:
  name: mkdocs
  highlightjs: true
  custom_dir: custom_theme/mkdocs/

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

#...

... and the defined custom_dir contains the main template used to redefine highlight url <script src="{{ base_url }}/assets/js/highlight.min.js"></script>

custom_theme/mkdocs/
└── main.html

Status

1. custom_dir is needed for highlight.js because the url is hardcoded in mkdocs
2. If I want multiple sites using the same code and configuration, that means I have to copy the mermaid.min.js file (then highlight.fs) in each projects. This could make updates complicated because each site must be individually upgraded.
3. For me, js code is not a document but formatting tools so should not be in doc's directory

Idea

That's why my first idea was to provides the the js code in theme using custom_dir as a all-in-one package

• actually needed to redefine the highlight.js url
• to deploy all js code in theme that can be clone from the same source to all sites
• to put js code out of docs directory

custom_theme/mkdocs/
├── js
│    ├── mermaid.min.js
│    └── highlight.js
└── main.html

Proposal

Makes mkdocs-mermaid2-plugin looking for mermaid.js in current location + in the theme defined in custom_dir. ( cf PR #94)

[fccagou]

After a new research in mkdocs issues, It seems the custom_dir is commonly used to provides offline materials as explain in mkdocs issue 2171

[fralau]

I believe this conflicts with the fundamental structure of concepts in MkDocs. There is a primary distinction between a theme and a plugin, and this has an impact on how projects, documentation and teams are organized.

The reference definition of custom_dir is "a directory containing a custom theme".

If a plugin was introducing information in an area reserved for themes, that could introduce confusion in the minds and create unwanted interdependencies. Metaphorically, that would be "unconstitutional" because it violates the "separation of powers".