From 2dae7212874ead12f2043169753301e79e4cc8ef Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Fri, 14 Jun 2024 09:07:14 -0700
Subject: [PATCH] Document blockquote render hooks

---
 content/en/render-hooks/blockquotes.md | 163 +++++++++++++++++++++++++
 content/en/render-hooks/code-blocks.md |   4 +-
 content/en/render-hooks/headings.md    |   8 +-
 content/en/render-hooks/images.md      |   8 +-
 content/en/render-hooks/links.md       |   4 +-
 5 files changed, 177 insertions(+), 10 deletions(-)
 create mode 100755 content/en/render-hooks/blockquotes.md

diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md
new file mode 100755
index 000000000..fd9a837d5
--- /dev/null
+++ b/content/en/render-hooks/blockquotes.md
@@ -0,0 +1,163 @@
+---
+title: Blockquote render hooks
+linkTitle: Blockquotes
+description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+  docs:
+    parent: render-hooks
+    weight: 30
+weight: 30
+toc: true
+---
+
+## Context
+
+Blockquote render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### AlertType
+
+(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
+
+###### Attributes
+
+(`map`) The [Markdown attributes], available if you configure your site as follows:
+
+[Markdown attributes]: /content-management/markdown-attributes/
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+block = true
+{{< /code-toggle >}}
+
+###### Ordinal
+
+(`int`) The zero-based ordinal of the blockquote on the page.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### Position
+
+(`string`) The position of the blockquote within the page content.
+
+###### Text
+(`string`) The blockquote text, excluding the alert designator if present. See the [alerts](#alerts) section below.
+
+###### Type
+
+(`bool`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below.
+
+## Examples
+
+In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
+<blockquote>
+  {{ .Text | safeHTML }}
+</blockquote>
+{{< /code >}}
+
+To render a blockquote as an HTML `figure` element with an optional citation and caption:
+
+{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
+<figure>
+  <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
+    {{ .Text | safeHTML }}
+  </blockquote>
+  {{ with .Attributes.caption }}
+    <figcaption class="blockquote-caption">
+      {{ . | safeHTML }}
+    </figcaption>
+  {{ end }}
+</figure>
+{{< /code >}}
+
+Then in your markdown:
+
+```text
+> Some text
+{cite="https://gohugo.io" caption="Some caption"}
+```
+
+## Alerts
+
+Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. For example:
+
+{{< code file=content/example.md lang=text >}}
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+{{< /code >}}
+
+
+{{% note %}}
+This syntax is compatible with the GitHub Alert Markdown extension.
+{{% /note %}}
+
+
+The first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets.
+
+The blockquote render hook below renders a multilingual alert if an alert desginator is present, otherwise it renders a blockquote according to the CommonMark specification.
+
+{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
+{{ $emojis := dict
+  "caution" ":exclamation:"
+  "important" ":information_source:"
+  "note" ":information_source:"
+  "tip" ":bulb:"
+  "warning" ":information_source:"
+}}
+
+{{ if eq .Type "alert" }}
+  <blockquote class="alert alert-{{ .AlertType }}">
+    <p class="alert-heading">
+      {{ transform.Emojify (index $emojis .AlertType) }}
+      {{ or (i18n .AlertType) (title .AlertType) }}
+    </p>
+    {{ .Text | safeHTML }}
+  </blockquote>
+{{ else }}
+  <blockquote>
+    {{ .Text | safeHTML }}
+  </blockquote>
+{{ end }}
+{{< /code >}}
+
+To override the label, create these entries in your i18n files:
+
+{{< code-toggle file=i18n/en.toml >}}
+caution = 'Caution'
+important = 'Important'
+note = 'Note'
+tip = 'Tip'
+warning = 'Warning'
+{{< /code-toggle >}}
+
+
+Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of blockquote:
+
+```text
+layouts/
+└── _default/
+    └── _markup/
+        ├── render-blockquote-alert.html
+        └── render-blockquote-regular.html
+```
diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md
index 0c11c7864..d322cb88d 100755
--- a/content/en/render-hooks/code-blocks.md
+++ b/content/en/render-hooks/code-blocks.md
@@ -7,8 +7,8 @@ keywords: []
 menu:
   docs:
     parent: render-hooks
-    weight: 30
-weight: 30
+    weight: 40
+weight: 40
 toc: true
 ---
 
diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md
index c48bb11e1..8ae3b808a 100755
--- a/content/en/render-hooks/headings.md
+++ b/content/en/render-hooks/headings.md
@@ -7,8 +7,8 @@ keywords: []
 menu:
   docs:
     parent: render-hooks
-    weight: 40
-weight: 40
+    weight: 50
+weight: 50
 toc: true
 ---
 
@@ -24,7 +24,9 @@ Heading render hook templates receive the following [context]:
 
 ###### Attributes
 
-(`map`) The Markdown attributes, available if you configure your site as follows:
+(`map`) The [Markdown attributes], available if you configure your site as follows:
+
+[Markdown attributes]: /content-management/markdown-attributes/
 
 {{< code-toggle file=hugo >}}
 [markup.goldmark.parser.attribute]
diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md
index 2d9b5e2e5..1638ceeae 100755
--- a/content/en/render-hooks/images.md
+++ b/content/en/render-hooks/images.md
@@ -7,8 +7,8 @@ keywords: []
 menu:
   docs:
     parent: render-hooks
-    weight: 50
-weight: 50
+    weight: 60
+weight: 60
 toc: true
 ---
 
@@ -32,7 +32,9 @@ Image render hook templates receive the following context:
 
 ###### Attributes
 
-(`map`) The Markdown attributes, available if you configure your site as follows:
+(`map`) The [Markdown attributes], available if you configure your site as follows:
+
+[Markdown attributes]: /content-management/markdown-attributes/
 
 {{< code-toggle file=hugo >}}
 [markup.goldmark.parser]
diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md
index bf0485068..79c3d6926 100755
--- a/content/en/render-hooks/links.md
+++ b/content/en/render-hooks/links.md
@@ -7,8 +7,8 @@ keywords: []
 menu:
   docs:
     parent: render-hooks
-    weight: 60
-weight: 60
+    weight: 70
+weight: 70
 toc: true
 ---