Auto activation of mermaid diagrams (via use of hugo render hook)

[stephanlachnit]

This switches Mermaid to use hugo's Markdown
render hooks instead of manipulating the string at runtime, which
should improve page loading performance by a tiny bit.

Similar to #987, can probably also be done for PlantUML and MarkMap.

This could potentially improved even further by setting {{ .Page.Store.Set "hasXXX" true }} in render-codeblock-XXX.html and adjusting scripts.html so that these corresponding JavaScript functions are loaded only on that page instead of bundling them to a global script. This would also lift the requirements to set params.XXX.enable = true. However since this is a more complicated endeavor and I'm not really familiar with js, I did not attempt to do this.

[deining]

This could potentially improved even further by setting {{ .Page.Store.Set "hasXXX" true }} in render-codeblock-XXX.html and adjusting scripts.html so that these corresponding JavaScript functions are loaded only on that page instead of bundling them to a global script. This would also lift the requirements to set params.XXX.enable = true.

I like the idea. However render hooks for code blocks are availabe as of hugo version 0.93 only, so implementing this feature would increase the minimum hugo version needed when authoring mermaid or UML diagrams.

[stephanlachnit]

I like the idea. However render hooks for code blocks are availabe as of hugo version 0.93 only, so implementing this feature would increase the minimum hugo version needed when authoring mermaid or UML diagrams.

Yes, indeed. v0.93 was released in February, so it is not that new considering that hugo is a "just download a single binary to use" program. I don't know what the release plans are, but maybe it can be merged just after v0.5.0 so that there is a reasonable time span in between the release after that and hugo v0.93.

[deining]

As said, I like the idea to use render hooks here. However render hooks for code blocks are availabe as of hugo version 0.93 only. I reflected about your submitted code changes and found a way to implement this feature without the need to increase the required hugo version to 0.93 when authoring mermaid diagrams. See my code review for details.

This could potentially improved even further by setting {{ .Page.Store.Set "hasXXX" true }} in render-codeblock-XXX.html and adjusting scripts.html so that these corresponding JavaScript functions are loaded only on that page instead of bundling them to a global script. This would also lift the requirements to set params.XXX.enable = true.

This is very true. See my PR #1286 for details on how to implement this useful feature. As proposed, I too would prefer to load the scripts inside the render hook rather than activating them on a global basis as we do now. For the sake of compatibility I would keep the activation in the site config file, though.

However since this is a more complicated endeavor and I'm not really familiar with js, I did not attempt to do this.

That's fine. I can take over that part once the issues in my code review were addressed and this PR was merged.

[deining]

I had a second thought on this and came up with an alternative solution that I would like to share:

• we leave the code renderblock as proposed by this PR
• inside mermaid.js, we use conditional output depending on the hugo version used:

(function($) {
    var needMermaid = false;
{{ if ge hugo.Version "0.93.0" -}}
    if ($('.mermaid').length > 0) {
        needMermaid = true;
    };
{{ else -}}
    $('.language-mermaid').parent().replaceWith(function() {
        needMermaid = true;
        return $('<pre class="mermaid">').text($(this).text());
    });
{{ end -}}

This way, we can keep the performance gain introduced with this PR while maintaining compatibility with hugo versions <0.93.3.

WDYT?

[stephanlachnit]

WDYT?

Sounds like a good idea, feel free to push to this branch

[deining]

`mermaid´ code blocks now work all hugo versions. For hugo versions <=0.92, you still need to manually activate mermaid.

[deining]

This PR is ready for review and subsequent merging now:

• with hugo versions >=0.93.0, the use of a mermaid code block inside your page automatically enabled mermaid diagrams.
• with hugo versions <0.93.0, mermaid diagrams still work. You still must activate mermaid support in your config file, though.

The documentation was adapted in order to reflect the changes introduced with this patch.

Advantages introduced with this PR:

• more user friendly use of mermaid diagrams, no manual activation needed (with hugo version >= 0.93.0).
• mermaid scripts are only loaded for pages that actually make use of mermaid diagrams.
• mermaid was updated to latest version 9.1.7.

@geriom @chalin: Can you please review and report back if you like these changes? If so, we could take them over for other diagram types (plantuml, markmap) as well.

[chalin]

Overall, LGTM. I haven't thoroughly reviewed the code, but I trust y'all.

Consider adding a note to the changelog so that folks using Mermaid will know that they can simplify their config if they're using Hugo 0.93+.

@LisaFC - did you want to review the UG changes?

[deining]

Consider adding a note to the changelog so that folks using Mermaid will know that they can simplify their config if they're using Hugo 0.93+.

Done.

@LisaFC - can you review the UG changes, please? Thanks in advance.

[LisaFC]

User guide changes LGTM!

[chalin]

Thanks all!