Pull in latest mermaid version while allowing custom versions (#1410)

layouts/partials/scripts.html

@@ -1,15 +1,10 @@
 {{ $needKaTeX  := or .Site.Params.katex.enable .Params.math .Params.chem -}}
 {{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}}
-{{ $needmermaid := .Site.Params.mermaid.enable -}}
 {{ if ge hugo.Version "0.93.0" -}}
-    {{ with .Site.Params.mermaid }}
-        {{ $needmermaid = true }}
-    {{ end }}
   {{ $needKaTeX = or $needKaTeX (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
   {{ $needmhchem = or $needmhchem (.Page.Store.Get "hasmhchem") -}}
-  {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}}
 {{ else -}}
-  {{ if or $needKaTeX $needmhchem $needmermaid -}}
+  {{ if or $needKaTeX $needmhchem -}}
     {{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version  }}
   {{ end -}}
 {{ end -}}
@@ -65,7 +60,6 @@
 {{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}}
 {{ $jsBase := resources.Get "js/base.js" -}}
 {{ $jsSearch := resources.Get "js/search.js" | resources.ExecuteAsTemplate "js/search.js" .Site.Home -}}
-{{ $jsMermaid := resources.Get "js/mermaid.js" | resources.ExecuteAsTemplate "js/mermaid.js" . -}}
 {{ $jsMarkmap := resources.Get "js/markmap.js" | resources.ExecuteAsTemplate "js/markmap.js" . -}}
 {{ $jsPlantuml := resources.Get "js/plantuml.js" | resources.ExecuteAsTemplate "js/plantuml.js" . -}}
 {{ $jsDrawio := resources.Get "js/drawio.js" | resources.ExecuteAsTemplate "js/drawio.js" . -}}
@@ -75,9 +69,8 @@
 
 {{ $jsArray := slice $jsBs $jsBase $jsSearch $jsPlantuml $jsMarkmap $jsDrawio -}}
 
-{{ if $needmermaid -}}
-{{ $jsArray = $jsArray | append $jsMermaid -}}
-<script src="https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.min.js" integrity="sha512-ku2nmBrzAXY5YwohzTqLYH1/lvyMrpTVxgQKrvTabd/b/uesqltLORdmpVapYv6QhZVCLUX6wkvFaKOAY4xpUA==" crossorigin="anonymous"></script>
+{{ if .Page.Store.Get "hasmermaid" -}}
+{{- partial "scripts/mermaid.html" . -}}
 {{ end -}}
 
 {{ $js := $jsArray | resources.Concat "js/main.js" -}}

assets/js/mermaid.js → layouts/partials/scripts/mermaid.html

@@ -1,25 +1,26 @@
-(function($) {
-    var needMermaid = false;
+{{ $version := .Site.Params.mermaid.version | default "latest" -}}
 
-{{ if ge hugo.Version "0.93.0" -}}
-    if ($('.mermaid').length > 0) {
-        needMermaid = true;
-    };
+{{ $cdnurl := printf "https://cdn.jsdelivr.net/npm/mermaid@%s/dist/mermaid.esm.min.mjs" $version -}}
+{{ with resources.GetRemote $cdnurl -}}
+  {{ with .Err -}}
+    {{ errorf "Could not retrieve mermaid script from CDN. Reason: %s." . -}}
+  {{ end -}}
 {{ else -}}
-    $('.language-mermaid').parent().replaceWith(function() {
-        needMermaid = true;
-        return $('<pre class="mermaid">').text($(this).text());
-    });
+  {{ errorf "Invalid Mermaid version %s, could not retrieve this version from CDN." $version -}}
 {{ end -}}
 
-    if (!needMermaid)  {
+<script type="module" async>
+import mermaid from "{{ $cdnurl }}";
+
+(function($) {
+    if ($('.mermaid').length == 0)  {
         mermaid.initialize({startOnLoad: false});
         return;
     }
 
     var params = {{ .Site.Params.mermaid | jsonify | safeJS }};
 
-    // site params are stored with lowercase keys; lookup correct casing
+    // Site params are stored with lowercase keys; lookup correct casing
     // from Mermaid default config.
     var norm = function(defaultConfig, params) {
         var result = {};
@@ -35,7 +36,9 @@
         }
         return result;
     };
+
     var settings = norm(mermaid.mermaidAPI.defaultConfig, params);
     settings.startOnLoad = true;
     mermaid.initialize(settings);
 })(jQuery);
+</script>

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

@@ -342,48 +342,64 @@ With Mermaid support enabled in Docsy, you can include the text definition of a
 
 The great advantage of this is anyone who can edit the page can now edit the diagram - no more hunting for the original tools and version to make a new edit.
 
-For example, the following defines a simple flowchart:
+For example, the following defines a sequence diagram:
 
 ````
 ```mermaid
-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]
+sequenceDiagram
+    autonumber
+    Docsy user->>Discussion board: Ask question
+    Discussion board->>Community member: read question
+    loop Different strategies
+    Community member->>Test instance: Investigate issue raised
+    end
+    Note right of Community member: After hours of investigation:
+    Test instance-->>Community member: Come up with solution
+    Community member-->>Discussion board: Propose solution
+    Discussion board-->>Docsy user: check proposed solution
+    Docsy user->>Discussion board: Mark question as resolved
+    Docsy user->>Docsy user: Being happy
 ```
 ````
 
-Automatically renders to:
+which is automatically rendered to:
 
 ```mermaid
-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]
+sequenceDiagram
+    autonumber
+    Docsy user->>Discussion board: Ask question
+    Discussion board->>Community member: read question
+    loop Different strategies
+    Community member->>Test instance: Investigate issue raised
+    end
+    Note right of Community member: After hours of investigation:
+    Test instance-->>Community member: Come up with solution
+    Community member-->>Discussion board: Propose solution
+    Discussion board-->>Docsy user: check proposed solution
+    Docsy user->>Discussion board: Mark question as resolved
+    Docsy user->>Docsy user: Being happy
 ```
 
-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.
+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 `hugo.toml`/`hugo.yaml`/`hugo.json`:
+By default, docsy pulls in the latest officially released version of Mermaid at build time. If that doesn't fit your needs, you can specify the wanted mermaid version inside your configuration file `hugo.toml`/`hugo.yaml`/`hugo.json`:
 
 {{< tabpane >}}
-{{< tab header="Hugo version <= 0.92 only:" disabled=true />}}
+{{< tab header="Configuration file:" disabled=true />}}
 {{< tab header="hugo.toml" lang="toml" >}}
 [params.mermaid]
-enable = true
+version = "10.8.0"
 {{< /tab >}}
 {{< tab header="hugo.yaml" lang="yaml" >}}
 params:
   mermaid:
-    enable: true
+    version: 10.8.0
 {{< /tab >}}
 {{< tab header="hugo.json" lang="json" >}}
 {
   "params": {
     "mermaid": {
-      "enable": true
+      "version": "10.8.0"
     }
   }
 }
@@ -424,7 +440,7 @@ params:
 
 See the [Mermaid documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) for a list of defaults that can be overridden.
 
-Settings can also be overridden on a per-diagram basis by making use of the `%%init%%` header at the start of the diagram definition.  See the [Mermaid theming documentation](https://mermaid-js.github.io/mermaid/#/theming?id=themes-at-the-local-or-current-level).
+Settings can also be overridden on a per-diagram basis by making use of a [frontmatter config](http://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables) block at the start of the diagram definition.
 
 ## UML Diagrams with PlantUML