# Images
> Plain Markdown image syntax plus one attribute line gives you captions, sizing, zoom, links, numbering and Hugo image processing.
---
LLMS index: [llms.txt](/llms.txt)
---
There is one way to write an image: Markdown's ``. An
image standing alone as its own paragraph can be followed by a `{…}` attribute
line, making it a captioned figure, a zoom candidate, a numbered figure, or a
derivative processed by Hugo. The theme has no image shortcode.
## Shortest form {#minimal}
```markdown {title="Source"}
```
This image sits in the same directory as the page (a page bundle), so the theme
reads its intrinsic size and writes `width`/`height`, and the page does not
shift while loading; every image is lazy-loaded. Alternative text serves screen
readers and search engines and should always be written; an empty alt marks a
decorative image, which zoom skips.
## Where images come from {#sources}
Sources resolve in the following order, written the same way in each case:
| Placement | How it is written | Suited to |
| --- | --- | --- |
| Beside the page (a bundle: `index.md` plus the image) | `` | A screenshot only this page uses; it travels with the page and is shared by translations |
| Current section bundle (`_index.md` and its resources) | `` | Images belonging to a section; use the resource path relative to that section |
| Global resource `assets/images/…` | `` | Images several pages share, especially ones needing processing (resize / crop) |
| Static directory `static/images/…` | `` | Large images and downloads that need no processing; supply `width`/`height` where the theme cannot measure them |
| Remote URL | `` | Rare: nothing is downloaded at build time and nothing can be processed |
A relative path is looked up as a page resource, a resource of the current
section, and then a global resource; if none matches, it is emitted as a static
path. The theme does not check whether a static path or a remote URL exists. When processing cannot resolve a
processable resource, ordinary preview warns and leaves the image unprocessed;
strict publishing rejects the warning.
Markdown alternative text takes precedence over resource metadata, including an
explicitly empty alt for a decorative image. Resource `params.alt` must be a
string; invalid metadata warns and is ignored, preserving the authored alt.
Strict publishing rejects that warning.
## Inline versus block {#inline-vs-block}
An image inside a line of text is an inline image, rendered as one `` and
unable to carry attributes; an image standing alone as its own paragraph is a
block image and can carry an attribute line.
```markdown {title="Source"}
This little one  sits inside a sentence — an inline image.
{width="100" height="64"}
```
This little one  sits inside a sentence — an inline image.
{width="100" height="64"}
An inline image displays at its own size (50×32 here). An SVG with no intrinsic
size stretches to the container width when inlined, so an SVG belongs as a block
image with explicit `width`/`height`.
> [!NOTE]
> Block images depend on the site setting
> `markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false` (this site
> has it; see [Configuration](/docs/customize/config/)). Without it, Goldmark
> wraps a standalone image in `
` and the attribute line is treated as prose.
## Captions {#caption}
An attribute line with `caption="…"` renders the image as a `` plus a
``. A caption is plain text and is not parsed as Markdown.
```markdown {title="Source"}
{caption="The release card uses the page's release_url and date"}
```
{caption="The release card uses the page's release_url and date"}
A Markdown `"title"` keeps its own meaning (a hover tooltip) and never becomes
the caption.
## Size {#size}
`width`/`height` are positive integers overriding the resource's own dimensions:
they give a static or remote image a placeholder box so the page does not shift,
or display a large image smaller (the browser scales it; the file is unchanged).
```markdown {title="Source"}
{width="450" height="300" caption="A 900×600 illustration from static/images/ shown at half size"}
```
{width="450" height="300" caption="A 900×600 illustration from static/images/ shown at half size"}
## Processed images {#processing}
Page resources and global resources can be processed by Hugo at build time:
`command` and `options` must both be given, the command is one of `Fit`,
`Resize`, `Fill` or `Crop`, and the options are Hugo's image processing string.
The rendered `src` is the derivative; with zoom enabled the dialog opens the
original.
```markdown {title="Source"}
{command="Fit" options="300x150" caption="Fit 300x150: scaled to fit inside a 300×150 box"}
{command="Fill" options="300x150 Left" caption="Fill 300x150 Left: fills the box, cropped from the left"}
```
{command="Fit" options="300x150" caption="Fit 300x150: scaled to fit inside a 300×150 box"}
{command="Fill" options="300x150 Left" caption="Fill 300x150 Left: fills the box, cropped from the left"}
Static paths, remote URLs and SVG cannot be processed. Writing `command` for
one warns and leaves it unprocessed; strict publishing rejects the warning. The
options syntax (anchors, quality, format conversion, as
in `300x150 webp q80`) is in
[Hugo image processing](https://gohugo.io/content-management/image-processing/).
## Linked images {#link}
Two forms, for different purposes:
- No caption, and the image itself is the link: wrap it in a Markdown link, `[](href)`.
- A captioned figure that is clickable as a whole: add `link="…"` to the attribute line (which requires `caption` or `num`).
```markdown {title="Source"}
[](/docs/about/features/)
{caption="Click the image for the releases and downloads guide" link="/docs/write/releases/"}
```
[](/docs/about/features/)
{caption="Click the image for the releases and downloads guide" link="/docs/write/releases/"}
A linked image never zooms. Writing `link=` with no caption warns and drops the
link, pointing at `[](…)` instead; strict publishing rejects the warning.
## Numbered figures {#numbered}
Numbered figures are for books and long manuals: add `num` to the attribute
line, with an optional `#id`. The number is a string the author writes (`2-1`,
`3.4`) and the theme never counts automatically; the caption gains a localized
"Figure 2-1" prefix, and `#id` defaults to `fig-`. Reference it from the
prose with an ordinary link `[Figure 2-1](#fig-2-1)` or the `xref` shortcode; a
whole-book list of figures is in [Books](/docs/write/book/).
```markdown {title="Source"}
{#fig-release num="2-1" caption="The release card: version, date and assets"}
See [Figure 2-1](#fig-release).
```
{#fig-release num="2-1" caption="The release card: version, date and assets"}
See [Figure 2-1](#fig-release).
A numbered figure can be a processed image at the same time (`num` plus
`command`), and can carry a `link`.
## Zoom {#zoom}
Image zoom is off by default. Once the site enables it, block images, figures
and gallery images that have alt text become clickable buttons that open the
full image in a native `