Customize mermaid module

[mirisbowring]

This MR relates #361

Changes:

1. If mermaid is not used at all in the user's repository, he is able to disable the module. This will reduce loading times and traffic since the mermaid.js will not be delivered.
2. The user is able to globally disable mermaid, but keep it enabled for specific pages (by using front matter configs).
3. The user is able to specify a URL for a custom mermaid version. This enables him to use any version (not just the delivered version of the theme).

[mirisbowring]

@matalo33 what do you think? :)

[matalo33]

@matalo33 what do you think? :)

@mirisbowring Sorry for not getting to this yet. I've been doing the 'easy' PRs and issues while on the road, I wanted to have a full read of your PR at a desk before merging.

[mirisbowring]

@matalo33
I don't want to be annoying, but is there any progress on this? :)

[matalo33]

Hi @mirisbowring! Not annoying at all, my apologies for taking so long. I gave this a quick test & found a small issue.

For the test I set disableMermaid = true in the exampleSite's config.toml and visited the mermaid page at http://localhost:1313/en/shortcodes/mermaid/. Also added in a debug which outputs to the console in chrome dev tools right above your

    <script>
        console.log("not $.Params.disableMermaid is {{ printf "%#v" (not $.Params.disableMermaid) }}")
        console.log("not $.Site.Params.disableMermaid is {{ printf "%#v" (not $.Site.Params.disableMermaid) }}")
    </script>
    {{ if (or (not .Params.disableMermaid) (not .Site.Params.disableMermaid)) }}
    ...

When disableMermaid is true in the site config but undefined in the page topmatter the condition is evaluated as true, and mermaid is loaded. Output from the above debug:

not $.Params.disableMermaid is true
not $.Site.Params.disableMermaid is false

This means that for someone to disable mermaid across their whole site they would need to set the disable flag in the site config.toml and in the topmatter of every page.

Is there a way for the site setting to become the sitewide setting unless overridden at the page level?

By the way, love the feature idea! It's a design we can copy to many of the other included libraries in the theme.

[mirisbowring]

@matalo33 I fixed the issues you mentioned.
I think that the check inside the partial would look a little bit cleaner if we would change the key from disable to enable but this would only confuse the user while configuring the theme because all the other options are using the disable style.

If the user globally disabled mermaid and did not configure the frontmatter for the current page, the mermaid module is not being included on the current page.

[mirisbowring]

@matalo33 any progress on this?

[matalo33]

Ok I think this is almost there. Just two thoughts / questions:

1. Why do you only load the CSS when using the local mermaid?
2. Could you rename the variable for the custom mermaid URL? Perhaps overrideMermaidURL is a bit clearer?

[mirisbowring]

Thanks for continuing on this PR.
Regarding the questions:

1. The latest versions of mermaid do not use the css anymore v8.8.0 vs v6.0.0 for example. The local version (when i developed this PR) was using the css, which why i included it. Since you merged Upgrade mermaid-js/mermaid @ 0918b97 (v8.8.0) #443 the forest.css and mermaid.css can be removed.
2. I will rename it to customMermaidURL

[mirisbowring]

@matalo33 I renamed the variable to customMermaidURL.

The CSS Files are no longer referenced and over 2 Years old (so i deleted them).

[matalo33]

This is awesome. Thanks very much 🎉

[McShelby]

The "alternate syntax" for mermaid (mermaid in code fences) was removed from the docs. Nevertheless, it's still working (only in Chrome, but this is a different topic- #410). So I can't see why it was removed. Is this now deprecated?

I always thought it's an elegant way to write mermaid graphs. Some others have had the same feeling Gitlab, Markdown Monster, markdown-it extension

[mirisbowring]

It is not depracted exactly. But it was not rendered on Edge, IE, Firefox and Safari. The docs should be generic until the issue is fixed.

[McShelby]

There is an issue when trying to detect mermaids URL

[McShelby]

As mentioned in the hugo documentation, this will not work, because the key needs to be lower case!

[chankeypathak]

Is this fixed? Just wondering whether I should patch this PR on my site or is it not stable yet?