mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-29 22:29:56 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/content/en/render-hooks/blockquotes.md
View File

@@ -2,14 +2,8 @@
title: Blockquote render hooks
linkTitle: Blockquotes
description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML.
categories: [render hooks]
categories: []
keywords: []
menu:
docs:
parent: render-hooks
weight: 30
weight: 30
toc: true
---
{{< new-in 0.132.0 />}}
@@ -18,73 +12,56 @@ toc: true
Blockquote render hook templates receive the following [context](g):
###### AlertType
AlertType
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
AlertTitle
: {{< new-in 0.134.0 />}}
: (`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
###### AlertTitle
AlertSign
: {{< new-in 0.134.0 />}}
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of&nbsp;`+`,&nbsp;`-`,&nbsp;or an empty string. See the [alerts](#alerts) section below.
{{< new-in 0.134.0 />}}
Attributes
: (`map`) The [Markdown attributes], available if you configure your site as follows:
(`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
{{< code-toggle file=hugo >}}
[markup.goldmark.parser.attribute]
block = true
{{< /code-toggle >}}
###### AlertSign
Ordinal
: (`int`) The zero-based ordinal of the blockquote on the page.
{{< new-in 0.134.0 />}}
Page
: (`page`) A reference to the current page.
(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of&nbsp;`+`,&nbsp;`-`,&nbsp;or an empty string. See the [alerts](#alerts) section below.
PageInner
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
###### Attributes
Position
: (`string`) The position of the blockquote within the page content.
(`map`) The [Markdown attributes], available if you configure your site as follows:
Text
: (`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below.
[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. [See details](#pageinner-details).
[`RenderShortcodes`]: /methods/page/rendershortcodes
###### Position
(`string`) The position of the blockquote within the page content.
###### Text
(`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. 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.
Type
: (`string`) 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 >}}
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
<blockquote>
{{ .Text }}
</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 >}}
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
<figure>
<blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
{{ .Text }}
@@ -95,7 +72,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and
</figcaption>
{{ end }}
</figure>
{{< /code >}}
```
Then in your markdown:
@@ -112,7 +89,7 @@ Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphas
With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. For example:
{{< code file=content/example.md lang=text >}}
```text {file="content/example.md"}
> [!NOTE]
> Useful information that users should know, even when skimming content.
@@ -127,34 +104,29 @@ With the basic Markdown syntax, the first line of each alert is an alert designa
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
{{< /code >}}
```
The basic syntax is compatible with [GitHub], [Obsidian], and [Typora].
[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
### Extended syntax
With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of&nbsp;`+`&nbsp;or&nbsp;`-`, typically used to indicate whether an alert is graphically foldable. For example:
{{< code file=content/example.md lang=text >}}
```text {file="content/example.md"}
> [!WARNING]+ Radiation hazard
> Do not approach or handle without protective gear.
{{< /code >}}
```
The extended syntax is compatible with [Obsidian].
{{% note %}}
The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
{{% /note %}}
> [!note]
> The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
### Example
This blockquote render hook renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification.
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ $emojis := dict
"caution" ":exclamation:"
"important" ":information_source:"
@@ -180,7 +152,7 @@ This blockquote render hook renders a multilingual alert if an alert designator
{{ .Text }}
</blockquote>
{{ end }}
{{< /code >}}
```
To override the label, create these entries in your i18n files:
@@ -202,4 +174,11 @@ layouts/
└── render-blockquote-regular.html
```
{{% include "/render-hooks/_common/pageinner.md" %}}
{{% include "/_common/render-hooks/pageinner.md" %}}
[`RenderShortcodes`]: /methods/page/rendershortcodes
[CommonMark specification]: https://spec.commonmark.org/current/
[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
[Markdown attributes]: /content-management/markdown-attributes/
[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts