mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-29 22:29:56 +02:00
Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'
This commit is contained in:
Bjørn Erik Pedersen
@@ -2,14 +2,8 @@
|
||||
title: Image render hooks
|
||||
linkTitle: Images
|
||||
description: Create an image render to hook override the rendering of Markdown images to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 60
|
||||
weight: 60
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Markdown
|
||||
@@ -28,76 +22,59 @@ These components are passed into the render hook [context](g) as shown below.
|
||||
|
||||
Image render hook templates receive the following context:
|
||||
|
||||
###### Attributes
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
(`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 >}}
|
||||
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
Destination
|
||||
: (`string`) The image destination.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser]
|
||||
wrapStandAloneImageWithinParagraph = false
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
IsBlock
|
||||
: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.
|
||||
|
||||
###### Destination
|
||||
Ordinal
|
||||
: (`int`) The zero-based ordinal of the image on the page.
|
||||
|
||||
(`string`) The image destination.
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
###### IsBlock
|
||||
PageInner
|
||||
: {{< new-in 0.125.0 />}}
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
(`bool`) Returns true if a standalone image is not wrapped within a paragraph element.
|
||||
PlainText
|
||||
: (`string`) The image description as plain text.
|
||||
|
||||
###### Ordinal
|
||||
Text
|
||||
: (`template.HTML`) The image description.
|
||||
|
||||
(`int`) The zero-based ordinal of the image on the page.
|
||||
|
||||
###### Page
|
||||
|
||||
(`page`) A reference to the current page.
|
||||
|
||||
###### PageInner
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
|
||||
###### PlainText
|
||||
|
||||
(`string`) The image description as plain text.
|
||||
|
||||
###### Text
|
||||
|
||||
(`template.HTML`) The image description.
|
||||
|
||||
###### Title
|
||||
|
||||
(`string`) The image title.
|
||||
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.
|
||||
{{% /note %}}
|
||||
> [!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:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true}
|
||||
<img src="{{ .Destination | safeURL }}"
|
||||
{{- with .PlainText }} alt="{{ . }}"{{ end -}}
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
>
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To render standalone images within `figure` elements:
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true}
|
||||
{{- if .IsBlock -}}
|
||||
<figure>
|
||||
<img src="{{ .Destination | safeURL }}"
|
||||
@@ -111,7 +88,7 @@ To render standalone images within `figure` elements:
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
>
|
||||
{{- end -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Note that the above requires the following site configuration:
|
||||
|
||||
@@ -126,8 +103,6 @@ wrapStandAloneImageWithinParagraph = false
|
||||
|
||||
Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:
|
||||
|
||||
[embedded image render hook]: {{% eturl render-image %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.image]
|
||||
enableDefault = true
|
||||
@@ -135,11 +110,8 @@ 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.
|
||||
|
||||
{{% note %}}
|
||||
The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
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.
|
||||
|
||||
@@ -157,4 +129,10 @@ target = 'assets'
|
||||
|
||||
Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: {{% eturl render-image %}}
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
Reference in New Issue
Block a user