diff options
Diffstat (limited to 'content/en/render-hooks/blockquotes.md')
| -rwxr-xr-x | content/en/render-hooks/blockquotes.md | 62 |
1 files changed, 49 insertions, 13 deletions
diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md index e0eda5c51..143c536d1 100755 --- a/content/en/render-hooks/blockquotes.md +++ b/content/en/render-hooks/blockquotes.md @@ -24,6 +24,18 @@ Blockquote render hook templates receive the following [context]: (`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. + +###### 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 `+`, `-`, or an empty string. See the [alerts](#alerts) section below. + ###### Attributes (`map`) The [Markdown attributes], available if you configure your site as follows: @@ -45,7 +57,7 @@ block = true ###### PageInner -(`page`) A reference to a page nested via the [`RenderShortcodes`] method. +(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). [`RenderShortcodes`]: /methods/page/rendershortcodes @@ -54,7 +66,7 @@ block = true (`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. +(`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below. ###### Type @@ -68,7 +80,7 @@ In its default configuration, Hugo renders Markdown blockquotes according to the {{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} <blockquote> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{< /code >}} @@ -77,7 +89,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and {{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} <figure> <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ with .Attributes.caption }} <figcaption class="blockquote-caption"> @@ -96,7 +108,11 @@ Then in your markdown: ## Alerts -Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. For example: +Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. + +### Basic syntax + +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 >}} > [!NOTE] @@ -115,15 +131,30 @@ Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphas > 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 `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example: + +{{< code file=content/example.md lang=text >}} +> [!WARNING]+ Radiation hazard +> Do not approach or handle without protective gear. +{{< /code >}} + +The extended syntax is compatible with [Obsidian]. {{% note %}} -This syntax is compatible with the GitHub Alert Markdown extension. +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 %}} +### Example -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. +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 >}} {{ $emojis := dict @@ -138,13 +169,17 @@ The blockquote render hook below renders a multilingual alert if an alert desgin <blockquote class="alert alert-{{ .AlertType }}"> <p class="alert-heading"> {{ transform.Emojify (index $emojis .AlertType) }} - {{ or (i18n .AlertType) (title .AlertType) }} + {{ with .AlertTitle }} + {{ . }} + {{ else }} + {{ or (i18n .AlertType) (title .AlertType) }} + {{ end }} </p> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ else }} <blockquote> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ end }} {{< /code >}} @@ -159,7 +194,6 @@ 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 @@ -169,3 +203,5 @@ layouts/ ├── render-blockquote-alert.html └── render-blockquote-regular.html ``` + +{{% include "/render-hooks/_common/pageinner.md" %}} |