mermaid: refactor config to use mermaid_config.js include, only require mermaid.version in _config.yml (#909)

This PR has a bit of scope creep! This PR now:

- changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857
- changes the behaviour of mermaid configuration
    - instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js`
    - the include is loaded directly into the contents of `mermaid_initialize`
    - by default, it is an empty object (i.e. `{}`), triggering the defaults
- updates docs
- adds an example to the markdown kitchen sink  

It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward!

_config.yml

@@ -51,26 +51,14 @@ search:
   # Supports true or false (default)
   button: false
 
-# Enable or disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/)
-# Supports true or false (default)
-mermaid_enabled: false
-mermaid:
-  # Version of mermaid library
-  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
-  version: "9.1.3"
-  # Configured theme of mermaid diagrams
-  # Pick an avaiable theme from https://mermaid-js.github.io/mermaid/#/theming
-  theme: "default"
-  # Additional configuration available matching pattern as defined in https://mermaid-js.github.io/mermaid/#/./Setup.
-  # For example,
-  # logLevel: 'fatal',
-  # sequence:
-  #   diagramMarginX: 50
-  #   actorMargin: 50
-  # gantt:
-  #   barGap: 4
-  #   topPadding: 50
-
+# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
+# uncomment the `mermaid` and `version` keys below
+# mermaid:
+#   # Version of mermaid library
+#   # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+#   version: "9.1.3"
+#   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+#   # See also docs/ui-components/code
 
 # Enable or disable heading anchors
 heading_anchors: true

_includes/head.html

@@ -30,7 +30,7 @@
     <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
 
-  {% if site.mermaid_enabled != false %}
+  {% if site.mermaid %}
     <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
   {% endif %}
 

_includes/mermaid_config.js

@@ -0,0 +1 @@
+{}

_includes/mermaid_init.html

@@ -1,58 +0,0 @@
-<script>
-  var config = {
-    theme: '{{ site.mermaid.theme | default: "default" }}',
-    logLevel: '{{ site.mermaid.logLevel | default: "fatal" }}',
-    securityLevel: '{{ site.mermaid.securityLevel | default: "strict" }}',
-    startOnLoad: {{ site.mermaid.startOnLoad | default: true }},
-    arrowMarkerAbsolute: {{ site.mermaid.arrowMarkerAbsolute | default: false }},
-
-    er: {
-      diagramPadding: {{ site.mermaid.er.diagramPadding | default: 20 }},
-      layoutDirection: '{{ site.mermaid.er.layoutDirection | default: "TB" }}',
-      minEntityWidth: {{ site.mermaid.er.minEntityWidth | default: 100 }},
-      minEntityHeight: {{ site.mermaid.er.minEntityHeight | default: 75 }},
-      entityPadding: {{ site.mermaid.er.entityPadding | default: 15 }},
-      stroke: '{{ site.mermaid.er.stroke | default: "gray" }}',
-      fill: '{{ site.mermaid.er.fill | default: "honeydew" }}',
-      fontSize: {{ site.mermaid.er.fontSize | default: 12 }},
-      useMaxWidth: {{ site.mermaid.er.useMaxWidth | default: true }},
-    },	
-    flowchart:{
-      diagramPadding: {{ site.mermaid.flowchart.diagramPadding | default: 8 }},
-      htmlLabels: {{ site.mermaid.flowchart.htmlLabels | default: true }},
-      curve: '{{ site.mermaid.flowchart.curve | default: "basis" }}',
-    },
-    sequence: {
-      diagramMarginX: {{ site.mermaid.sequence.diagramMarginX | default: 50 }},
-      diagramMarginY: {{ site.mermaid.sequence.diagramMarginY | default: 10 }},
-      actorMargin: {{ site.mermaid.sequence.actorMargin | default: 50 }},
-      width: {{ site.mermaid.sequence.width | default: 150 }},
-      height: {{ site.mermaid.sequence.height | default: 65 }},
-      boxMargin: {{ site.mermaid.sequence.boxMargin | default: 10 }},
-      boxTextMargin: {{ site.mermaid.sequence.boxTextMargin | default: 5 }},
-      noteMargin: {{ site.mermaid.sequence.noteMargin | default: 10 }},
-      messageMargin: {{ site.mermaid.sequence.messageMargin | default: 35 }},
-      messageAlign: '{{ site.mermaid.sequence.messageAlign | default: "center" }}',
-      mirrorActors: {{ site.mermaid.sequence.mirrorActors | default: true }},
-      bottomMarginAdj: {{ site.mermaid.sequence.bottomMarginAdj | default: 1 }},
-      useMaxWidth: {{ site.mermaid.sequence.useMaxWidth | default: true }},
-      rightAngles: {{ site.mermaid.sequence.rightAngles | default: false }},
-      showSequenceNumbers: {{ site.mermaid.sequence.showSequenceNumbers | default: false }},
-    },
-    gantt: {
-      titleTopMargin: {{ site.mermaid.gantt.titleTopMargin | default: 25 }},
-      barHeight: {{ site.mermaid.gantt.barHeight | default: 20 }},
-      barGap: {{ site.mermaid.gantt.barGap | default: 4 }},
-      topPadding: {{ site.mermaid.gantt.topPadding | default: 50 }},
-      leftPadding: {{ site.mermaid.gantt.leftPadding | default: 75 }},
-      fontSize: {{ site.mermaid.gantt.fontSize | default: 11 }},
-      gridLineStartPadding: {{ site.mermaid.gantt.gridLineStartPadding | default: 35 }},
-      fontFamily: '{{ site.mermaid.gantt.fontFamily | default: "\'Open Sans\', sans-serif" }}',
-      numberSectionStyles: {{ site.mermaid.gantt.numberSectionStyles | default: 4 }},
-      axisFormat: '{{ site.mermaid.gantt.axisFormat | default: "%Y-%m-%d" }}',
-      topAxis: {{ site.mermaid.gantt.topAxis | default: false }},
-    },
-  };
-  mermaid.initialize(config);
-  window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
-</script>

_layouts/default.html

@@ -215,7 +215,11 @@ layout: table_wrappers
     {% endif %}
   </div>
 </body>
-{% if site.mermaid_enabled != false %}
-  {%- include mermaid_init.html -%}
+{% if site.mermaid %}
+  <script>
+    var config = {% include mermaid_config.js %};
+    mermaid.initialize(config);
+    window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
+  </script>
 {% endif %}
 </html>

docs/configuration.md

@@ -60,30 +60,18 @@ search:
 ```
 
 ## Mermaid Diagrams
-See [Code]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more information.
+
+The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`:
 
 ```yaml
-# Enable or disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/)
-# Supports true or false (default)
-mermaid_enabled: false
 mermaid:
   # Version of mermaid library
   # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
   version: "9.1.3"
-  # Configured theme of mermaid diagrams
-  # Pick an avaiable theme from https://mermaid-js.github.io/mermaid/#/theming
-  theme: "default"
-  # Additional configuration available matching pattern as defined in https://mermaid-js.github.io/mermaid/#/./Setup.
-  # For example,
-  # logLevel: 'fatal',
-  # sequence:
-  #   diagramMarginX: 50
-  #   actorMargin: 50
-  # gantt:
-  #   barGap: 4
-  #   topPadding: 50
 ```
 
+See [the Code documentation]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
+
 ## Aux links
 
 ```yaml
@@ -186,7 +174,7 @@ A paragraph...
 ```
 
 [^dark]:
-    If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. 
+    If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
 
 The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file:
 
@@ -261,6 +249,7 @@ just_the_docs:
       # Supports true or false (default)
       # search_exclude: true
 ```
+
 The navigation for all your normal pages (if any) is displayed before those in collections.
 
 You can reference multiple collections.
@@ -282,6 +271,7 @@ just_the_docs:
     tutorials:
       name: Tutorials
 ```
+
 When *all* your pages are in a single collection, its name is not displayed.
 
 The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page.

docs/index-test.md

@@ -71,7 +71,7 @@ end
 
 [This is a very long link which wraps and therefore doesn't overflow
 even when it comes at the beginning](.) of the line.
-  
+
 - [This is a very long link which wraps and therefore doesn't overflow the line
   when used first in an item ](.) in a list.
 
@@ -298,6 +298,19 @@ class conditions(object):
 Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
 ```
 
+### Mermaid Diagrams
+
+The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`.
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+
 ```
 The final element.
 ```

docs/ui-components/code.md

@@ -91,9 +91,36 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 ## Mermaid diagram code blocks
 
-[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding `mermaid_enabled: true` to your \_config.yml.
+[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
 
-The markdown for a simple flowchart example might look like the following:
+The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
+
+```yaml
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  version: "9.1.3"
+```
+
+Additional configuration options are loaded through `_includes/mermaid_config.js`. By default, the contents of the file are the empty object:
+
+```js
+// _includes/mermaid_config.js
+{}
+```
+
+This loads the default settings.
+
+The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
+
+```js
+// _includes/mermaid_config.js
+{
+  theme: "forest"
+}
+```
+
+Once mermaid is installed, it can be used in markdown files. The markdown for a simple flowchart example might look like the following:
 
 {% highlight markdown %}
 ```mermaid