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

…ogle#990)

CHANGELOG.md

@@ -13,6 +13,10 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
 **New**:
 
+- **Simplified use of mermaid diagrams**: when using a `mermaid` code block on
+  your page, mermaid is now automatically enabled (needs hugo version >= 0.93.0).
+  For existing sites build with hugo 0.93.0+, parameter `mermaid.enable`
+  can be removed from site config.
 
 **Breaking changes**:
 

assets/js/mermaid.js

@@ -1,11 +1,22 @@
-{{ with .Site.Params.mermaid }}
-{{ if .enable }}
+{{ $needmermaid := .Site.Params.mermaid.enable -}}
+{{ if ge hugo.Version "0.93.0" -}}
+    {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
+{{ end }}
+
+{{ if $needmermaid }}
 (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 -}}
 
     if (!needMermaid)  {
         mermaid.initialize({startOnLoad: false});
@@ -35,4 +46,3 @@
     mermaid.initialize(settings);
 })(jQuery);
 {{ end }}
-{{ end }}

layouts/_default/_markup/render-codeblock-mermaid.html

@@ -0,0 +1,5 @@
+{{ .Page.Store.Set "hasmermaid" true -}}
+
+<div class="mermaid">
+  {{- .Inner | safeHTML }}
+</div>

layouts/partials/scripts.html

@@ -1,5 +1,10 @@
-{{ if .Site.Params.mermaid.enable -}}
-  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js" integrity="sha512-E/owfVh8/U1xwhvIT4HSI064DRc1Eo/xf7AYax84rt9gVqA8tc/JNH/lvTl1tuw9PUHQIMGUtObkjYkgRjFqAA==" crossorigin="anonymous"></script>
+{{ $needmermaid := .Site.Params.mermaid.enable -}}
+{{ if ge hugo.Version "0.93.0" -}}
+    {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
+{{ end }}
+
+{{ if $needmermaid -}}
+  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js" integrity="sha512-1ypa9tdUrJAWv5g28Mb5x0zXaUuI4SBofKff88OGyk5D/oOd4x1IPxYHsx3K81bwBKt8NVUvGgw7TgNZ6PJX2A==" crossorigin="anonymous"></script>
 {{ end -}}
 
 {{ if .Site.Params.markmap.enable -}}

userguide/config.yaml

@@ -106,9 +106,6 @@ params:
         icon: fa-brands fa-github
         desc: Development takes place here!
 
-  mermaid:
-    enable: true
-    theme: default
   plantuml:
     enable: true
     theme: default

userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md

@@ -269,27 +269,30 @@ For example, the following defines a simple flowchart:
 
 ````
 ```mermaid
-graph LR
-  Start --> Need{"Do I need diagrams"}
-  Need -- No --> Off["Set params.mermaid.enable = false"]
-  Need -- Yes --> HaveFun["Great!  Enjoy!"]
+graph TD
+  Start --> Need{"Hugo version >= 0.93.0"}
+  Need -- No --> Off["Set params.mermaid.enable = true"]
+  Off --> Author
+  Need -- Yes --> Author[Insert mermaid codeblock]
 ```
 ````
 
 Automatically renders to:
 
 ```mermaid
-graph LR
-  Start --> Need{"Do I need diagrams"}
-  Need -- No --> Off["Set params.mermaid.enable = false"]
-  Need -- Yes --> HaveFun["Great!  Enjoy!"]
-
+graph TD
+  Start --> Need{"Hugo version >= 0.93.0"}
+  Need -- No --> Off["Set params.mermaid.enable = true"]
+  Off --> Author
+  Need -- Yes --> Author[Insert mermaid codeblock]
 ```
 
-To enable/disable Mermaid, update `config.toml`/`config.yaml`/`config.json`:
+With hugo version 0.93 or higher, support of Mermaid diagrams is automatically enabled as soon as you use a `mermaid` code block on your page.
+
+If you are using hugo version 0.92 or lower, you need to enable Mermaid manually by updating your `config.toml`/`config.yaml`/`config.json`:
 
 {{< tabpane persistLang=false >}}
-{{< tab header="Configuration file:" disabled=true />}}
+{{< tab header="Hugo version <= 0.92 only:" disabled=true />}}
 {{< tab header="config.toml" lang="toml" >}}
 [params.mermaid]
 enable = true
@@ -310,38 +313,12 @@ params:
 {{< /tab >}}
 {{< /tabpane >}}
 
-You also need to disable the `guessSyntax` from markup highlighting in `config.toml`/`config.yaml`/`config.json` for Mermaid to work:
-
-{{< tabpane persistLang=false >}}
-{{< tab header="Configuration file:" disabled=true />}}
-{{< tab header="config.toml" lang="toml" >}}
-[markup]
-  [markup.highlight]
-      guessSyntax = false
-{{< /tab >}}
-{{< tab header="config.yaml" lang="yaml" >}}
-markup:
-  highlight:
-    guessSyntax: false
-{{< /tab >}}
-{{< tab header="config.json" lang="json" >}}
-{
-  "markup": {
-    "highlight": {
-      "guessSyntax": false
-    }
-  }
-}
-{{< /tab >}}
-{{< /tabpane >}}
-
-You can also update settings for Mermaid, such as themes, padding, etc:
+If needed, you can define custom settings for your diagrams, such as themes, padding in your `config.toml`/`config.yaml`/`config.json`.
 
 {{< tabpane persistLang=false >}}
 {{< tab header="Configuration file:" disabled=true />}}
 {{< tab header="config.toml" lang="toml" >}}
 [params.mermaid]
-enable = true
 theme = "neutral"
 
 [params.mermaid.flowchart]
@@ -350,7 +327,6 @@ diagramPadding = 6
 {{< tab header="config.yaml" lang="yaml" >}}
 params:
   mermaid:
-    enable: true
     theme: neutral
     flowchart:
       diagramPadding: 6
@@ -359,7 +335,6 @@ params:
 {
   "params": {
     "mermaid": {
-      "enable": true,
       "theme": "neutral",
       "flowchart": {
         "diagramPadding": 6

userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md

@@ -70,7 +70,7 @@ Hugo's commands for module management require that the Go programming language i
 
 ```bash
 $ go version
-go version go1.18.4 windows/amd64
+go version go1.19.2 windows/amd64
 ```
 
 Ensure that you are using version 1.12 or higher.
@@ -84,7 +84,7 @@ Hugo's commands for module management require that the `git` client is installed
 
 ```bash
 git version
-git version 2.37.1.windows.1
+git version 2.38.1.windows.1
 ```
 
 If no `git` client is installed on your system yet, go to the [Git website](https://git-scm.com/), download the installer for your system architecture and execute it. Afterwards, check for a successful installation.