Merge pull request #2167 from aws-lumberyard-dev/willihay/mermaid-setup

Add support for Mermaid.js diagram tool in blogs and docs

config.toml

@@ -18,6 +18,7 @@ unsafe = true
 
 [params]
 font_awesome_version = "5.12.0"
+mermaid_version = ["9.2.2", "sha384-W/RuUCsZGwf4MwkS0K4JdFzoA0RgiA6foiYzRo68rW5DNPfq+5Dr0uGKY1zecHEA"]
 description = "Open 3D Engine (O3DE) is a modular, open source, cross-platform 3D engine built to power anything from AAA games to cinema-quality 3D worlds to high-fidelity simulations. No fees or commercial obligations. Apache 2.0-licensed. Managed by The Linux Foundation."
 favicon = "favicon.ico"
 repositoryUrl = "https://github.com/o3de/o3de.org"

content/smoketest.md

@@ -557,4 +557,60 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \
 
 **Example Output**
 
-$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+
+## Embedding Mermaid diagrams
+
+**Example UML Class Diagram**
+
+````
+```mermaid
+classDiagram
+    Animal <|-- Duck
+    Animal <|-- Fish
+    Animal <|-- Zebra
+    Animal : +int age
+    Animal : +String gender
+    Animal: +isMammal()
+    Animal: +mate()
+    class Duck{
+        +String beakColor
+        +swim()
+        +quack()
+    }
+    class Fish{
+        -int sizeInFeet
+        -canEat()
+    }
+    class Zebra{
+        +bool is_wild
+        +run()
+    }
+```
+````
+
+**Example Output**
+
+```mermaid
+classDiagram
+    Animal <|-- Duck
+    Animal <|-- Fish
+    Animal <|-- Zebra
+    Animal : +int age
+    Animal : +String gender
+    Animal: +isMammal()
+    Animal: +mate()
+    class Duck{
+        +String beakColor
+        +swim()
+        +quack()
+    }
+    class Fish{
+        -int sizeInFeet
+        -canEat()
+    }
+    class Zebra{
+        +bool is_wild
+        +run()
+    }
+```

layouts/_default/_markup/render-codeblock-mermaid.html

@@ -0,0 +1,4 @@
+<div class="mermaid">
+    {{- .Inner | safeHTML }}
+</div>
+{{ .Page.Store.Set "hasMermaid" true }}

layouts/_default/single.html

@@ -1,4 +1,5 @@
 {{ define "main" }}
+{{ $mermaidVersion := site.Params.mermaid_version }}
   <div class="container">
       <section class="row">
         <section class="col col-8">
@@ -8,6 +9,13 @@ <h1 class="title">{{ .Page.Title | markdownify }}</h1>
             {{ . }}
           </div>
           {{ end }}
+
+          {{ if .Page.Store.Get "hasMermaid" }}
+            <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ index $mermaidVersion 0 }}/dist/mermaid.min.js" integrity="{{ index $mermaidVersion 1 }}" crossorigin="anonymous"></script>
+            <script>
+              mermaid.initialize({ startOnLoad: true });
+            </script>
+          {{ end }}
         </section>
       </section>
     </div>

layouts/partials/blog/content.html

@@ -1,10 +1,19 @@
+{{ $mermaidVersion := site.Params.mermaid_version }}
 {{ $posts := where site.RegularPages "Section" "blog" }}
 <div class="container">
   <div class="columns">
     <div class="col col-12">
       <div class="">
         {{ .Content }}
       </div>
+
+      {{ if .Page.Store.Get "hasMermaid" }}
+        <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ index $mermaidVersion 0 }}/dist/mermaid.min.js" integrity="{{ index $mermaidVersion 1 }}" crossorigin="anonymous"></script>
+        <script>
+            mermaid.initialize({ startOnLoad: true });
+        </script>
+      {{ end }}
+
       <a class="btn btn-primary back-to-blog" href="/blog">
         <span>
           Back to blogs

layouts/partials/docs/content.html

@@ -1,5 +1,13 @@
+{{ $mermaidVersion := site.Params.mermaid_version }}
 {{ with .Content }}
 <div class="content">
   {{ . }}
 </div>
 {{ end }}
+
+{{ if .Page.Store.Get "hasMermaid" }}
+<script src="https://cdn.jsdelivr.net/npm/mermaid@{{ index $mermaidVersion 0 }}/dist/mermaid.min.js" integrity="{{ index $mermaidVersion 1 }}" crossorigin="anonymous"></script>
+<script>
+  mermaid.initialize({ startOnLoad: true });
+</script>
+{{ end }}