diff --git a/exampleSite/content/basics/configuration/_index.en.md b/exampleSite/content/basics/configuration/_index.en.md
index 54b90749bb..1ed2a78d6f 100644
--- a/exampleSite/content/basics/configuration/_index.en.md
+++ b/exampleSite/content/basics/configuration/_index.en.md
@@ -42,6 +42,8 @@ Note that some of these parameters are explained in details in other sections of
   disableMermaid = false
   # Specifies the remote location of the mermaid js
   customMermaidURL = "https://unpkg.com/mermaid@8.8.0/dist/mermaid.min.js"
+  # Initialization parameter for mermaid, see mermaid documentation
+  mermaidInitialize = "{ \"startOnLoad\": true }"
   # Hide Next and Previous page buttons normally displayed full height beside content
   disableNextPrev = true
   # Order sections in menu by "weight" or "title". Default to "weight"
@@ -70,7 +72,7 @@ Relearn theme uses the last improvement available in hugo version 20+ to generat
 
 ## Mermaid
 
-The mermaid configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one.
+The mermaid configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one. See [mermaid]({{< relref "shortcodes/mermaid.md" >}}) for additional documentation.
 
 > Example:
 >
diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md
index d169452dfd..c801bb2605 100644
--- a/exampleSite/content/shortcodes/mermaid.en.md
+++ b/exampleSite/content/shortcodes/mermaid.en.md
@@ -7,12 +7,14 @@ description : "Generation of diagram and flowchart from text in a similar manner
 
 Just insert your mermaid code in the `mermaid` shortcode and that's it.
 
-## Flowchart example
+## Examples
+
+### Flowchart example
 
     {{</*mermaid align="left"*/>}}
     graph LR;
         A[Hard edge] -->|Link text| B(Round edge)
-        B --> C{Decision}
+        B --> C{<strong>Decision</strong>}
         C -->|One| D[Result one]
         C -->|Two| E[Result two]
     {{</* /mermaid */>}}
@@ -22,7 +24,7 @@ renders as
 {{<mermaid align="left">}}
 graph LR;
     A[Hard edge] -->|Link text| B(Round edge)
-    B --> C{Decision}
+    B --> C{<strong>Decision</strong>}
     C -->|One| D[Result one]
     C -->|Two| E[Result two]
 {{</mermaid>}}
@@ -79,7 +81,7 @@ sequenceDiagram
     Bob-->John: Jolly good!
 {{</mermaid>}}
 
-## GANTT Example
+### GANTT Example
 
     {{</* mermaid */>}}
     gantt
@@ -99,7 +101,6 @@ sequenceDiagram
             Add to mermaid                      :1d
     {{</* /mermaid */>}}
 
-
 renders as
 
 {{<mermaid>}}
@@ -120,7 +121,6 @@ gantt
         Add to mermaid                      :1d
 {{</mermaid>}}
 
-
 ### Class example
 
     {{</* mermaid */>}}
@@ -142,7 +142,6 @@ gantt
 
 renders as
 
-
 {{<mermaid>}}
 classDiagram
   Class01 <|-- AveryLongClass : Cool
@@ -160,7 +159,6 @@ classDiagram
   Class08 <--> C2: Cool label
 {{</mermaid>}}
 
-
 ### Git example
 
     {{</* mermaid */>}}
@@ -228,3 +226,27 @@ stateDiagram-v2
   locked --> closed: Unlock
   closed --> open: Open
 {{</mermaid>}}
+
+## Configuration
+
+By default, mermaid is configured with default settings. You can customize mermaids default settings for all of your files thru a JSON object in your `config.toml` or override these settings sidewise thru your pages frontmatter.
+
+This JSON object is forwarded into mermaids `mermaid.initialize()` function.
+
+See [mermaid documentation](http://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults) for all allowed settings.
+
+### Allow HTML in graphs
+
+By default newer versions of mermaid disallow HTML in graphs if you are using default settings. To enable this, set the following line in your `config.toml`
+
+````toml
+[params]
+  mermaidInitialize = "{ \"securityLevel\": \"loose\", \"startOnLoad\": true }"
+````
+
+or pages frontmatter
+````toml
++++
+mermaidInitialize = "{ \"securityLevel\": \"loose\", \"startOnLoad\": true }"
++++
+````