---
title: Image render hooks
linkTitle: Images
description: Create image render hook templates to override the rendering of Markdown images to HTML.
categories: []
keywords: []
---

## Markdown

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

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

These components are passed into the render hook [context](g) 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:

  {{< code-toggle file=hugo >}}
  [markup.goldmark.parser]
  wrapStandAloneImageWithinParagraph = false
  [markup.goldmark.parser.attribute]
  block = true
  {{< /code-toggle >}}

`Destination`
: (`string`) The image destination.

`IsBlock`
: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.

`Ordinal`
: {{< new-in v0.160.0 />}}
: (`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](#pageinner-details).

`PlainText`
: (`string`) The image description as plain text.

`Position`
: {{< new-in 0.160.0 />}}
: (`string`) The position of the image within the page content.

`Text`
: (`template.HTML`) The image description.

`Title`
: (`string`) The image title.

## Examples

> [!NOTE]
> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.

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

```go-html-template {file="layouts/_markup/render-image.html" copy=true}
<img src="{{ .Destination | safeURL }}"
  {{- with .PlainText }} alt="{{ . }}"{{ end -}}
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- /* chomp trailing newline */ -}}
```

To render standalone images within `figure` elements:

```go-html-template {file="layouts/_markup/render-image.html" copy=true}
{{- if .IsBlock -}}
  <figure>
    <img src="{{ .Destination | safeURL }}"
      {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    >
    {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
  </figure>
{{- else -}}
  <img src="{{ .Destination | safeURL }}"
    {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    {{- with .Title }} title="{{ . }}"{{ end -}}
  >
{{- end -}}
```

Note that the above requires the following project configuration:

{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
wrapStandAloneImageWithinParagraph = false
{{< /code-toggle >}}

## Embedded

Hugo includes an [embedded image render hook][] to resolve Markdown image destinations. You can adjust its behavior in your project configuration. This is the default setting:

{{< code-toggle file=hugo >}}
[markup.goldmark.renderHooks.image]
useEmbedded = 'auto'
{{< /code-toggle >}}

When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host projects, specifically when the [duplication of shared page resources][] feature is disabled. This is the default behavior for such projects. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.

You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. See [details][].

The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). 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 project configuration:

{{< code-toggle file=hugo >}}
[[module.mounts]]
source = 'assets'
target = 'assets'

[[module.mounts]]
source = 'static'
target = 'assets'
{{< /code-toggle >}}

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

{{% include "/_common/render-hooks/pageinner.md" %}}

[CommonMark]: https://spec.commonmark.org/current/
[Markdown attributes]: /content-management/markdown-attributes/
[`RenderShortcodes`]: /methods/page/rendershortcodes/
[details]: /configuration/markup/#renderhooksimageuseembedded
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
[embedded image render hook]: <{{% eturl render-image %}}>
