From 6907f0697781130d5a804c7e5a3fe7e7eb467313 Mon Sep 17 00:00:00 2001
From: nascosto <2653283+nascosto@users.noreply.github.com>
Date: Tue, 12 Jul 2022 16:16:18 -0600
Subject: [PATCH] Add mermaid support (#857)
Closes #825
Co-authored-by: Matt Wang <matt@matthewwang.me>
---
_config.yml | 21 ++++++++++++++
_includes/head.html | 5 ++++
_includes/mermaid_init.html | 58 +++++++++++++++++++++++++++++++++++++
_layouts/default.html | 3 ++
_sass/code.scss | 7 +++++
docs/configuration.md | 25 ++++++++++++++++
docs/ui-components/code.md | 18 ++++++++++++
7 files changed, 137 insertions(+)
create mode 100644 _includes/mermaid_init.html
diff --git a/_config.yml b/_config.yml
index 65c2280b..b0f93102 100644
--- a/_config.yml
+++ b/_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
diff --git a/_includes/head.html b/_includes/head.html
index d26a42ae..1b4f7b7f 100644
--- a/_includes/head.html
+++ b/_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">
diff --git a/_includes/mermaid_init.html b/_includes/mermaid_init.html
new file mode 100644
index 00000000..327dfdf6
--- /dev/null
+++ b/_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>
diff --git a/_layouts/default.html b/_layouts/default.html
index efaa1e53..63e23b0c 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -214,4 +214,7 @@ layout: table_wrappers
{% endif %}
</div>
</body>
+{% if site.mermaid_enabled != false %}
+ {%- include mermaid_init.html -%}
+{% endif %}
</html>
diff --git a/_sass/code.scss b/_sass/code.scss
index a479c702..6ad832f4 100644
--- a/_sass/code.scss
+++ b/_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 %}
diff --git a/docs/configuration.md b/docs/configuration.md
index e1ba5445..cb0b7fd3 100644
--- a/docs/configuration.md
+++ b/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
diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md
index b8136a35..0ea9b71f 100644
--- a/docs/ui-components/code.md
+++ b/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 %}
--
GitLab