From 9ff62494a79675094f99a761daad72853ef7fb70 Mon Sep 17 00:00:00 2001 From: Gareth Watts Date: Mon, 21 Sep 2020 10:57:27 -0500 Subject: [PATCH 1/3] Add support for Mermaid diagrams --- assets/scss/_code.scss | 4 ++ layouts/partials/scripts.html | 39 +++++++++++++++ userguide/config.toml | 4 ++ .../en/docs/Adding content/lookandfeel.md | 49 +++++++++++++++++++ 4 files changed, 96 insertions(+) diff --git a/assets/scss/_code.scss b/assets/scss/_code.scss index 7f2193a887..7a51eadbbc 100644 --- a/assets/scss/_code.scss +++ b/assets/scss/_code.scss @@ -47,4 +47,8 @@ border: 0; } } + + pre.mermaid { + background-color: inherit; + } } diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html index 9a308eb761..15ffb6846c 100644 --- a/layouts/partials/scripts.html +++ b/layouts/partials/scripts.html @@ -18,4 +18,43 @@ {{ end }} + +{{ with .Site.Params.mermaid }} +{{ if .enable }} + + + +{{ end }} +{{ end }} {{ partial "hooks/body-end.html" . }} diff --git a/userguide/config.toml b/userguide/config.toml index e5942a3dd3..82eeb508e6 100644 --- a/userguide/config.toml +++ b/userguide/config.toml @@ -199,3 +199,7 @@ enable = false # url = "https://example.org/mail" # icon = "fa fa-envelope" # desc = "Discuss development issues around the project" + +[params.mermaid] +enable = true +theme = "default" diff --git a/userguide/content/en/docs/Adding content/lookandfeel.md b/userguide/content/en/docs/Adding content/lookandfeel.md index ce94413250..f7e5f54c18 100644 --- a/userguide/content/en/docs/Adding content/lookandfeel.md +++ b/userguide/content/en/docs/Adding content/lookandfeel.md @@ -140,6 +140,55 @@ If the included Prism configuration is not sufficient for your requirements, and * Copy the Javascript file to `static/js/prism.js` * Copy the CSS file to `static/css/prism.css` +## Diagrams with Mermaid + +[Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering simple text definitions to useful diagrams in the browser. It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts. + +With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser, as soon as the page loads. + +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: + +```` +```mermaid +graph LR + Start --> Need{"Do I need diagrams"} + Need -- No --> Off["Set params.mermaid.enable = false"] + Need -- Yes --> HaveFun["Great! Enjoy!"] +``` +```` + +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!"] + +``` + +To enable/disable Mermaid, update `config.toml`: + +```toml +[params.mermaid] +enable = true +``` + +You can also update settings for Mermaid, such as themes, padding, etc: + +```toml +[params.mermaid] +enable = true +theme = "neutral" + +[params.mermaid.flowchart] +diagramPadding = 6 +``` + +See the [Mermaid documentation](https://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults) for a list of defaults that can be overriden. + ## Customizing templates ### Add code to head or before body end From 02a1f1cd1f76e404703d92052ec65cc592f209e5 Mon Sep 17 00:00:00 2001 From: Gareth Watts Date: Tue, 22 Sep 2020 21:32:28 -0500 Subject: [PATCH 2/3] Mermaid updates * Scale diagrams to fit instead of displaying a horizontal scroll bar * Don't display diagram source before rendering * Document diagram level configuration override option --- assets/scss/_code.scss | 1 + layouts/partials/scripts.html | 19 +++++++++++++++++-- .../en/docs/Adding content/lookandfeel.md | 2 ++ 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/assets/scss/_code.scss b/assets/scss/_code.scss index 7a51eadbbc..d491beeb45 100644 --- a/assets/scss/_code.scss +++ b/assets/scss/_code.scss @@ -50,5 +50,6 @@ pre.mermaid { background-color: inherit; + font-size: 0; } } diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html index 15ffb6846c..ca06e73f25 100644 --- a/layouts/partials/scripts.html +++ b/layouts/partials/scripts.html @@ -27,10 +27,14 @@ (function() { var needMermaid = false; $('.language-mermaid').parent().replaceWith(function() { - needsMermaid = true; + needMermaid = true; return $('
').text($(this).text());
     });
-    if (!needsMermaid)  return;
+
+    if (!needMermaid)  {
+        mermaid.initialize({startOnLoad: false});
+        return;
+    }
 
     var params = {{ . | jsonify | safeJS }};
 
@@ -50,6 +54,17 @@
         }
         return result;
     };
+    // Mermaid 8.8.0 doesn't yet expose this in defaultConfig; next release will.
+    // See https://github.com/mermaid-js/mermaid/issues/1490
+    mermaid.mermaidAPI.defaultConfig.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.flowchart.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.sequence.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.gantt.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.journey.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.git.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.state.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.er.useMaxWidth = true;
+
     var settings = norm(mermaid.mermaidAPI.defaultConfig, params);
     settings.startOnLoad = true;
     mermaid.initialize(settings);
diff --git a/userguide/content/en/docs/Adding content/lookandfeel.md b/userguide/content/en/docs/Adding content/lookandfeel.md
index f7e5f54c18..34ed2c1ff1 100644
--- a/userguide/content/en/docs/Adding content/lookandfeel.md	
+++ b/userguide/content/en/docs/Adding content/lookandfeel.md	
@@ -189,6 +189,8 @@ diagramPadding = 6
 
 See the [Mermaid documentation](https://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults) for a list of defaults that can be overriden.
 
+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/getting-started/theming.html#themes-at-the-local-or-current-level).
+
 ## Customizing templates
 
 ### Add code to head or before body end

From 74eda59264be2c519568b2fe63bffca2c22d5dcf Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Mon, 28 Sep 2020 17:34:23 +0100
Subject: [PATCH 3/3] Update lookandfeel.md

---
 userguide/content/en/docs/Adding content/lookandfeel.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/userguide/content/en/docs/Adding content/lookandfeel.md b/userguide/content/en/docs/Adding content/lookandfeel.md
index 34ed2c1ff1..12fa6cca01 100644
--- a/userguide/content/en/docs/Adding content/lookandfeel.md	
+++ b/userguide/content/en/docs/Adding content/lookandfeel.md	
@@ -144,9 +144,9 @@ If the included Prism configuration is not sufficient for your requirements, and
 
 [Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering simple text definitions to useful diagrams in the browser.  It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts.
 
-With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser, as soon as the page loads.
+With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser as soon as the page loads.
 
-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.
+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: