From f3b9c7825308576ddc8f1cfbf10eda2f7a778001 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6ren=20Weber?= <mail@soeren-weber.de>
Date: Tue, 13 Aug 2024 13:33:49 +0200
Subject: [PATCH] docs: clarification for notice/alert #885

---
 exampleSite/content/cont/markdown.en.md     | 28 ++++++++++++++++++++-
 exampleSite/content/shortcodes/notice.en.md | 25 +++++++++++++++++-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/exampleSite/content/cont/markdown.en.md b/exampleSite/content/cont/markdown.en.md
index ebfe0852d4..1922807a4a 100644
--- a/exampleSite/content/cont/markdown.en.md
+++ b/exampleSite/content/cont/markdown.en.md
@@ -28,7 +28,7 @@ John Gruber, the author of Markdown, puts it like this:
 
 ## Standard and Extensions
 
-If not otherwise noted, the showed examples adhere to the [Commonmark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions that [can be activated](https://gohugo.io/getting-started/configuration-markup/#goldmark) in your `hugo.toml` or are built into the theme:
+If not otherwise noted, the shown examples adhere to the [Commonmark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions that [can be activated](https://gohugo.io/getting-started/configuration-markup/#goldmark) in your `hugo.toml` or are built into the theme:
 
 - {{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Extension on top of standard Markdown adhering to [GitHub Flavored Markdown](https://github.github.com/gfm/).
 
@@ -139,6 +139,11 @@ Blockquotes can also be nested.
 
 ## Alerts
 
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.132.0{{% /badge %}} GitHub styled alerts are also supported.
+
+If you are in need of more advanced options to style your alerts, use the [notice shortcode](shortcodes/notice).
+
+````md
 > [!CAUTION]
 > Advises about risks or negative outcomes of certain actions.
 
@@ -156,6 +161,27 @@ Blockquotes can also be nested.
 
 > [!WARNING]
 > Urgent info that needs immediate user attention to avoid problems.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!INFO]
+> Information that users might find interesting.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+{{% /notice %}}
 
 ## Text Markers
 
diff --git a/exampleSite/content/shortcodes/notice.en.md b/exampleSite/content/shortcodes/notice.en.md
index 1a93498a59..6b93b7c5fa 100644
--- a/exampleSite/content/shortcodes/notice.en.md
+++ b/exampleSite/content/shortcodes/notice.en.md
@@ -11,9 +11,19 @@ It is all about the boxes.
 
 ## Usage
 
-While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.
+While the examples are using shortcodes with named parameter you are free to use positional as well, use it as [GitHub styled alerts](/cont/markdown#alerts) or also call this shortcode from your own partials.
+
+Note that if you want to use GitHub styled alerts Markdown, this is only available starting with Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.132.0{{% /badge %}}. In this case no parameter from the below table are available.
 
 {{< tabs groupid="shortcode-parameter">}}
+{{% tab title="markdown" %}}
+
+````md
+> [!NOTE]
+> It is all about the boxes.
+````
+
+{{% /tab %}}
 {{% tab title="shortcode" %}}
 
 ````go
@@ -57,6 +67,19 @@ It is all about the boxes.
 | **icon**  | 3        | see notes | [Font Awesome icon name](shortcodes/icon#finding-an-icon) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other styles: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
 | _**&lt;content&gt;**_ |          | _&lt;empty&gt;_ | Arbitrary text to be displayed in box. |
 
+## Configuration
+
+If you are using [GitHub styled alerts](/cont/markdown#alerts), by default the theme also accepts alert levels like `info` not known to GitHub's implementation. If this interferes with your layout, you can turn this extension off by setting `disableBlockquoteNoticeSupport=true` in your `hugo.toml`.
+
+### Global Configuration File
+
+This example reflects the default configuration also used if you don't set anything explicitly.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableBlockquoteNoticeSupport = false
+{{< /multiconfig >}}
+
 ## Examples
 
 ### By Severity