From cac318152014b2042b90818825647454659eeeef Mon Sep 17 00:00:00 2001 From: Stephan Lachnit Date: Tue, 26 Apr 2022 17:01:07 +0200 Subject: [PATCH 1/3] performance: use hugo render hook for Mermaid This switches Mermaid to use hugo's Markdown render hooks [1] instead of manipulating the string at runtime, which should improve performance by a bit. [1]: https://gohugo.io/templates/render-hooks/#render-hooks-for-code-blocks Signed-off-by: Stephan Lachnit --- assets/js/mermaid.js | 5 ++--- layouts/_default/_markup/render-codeblock-mermaid.html | 3 +++ 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 layouts/_default/_markup/render-codeblock-mermaid.html diff --git a/assets/js/mermaid.js b/assets/js/mermaid.js index 821e567872..9580739917 100644 --- a/assets/js/mermaid.js +++ b/assets/js/mermaid.js @@ -2,10 +2,9 @@ {{ if .enable }} (function($) { var needMermaid = false; - $('.language-mermaid').parent().replaceWith(function() { + if ($('.mermaid').length > 0) { needMermaid = true; - return $('
').text($(this).text());
-    });
+    };
 
     if (!needMermaid)  {
         mermaid.initialize({startOnLoad: false});
diff --git a/layouts/_default/_markup/render-codeblock-mermaid.html b/layouts/_default/_markup/render-codeblock-mermaid.html
new file mode 100644
index 0000000000..85166b1de9
--- /dev/null
+++ b/layouts/_default/_markup/render-codeblock-mermaid.html
@@ -0,0 +1,3 @@
+

+  {{- .Inner | safeHTML }}
+


From 7789b40b869273d74dab905859b99e5016a48eb0 Mon Sep 17 00:00:00 2001
From: Andreas Deininger 
Date: Thu, 20 Oct 2022 18:12:03 +0200
Subject: [PATCH 2/3] mermaid diagrams: automatic activation (with hugo
 >=0.93.0)

---
 assets/js/mermaid.js                            | 17 ++++++++++++++---
 .../_markup/render-codeblock-mermaid.html       |  2 ++
 layouts/partials/scripts.html                   |  9 +++++++--
 userguide/config.yaml                           |  3 ---
 4 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/assets/js/mermaid.js b/assets/js/mermaid.js
index 9580739917..90d162ebab 100644
--- a/assets/js/mermaid.js
+++ b/assets/js/mermaid.js
@@ -1,10 +1,22 @@
-{{ with .Site.Params.mermaid }}
-{{ if .enable }}
+{{ $needmermaid := or .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 $('
').text($(this).text());
+    });
+{{ end -}}
 
     if (!needMermaid)  {
         mermaid.initialize({startOnLoad: false});
@@ -34,4 +46,3 @@
     mermaid.initialize(settings);
 })(jQuery);
 {{ end }}
-{{ end }}
diff --git a/layouts/_default/_markup/render-codeblock-mermaid.html b/layouts/_default/_markup/render-codeblock-mermaid.html
index 85166b1de9..0b8d7c01bd 100644
--- a/layouts/_default/_markup/render-codeblock-mermaid.html
+++ b/layouts/_default/_markup/render-codeblock-mermaid.html
@@ -1,3 +1,5 @@
+{{ .Page.Store.Set "hasmermaid" true -}}
+
 

   {{- .Inner | safeHTML }}
 

diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html
index 9cc401bbbb..b47d8ba7c4 100644
--- a/layouts/partials/scripts.html
+++ b/layouts/partials/scripts.html
@@ -1,5 +1,10 @@
-{{ if .Site.Params.mermaid.enable -}}
-  
+{{ $needmermaid := or .Site.Params.mermaid.enable -}}
+{{ if ge hugo.Version "0.93.0" -}}
+    {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
+{{ end }}
+
+{{ if $needmermaid -}}
+  
 {{ end -}}
 
 {{ if .Site.Params.markmap.enable -}}
diff --git a/userguide/config.yaml b/userguide/config.yaml
index fb6add464a..23aa0b87b4 100644
--- a/userguide/config.yaml
+++ b/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

From 4f4731a121925e4e140f1c44190854ee6a1bda0d Mon Sep 17 00:00:00 2001
From: Andreas Deininger 
Date: Fri, 21 Oct 2022 14:13:40 +0200
Subject: [PATCH 3/3] Auto-activation of mermaid diagrams: adapt documentation

---
 CHANGELOG.md                                  |  4 ++
 assets/js/mermaid.js                          |  2 +-
 layouts/partials/scripts.html                 |  2 +-
 .../diagrams-and-formulae/index.md            | 55 +++++--------------
 .../installation-prerequisites.md             |  4 +-
 5 files changed, 23 insertions(+), 44 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72d1a03a2f..53fb5d01cf 100644
--- a/CHANGELOG.md
+++ b/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**:
 
diff --git a/assets/js/mermaid.js b/assets/js/mermaid.js
index 90d162ebab..e361b096d4 100644
--- a/assets/js/mermaid.js
+++ b/assets/js/mermaid.js
@@ -1,4 +1,4 @@
-{{ $needmermaid := or .Site.Params.mermaid.enable -}}
+{{ $needmermaid := .Site.Params.mermaid.enable -}}
 {{ if ge hugo.Version "0.93.0" -}}
     {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
 {{ end }}
diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html
index b47d8ba7c4..a4a9cc028e 100644
--- a/layouts/partials/scripts.html
+++ b/layouts/partials/scripts.html
@@ -1,4 +1,4 @@
-{{ $needmermaid := or .Site.Params.mermaid.enable -}}
+{{ $needmermaid := .Site.Params.mermaid.enable -}}
 {{ if ge hugo.Version "0.93.0" -}}
     {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
 {{ end }}
diff --git a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md b/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md
index 94d81b5c5d..db9ee56220 100644
--- a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md
+++ b/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
diff --git a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md b/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md
index 5f52a35a88..4513c3a887 100644
--- a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md
+++ b/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.