From 3ffdf79c278187dad1211cd7c62c30d3729a2ae4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6ren=20Weber?= <mail@soeren-weber.de>
Date: Sun, 24 Oct 2021 11:34:29 +0200
Subject: [PATCH] docs: switch to some kind of EBNF for shortcodes

---
 exampleSite/content/shortcodes/expand.en.md    |  2 +-
 exampleSite/content/shortcodes/include.en.md   |  6 +++---
 exampleSite/content/shortcodes/mermaid.en.md   |  4 ++--
 exampleSite/content/shortcodes/notice.en.md    | 12 +++++++-----
 exampleSite/content/shortcodes/siteparam.en.md | 12 +++++++++++-
 5 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/exampleSite/content/shortcodes/expand.en.md b/exampleSite/content/shortcodes/expand.en.md
index 09c2e6db32..4d991c585c 100644
--- a/exampleSite/content/shortcodes/expand.en.md
+++ b/exampleSite/content/shortcodes/expand.en.md
@@ -8,7 +8,7 @@ The Expand shortcode displays an expandable/collapsible section of text on your
 ## Usage
 
 ````go
-{{%/* expand "Does this Relearn theme rock?" { "true" | "false" } */%}}
+{{%/* expand [ <string> [ "true" | "false" ] ] */%}}
 Yes!
 {{%/* /expand */%}}
 ````
diff --git a/exampleSite/content/shortcodes/include.en.md b/exampleSite/content/shortcodes/include.en.md
index ff3e6dc986..f39a109a2f 100644
--- a/exampleSite/content/shortcodes/include.en.md
+++ b/exampleSite/content/shortcodes/include.en.md
@@ -8,12 +8,12 @@ The include shortcode includes other files from your project inside of the curre
 ## Usage
 
 ````go
-{{%/* include "<file>" { "true" | "false" } */%}}
+{{%/* include <string> [ "true" | "false" ] */%}}
 ````
 
-The first parameter is the path to the file to be included.
+The first required parameter is the path to the file to be included.
 
-If the file's content will be displayed as HTML, the second optional parameter controls if the first heading of the included file should be displayed ("true")- which is the default - or be hidden.
+If the file's content will be displayed as HTML, the second optional parameter controls if the first heading of the included file should be displayed (`"true"`)- which is the default - or be hidden.
 
 ## Examples
 
diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md
index 0d16513210..55ee672205 100644
--- a/exampleSite/content/shortcodes/mermaid.en.md
+++ b/exampleSite/content/shortcodes/mermaid.en.md
@@ -10,13 +10,13 @@ title = "Mermaid"
 Just insert your Mermaid code in the `mermaid` shortcode like this:
 
 ````go
-{{</* mermaid [ align=(left|right|center|justify) ] */>}}
+{{</* mermaid [ align=("left"|"right"|"center"|"justify") ] */>}}
 classDiagram
     Person *-- Dog
 {{</* /mermaid */>}}
 ````
 
-You can set an optional `align` attribute which defaults to `center`.
+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 have turned off `guessSyntax` for the `markup.highlight` setting (see below):
 
diff --git a/exampleSite/content/shortcodes/notice.en.md b/exampleSite/content/shortcodes/notice.en.md
index e02110d00a..2bdcc23b14 100644
--- a/exampleSite/content/shortcodes/notice.en.md
+++ b/exampleSite/content/shortcodes/notice.en.md
@@ -8,7 +8,7 @@ The notice shortcode shows four types of disclaimers to help you structure your
 ## Usage
 
 ````go
-{{%/* notice [ note | info | tip | warning ] [?string] */%}}
+{{%/* notice ( note | info | tip | warning ) [ <string> ] */%}}
 Some markup
 {{%/* /notice */%}}
 ````
@@ -199,12 +199,14 @@ You can add:
 
 You can customize the title of the notice by passing it as a second parameter.
 
+{{% notice note "Pay Attention to this Note!" %}}
+The title is now the parameter that was provided.
+{{% /notice %}}
+
+{{% expand "Show markup" %}}
 ````go
 {{%/* notice note "Pay Attention to this Note!" */%}}
 The title is now the parameter that was provided.
 {{%/* /notice */%}}
 ````
-
-{{% notice note "Pay Attention to this Note!" %}}
-The title is now the parameter that was provided.
-{{% /notice %}}
+{{% /expand %}}
diff --git a/exampleSite/content/shortcodes/siteparam.en.md b/exampleSite/content/shortcodes/siteparam.en.md
index 5403c8d58f..e09c0ea623 100644
--- a/exampleSite/content/shortcodes/siteparam.en.md
+++ b/exampleSite/content/shortcodes/siteparam.en.md
@@ -3,7 +3,17 @@ description = "Get value of site params variables in your page"
 title = "Site param"
 +++
 
-`siteparam` shortcode is used to help you print values of site params.
+The `siteparam` shortcode is used to help you print values of site params.
+
+## Usage
+
+````go
+{{%/* siteparam <string */%}}
+````
+
+The first required parameter is the name of the site param to be displayed.
+
+## Examples
 
 For instance, in this current site, the `editURL` variable is used in `config.toml`