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

PageInner details

The primary use case for PageInner is to resolve links and page resources relative to an included Page. For example, create an “include” shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:

{{ with .Get 0 }}
  {{ with $.Page.GetPage . }}
    {{- .RenderShortcodes }}
  {{ else }}
    {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
{{ end }}

Then call the shortcode in your Markdown:

{{% include "/posts/p2" %}}

Any render hook triggered while rendering /posts/p2 will get:

• /posts/p1 when calling Page
• /posts/p2 when calling PageInner

PageInner falls back to the value of Page if not relevant, and always returns a value.

As a practical example, Hugo’s embedded link and image render hooks use the PageInner method to resolve markdown link and image destinations. See the source code for each:

• Embedded link render hook
• Embedded image render hook