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!

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