Image render hooks

Markdown

A Markdown image has three components: the image description, the image destination, and optionally the image title.

![white kitten](/images/kitten.jpg "A kitten!")
  ------------  ------------------  ---------
  description      destination        title

These components are passed into the render hook context as shown below.

Context

Image render hook templates receive the following context:

Attributes

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

markup:
  goldmark:
    parser:
      attribute:
        block: true
      wrapStandAloneImageWithinParagraph: false

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

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            },
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

Destination

(string) The image destination.

IsBlock

(bool) Returns true if a standalone image is not wrapped within a paragraph element.

Ordinal

(int) The zero-based ordinal of the image 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.

PlainText

(string) The image description as plain text.

Text

(template.HTML) The image description.

Title

(string) The image title.

Examples

In its default configuration, Hugo renders Markdown images according to the CommonMark specification. To create a render hook that does the same thing:

<img src="{{ .Destination | safeURL }}"
  {{- with .Text }} alt="{{ . }}"{{ end -}}
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- /* chomp trailing newline */ -}}

To render standalone images within figure elements:

{{- if .IsBlock -}}
  <figure>
    <img src="{{ .Destination | safeURL }}"
      {{- with .Text }} alt="{{ . }}"{{ end -}}
    >
    {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
  </figure>
{{- else -}}
  <img src="{{ .Destination | safeURL }}"
    {{- with .Text }} alt="{{ . }}"{{ end -}}
    {{- with .Title }} title="{{ . }}"{{ end -}}
  >
{{- end -}}

Note that the above requires the following site configuration:

markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      wrapStandAloneImageWithinParagraph = false

{
   "markup": {
      "goldmark": {
         "parser": {
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

Default

Hugo includes an embedded image render hook to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:

markup:
  goldmark:
    renderHooks:
      image:
        enableDefault: true

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = true

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "image": {
               "enableDefault": true
            }
         }
      }
   }
}

A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.

The embedded image render hook resolves internal Markdown destinations by looking for a matching page resource, falling back to a matching global resource. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.

You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:

module:
  mounts:
  - source: assets
    target: assets
  - source: static
    target: assets

[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    source = 'static'
    target = 'assets'

{
   "module": {
      "mounts": [
         {
            "source": "assets",
            "target": "assets"
         },
         {
            "source": "static",
            "target": "assets"
         }
      ]
   }
}

Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.

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