Images
This page explains the ways to add images to an Ananke site and the paths each one uses.
Static images #
Files in your project’s static/ directory are copied to the site root as-is.
A file at static/images/example.jpg is served at /images/example.jpg:
my-site/
└── static/
└── images/
└── example.jpg # available at /images/example.jpgReference static images with a leading / (note: no static in the URL).
Images in Markdown #
Add an image in content with standard Markdown. Always include descriptive alt text:
Page bundle images #
A page bundle keeps a
page and its images together in one folder. Put the image next to the page’s
index.md:
content/posts/my-post/
├── index.md
└── header.jpgInside that page you can reference the image by its filename (header.jpg)
rather than an absolute path, and the theme’s featured-image lookup can find it
automatically.
Featured images #
The featured_image front matter sets a page’s hero image. It can point to a
static path or, in a page bundle, to a resource by filename:
+++
title = "Bundled image example"
featured_image = "header.jpg"
+++The full lookup order (front matter featured_image, then the images array,
then a bundle resource named cover/feature) and the colour fallback are
described in Page headers.
Social sharing images #
Social previews use the images front matter array, not featured_image. See SEO → Social previews.
Alt text #
Alt text describes an image for screen-reader users and when an image fails to load.
- For meaningful images, write alt text that conveys the information the image carries.
- For purely decorative images, use empty alt text (
) so screen readers skip them. - The hero/featured image is a CSS background and is treated as decorative — do not rely on it to convey information (see Page headers → Accessibility).
Common path mistakes #
- Including
staticin the URL. A file atstatic/images/x.jpgis referenced as/images/x.jpg, never/static/images/x.jpg. - Missing leading slash. For static images use
/images/x.jpg; a relativeimages/x.jpgresolves against the current page URL and often breaks. - Wrong case. File systems on deploy servers are case-sensitive —
Header.JPGandheader.jpgare different files. - Bundle image referenced with an absolute path. Inside a page bundle,
reference the resource by filename (
header.jpg), not/header.jpg.
Responsive header images #
From Ananke v2.21.0, home, list, and individual-page headers process local image resources. Put a shared image in assets/images/header.jpg, and select it in page front matter:
---
title: Home
params:
featured_image: images/header.jpg
---Ananke searches the page bundle first, then assets/. Bundle images can use a filename such as header.jpg. Existing static and external URLs still work, but are not resized. SVG images retain their original URL.
The optional ananke.responsive_image_widths parameter defaults to [480, 960, 1440, 1920]. For example, in config/_default/params.toml:
[ananke]
responsive_image_widths = [480, 960, 1440, 1920]Page front matter under params.ananke overrides a cascade or site configuration. Widths must be positive integers in pixels.
The header selects the next image width that covers the viewport. The original image supplies the largest size; Ananke does not enlarge smaller sources. These backgrounds are decorative, and the header’s existing crop, overlay, and spacing settings still apply.
Back to contents