blob: e0eda5c51c9835fa947d1b55f3b83cf2d4b6e3bb (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
---
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
---
{{< new-in 0.132.0 >}}
## 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.
###### PageInner
(`page`) A reference to a page nested via the [`RenderShortcodes`] method.
[`RenderShortcodes`]: /methods/page/rendershortcodes
###### 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
```
|
