Add mermaid support (#857)

Closes #825


Co-authored-by: Matt Wang <matt@matthewwang.me>

_config.yml

@@ -51,6 +51,27 @@ 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
+
+
 # Enable or disable heading anchors
 heading_anchors: true
 

_includes/head.html

@@ -29,6 +29,11 @@
   {% if site.search_enabled != false %}
     <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
+
+  {% if site.mermaid_enabled != false %}
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
+  {% endif %}
+
   <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">

_includes/mermaid_init.html

@@ -0,0 +1,58 @@
+<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

@@ -214,4 +214,7 @@ layout: table_wrappers
     {% endif %}
   </div>
 </body>
+{% if site.mermaid_enabled != false %}
+  {%- include mermaid_init.html -%}
+{% endif %}
 </html>

_sass/code.scss

@@ -139,4 +139,11 @@ figure.highlight {
   }
 }
 
+// Mermaid diagram code blocks should be left unstyled.
+code.language-mermaid {
+  padding: 0;
+  background-color: inherit;
+  border: 0;
+}
+
 // {% endraw %}

docs/configuration.md

@@ -59,6 +59,31 @@ search:
   button: false
 ```
 
+## Mermaid Diagrams
+See [Code]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more information.
+
+```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
+```
+
 ## Aux links
 
 ```yaml

docs/ui-components/code.md

@@ -86,3 +86,21 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 [Link button](http://example.com/){: .btn }
 ```
 {% endhighlight %}
+
+---
+
+## 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.
+
+The markdown for a simple flowchart example might look like the following:
+
+{% highlight markdown %}
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+{% endhighlight %}