Chronicle
IntroductionQuick startProject structure

Pages and frontmatterNavigationComponentsImagesLinks and redirectsAuthors and bylines

Versioned documentationAPI referenceSearchMultiple content sectionsMove an existing docs site

Choosing a themeTheme options

chronicle.yamlFrontmatter fieldsCLI commandsGenerated routes

Build and serveDeployDockerMonitoring

Images

Adding an image

Put the file next to the page that uses it and reference it relatively:

![Architecture overview](./architecture.png)

A path starting with / is resolved from the root of the content directory instead, which is what you want for an image several pages share:

![Logo](/shared/logo.svg)

Either way Chronicle rewrites the URL at build time and appends a hash of the file's contents. That hash is why an image can be cached forever by a browser and still update the moment you change the file.

Images in public/ are different — they are served exactly as you put them there, with no rewriting and no optimization. Use public/ for a favicon or a download, and keep content images next to their pages.

Optimization

Everything below happens on its own. There is nothing to turn on.

Content images are resized, re-encoded to a modern format, and cached on disk, through an on-demand /api/image endpoint.

How it works

  1. The remark plugin rewrites all image URLs to route through /api/image
  2. On first request, the image is resized and converted based on browser support
  3. The result is cached — subsequent requests are served instantly
  4. On server start, all content images are pre-cached (warmup)

Format Negotiation

The endpoint reads the browser's Accept header and serves the best format:

Browser sendsFormat served
Accept: image/avifAVIF
Accept: image/webpWebP
NeitherOriginal (resized only)

SVG images are passed through unchanged.

Query Parameters

Control image output directly in markdown using query parameters:

![Screenshot](screenshot.png?w=640&q=90)

Width (w)

Sets the output width in pixels. The image is resized proportionally (height auto-calculated). Images are never enlarged beyond their original size.

Allowed values:

WidthUse case
320Small thumbnails, mobile icons
640Mobile content images
768Tablet content images
1024Default — desktop content
1280Wide content areas
1536Large displays
1920Full-width hero images

Default: 1024

Quality (q)

Sets the compression quality. Lower values produce smaller files with more compression artifacts.

Allowed values:

QualityFile sizeUse case
60SmallestThumbnails, previews
75BalancedDefault — content images
90High qualityScreenshots with text
100MaximumLossless-like output

Default: 75

Examples

<!-- Default: 1024w, quality 75 -->
![Overview](overview.png)

<!-- Small thumbnail -->
![Thumb](thumb.png?w=320&q=60)

<!-- High quality screenshot -->
![UI](dashboard.png?w=1280&q=90)

<!-- Width only, default quality -->
![Photo](photo.png?w=640)

<!-- Quality only, default width -->
![Chart](chart.png?q=90)

API Endpoint

GET /api/image?url=/_content/docs/photo.png&w=640&q=75
ParameterRequiredDescription
urlYesContent image path (must start with /_content/)
wYesOutput width (must be an allowed value)
qNoQuality 1-100 (snapped to nearest allowed value)

Response Headers

Content-Type: image/webp (or image/avif, or original mime)
Cache-Control: public, max-age=31536000, immutable
Vary: Accept

Cache

Optimized images are cached using Nitro storage with the fs driver at .cache/images/. Cache persists across server restarts.

The warmup process pre-caches all content images as WebP at default width (1024) and quality (75) when the server starts.

ComponentsLinks and redirects