Working with Images
- Date
- Tags
- Images Markdown Page-Bundles
- Author
- Thomas Laurenson
letsblaze handles images with a custom render hook that supports three rendering modes controlled by the imageMode param, plus automatic dimension detection for page-bundle images.
Image mode
The imageMode param controls how Markdown images are rendered. Set it site-wide in hugo.toml or override it per page in front matter.
| Value | Output |
|---|---|
embed (default) | Wraps the image in a <figure> element |
link-same-tab | Renders a bare <a> link using the alt text as link text |
link-new-tab | Same as link-same-tab but opens in a new tab with rel="noopener noreferrer" |
Site-wide in hugo.toml:
[params]
imageMode = "embed"Per-page in front matter:
---
imageMode: link-same-tab
---Eager and lazy loading
In embed mode, the first image on a page (Ordinal 0) is treated as a likely above-the-fold image. It is rendered with loading="eager" and fetchpriority="high" to improve Largest Contentful Paint (LCP). All subsequent images use loading="lazy". This is automatic, no configuration required.
Page bundles
The recommended way to use images is as page bundles: store the image alongside the content file:
content/
blog/
working-with-images/
index.md ← this file
hero.jpg ← image in the same directoryThis is a leaf bundle. Hugo can read the image dimensions at build time and emit width and height attributes automatically, preventing layout shift (CLS).
Basic image
Standard Markdown syntax:
Image with caption
Add a title in quotes after the path to render a <figcaption>:
External images
External URLs work but Hugo cannot read their dimensions. The image renders without width/height attributes. This is correct behaviour, as no dimensions are better than wrong dimensions.
Alt text
Always write descriptive alt text. It is read by screen readers and displayed when the image fails to load. An empty alt="" is correct for purely decorative images, as it tells screen readers to skip the element.