From fdd5ff7ab87ce159fc664509924d681f4b47acd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6ren=20Weber?= <mail@soeren-weber.de>
Date: Thu, 7 Oct 2021 23:01:04 +0200
Subject: [PATCH] clarify caveats for mermaid code fences

---
 exampleSite/config.toml                        |  2 +-
 exampleSite/content/cont/syntaxhighlight.en.md |  2 +-
 exampleSite/content/shortcodes/mermaid.en.md   | 16 +++++++++++-----
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/exampleSite/config.toml b/exampleSite/config.toml
index 5ac664283e..c162ede1ea 100644
--- a/exampleSite/config.toml
+++ b/exampleSite/config.toml
@@ -26,7 +26,7 @@ relativeURLs = true
 [markup]
   [markup.highlight]
     style = "base16-snazzy" # choose a color theme or create your own
-    guessSyntax = true      # avoid unstyled code if no language was given
+    guessSyntax = false     # if set to true, avoid unstyled code if no language was given but mermaid code fences will not work anymore
 
 [markup.goldmark.renderer]
   unsafe= true
diff --git a/exampleSite/content/cont/syntaxhighlight.en.md b/exampleSite/content/cont/syntaxhighlight.en.md
index 02fa463dff..b6db6875c3 100644
--- a/exampleSite/content/cont/syntaxhighlight.en.md
+++ b/exampleSite/content/cont/syntaxhighlight.en.md
@@ -57,5 +57,5 @@ You can choose a color theme from the [list of supported themes](https://xyproto
 [markup]
   [markup.highlight]
     style = "base16-snazzy" # choose a color theme or create your own
-    guessSyntax = true      # avoid unstyled code if no language was given
+    guessSyntax = false     # if set to true, avoid unstyled code if no language was given but mermaid code fences will not work anymore
 ````
diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md
index 72ec52ffb2..0d16513210 100644
--- a/exampleSite/content/shortcodes/mermaid.en.md
+++ b/exampleSite/content/shortcodes/mermaid.en.md
@@ -18,7 +18,7 @@ classDiagram
 
 You can set an optional `align` attribute which defaults to `center`.
 
-If you don't need alignment you can use the alternative syntax using code fences:
+If you don't need alignment you can use the alternative syntax using code fences if you have turned off `guessSyntax` for the `markup.highlight` setting (see below):
 
 ````plaintext
 ```mermaid
@@ -171,7 +171,7 @@ classDiagram
 
 ### State
 
-{{< mermaid >}}
+````mermaid
 stateDiagram-v2
   open: Open Door
   closed: Closed Door
@@ -180,11 +180,11 @@ stateDiagram-v2
   closed --> locked: Lock
   locked --> closed: Unlock
   closed --> open: Open
-{{< /mermaid >}}
+````
 
 {{% expand "Show markup" "true" %}}
 ````go
-{{</* mermaid */>}}
+```mermaid
 stateDiagram-v2
     open: Open Door
     closed: Closed Door
@@ -193,7 +193,7 @@ stateDiagram-v2
     closed --> locked: Lock
     locked --> closed: Unlock
     closed --> open: Open
-{{</* /mermaid */>}}
+```
 ````
 {{% /expand %}}
 
@@ -205,11 +205,17 @@ This JSON object is forwarded into Mermaid's `mermaid.initialize()` function.
 
 See [Mermaid documentation](http://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults) for all allowed settings.
 
+Also, if you want to use mermaid codefences, you have to turn off `guessSyntax` for the `markup.highlight` setting.
+
 ### Example
 
 ````toml
 [params]
   mermaidInitialize = "{ \"theme\": \"dark\" }"
+
+[markup]
+  [markup.highlight]
+    guessSyntax = false     # if set to true, avoid unstyled code if no language was given but mermaid code fences will not work anymore
 ````
 
 or pages frontmatter