Blockquote render hooks

Context #

Blockquote render hook templates receive the following [context]:

AlertType #

(string) Applicable when Type is alert, this is the alert type converted to lowercase. See the alerts section below.

AlertTitle #

(template.HTML) Applicable when Type is alert, this is the alert title. See the alerts section below.

AlertSign #

(string) Applicable when 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 section below.

Attributes #

(map) The [Markdown attributes], available if you configure your site as follows:

markup:
  goldmark:
    parser:
      attribute:
        block: true

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            }
         }
      }
   }
}

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.

Position #

(string) The position of the blockquote within the page content.

Text #

(template.HTML) The blockquote text, excluding the first line if Type is alert. See the alerts section below.

Type #

(bool) The blockquote type. Returns alert if the blockquote has an alert designator, else regular. See the 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:

<blockquote>
  {{ .Text }}
</blockquote>

To render a blockquote as an HTML figure element with an optional citation and caption:

<figure>
  <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
    {{ .Text }}
  </blockquote>
  {{ with .Attributes.caption }}
    <figcaption class="blockquote-caption">
      {{ . | safeHTML }}
    </figcaption>
  {{ end }}
</figure>

Then in your markdown:

> Some text
{cite="https://gohugo.io" caption="Some caption"}

Alerts #

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:

> [!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.

The basic syntax is compatible with [GitHub], [Obsidian], and [Typora].

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:

> [!WARNING]+ Radiation hazard
> Do not approach or handle without protective gear.

The extended syntax is compatible with [Obsidian].

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.

{{ $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) }}
      {{ with .AlertTitle }}
        {{ . }}
      {{ else }}
        {{ or (i18n .AlertType) (title .AlertType) }}
      {{ end }}
    </p>
    {{ .Text }}
  </blockquote>
{{ else }}
  <blockquote>
    {{ .Text }}
  </blockquote>
{{ end }}

To override the label, create these entries in your i18n files:

caution: Caution
important: Important
note: Note
tip: Tip
warning: Warning

caution = 'Caution'
important = 'Important'
note = 'Note'
tip = 'Tip'
warning = 'Warning'

{
   "caution": "Caution",
   "important": "Important",
   "note": "Note",
   "tip": "Tip",
   "warning": "Warning"
}

Although you can use one template with conditional logic as shown above, you can also create separate templates for each Type of blockquote:

layouts/
└── _default/
    └── _markup/
        ├── render-blockquote-alert.html
        └── render-blockquote-regular.html