Images & Figures
Add images and figures in Hugo — control sizing, add captions with the figure shortcode, and organize image assets in page bundles.
Basic Image Syntax
Always include descriptive alt text for accessibility and SEO.
Image Resolution
From the site media library in assets/media/ (Ownable first checks the page folder, then falls back to assets/media/):
From a page bundle (image in same folder as index.md):
Remote URL:
Sizing with HTML
Markdown doesn't support image sizing natively. Use HTML for precise control:
<img src="my-image.jpg" alt="Descriptive alt text" width="600" />Or constrain by both dimensions:
<img src="my-image.jpg" alt="Photo" width="400" height="300" />Linked Images
Wrap an image in a link to make it clickable:
[](https://example.com)Figure Shortcode
For images with captions, use the figure shortcode:
{{</* figure src="image.jpg" caption="A beautiful sunset over the mountains." */>}}| Parameter | Description |
|---|---|
src | Required. Path to image (page bundle, assets/media/, or URL) |
caption | Caption text displayed below the image (supports Markdown) |
For featured images and page covers, see Page Features. The figure shortcode is for inline figures within your content body.
Image Optimization
Hugo automatically processes local images for performance:
- WebP is recommended for best compression
- JPG for photography
- PNG for diagrams requiring lossless detail
- SVG is rendered as-is (bypasses Hugo's resize pipeline)
Asset Organization
Use Page Bundles
For the best experience, use Page Bundles (folders named index.md). Images in the same folder as your content file can be referenced by filename alone:
Two strategies for storing images:
| Strategy | Path | Best For |
|---|---|---|
| Page Bundle | Same folder as index.md | Page-specific images |
| Media Library | assets/media/ | Shared/global images |
Was this page helpful?
Lists & Task Lists
Create unordered lists, ordered lists, nested lists, task lists with checkboxes, and definition lists in Hugo Markdown.
Tables
Create Markdown tables with column alignment and formatting, or import CSV data with the table shortcode in Hugo.
From the makers of
© 2026 Lore Labs.