mermaid: refactor config to use mermaid_config.js include, only r…

…equire `mermaid.version` in `_config.yml` (mmistakes#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 mmistakes#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 mmistakes#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 @@
+{}

_layouts/default.html

@@ -215,7 +215,11 @@ <h2 class="text-delta">Table of contents</h2>
     {% 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