@stati/core 1.27.2 → 1.29.0

package/README.md

@@ -166,7 +166,8 @@ Customize layouts with [Eta templates](https://eta.js.org):
 
 Only rebuild what changed:
 
-- Smart caching based on hashes of each page's content and templates
+- Smart caching based on hashes of each page's content and templates, and of the collection and navigation data it reads
+- Removal of pages that no longer exist, such as deleted posts and unused tag pages
 - TTL-based refresh for dynamic content
 - Tag-based invalidation for related content
 
@@ -183,6 +184,10 @@ await invalidate('path:/posts');
 await invalidate('age:3months');
 ```
 
+#### Collections, Pagination and Generated Pages
+
+A folder with an `index.md` is a collection: templates read its pages as `stati.collection`, sorted by date and grouped by tag. `paginate: 10` in front matter splits a listing into `/blog`, `/blog/page/2` and so on (`stati.pagination`), and a `[tag].md` template becomes one page per tag (`stati.generated`). See [Collections and generated pages](https://stati.build/core-concepts/collections).
+
 #### Built-In SEO
 
 SEO optimization works automatically with zero configuration:

package/dist/config/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error thrown when the Stati configuration is invalid.
+ * `loadConfig()` always rethrows it, because the build cannot proceed with a broken config.
+ */
+export declare class ConfigValidationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/config/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/config/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/config/errors.js

@@ -0,0 +1,10 @@
+/**
+ * Error thrown when the Stati configuration is invalid.
+ * `loadConfig()` always rethrows it, because the build cannot proceed with a broken config.
+ */
+export class ConfigValidationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ConfigValidationError';
+    }
+}

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6BrD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAqBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,CA8GlF"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA+BrD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAqBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,CA8HlF"}

package/dist/config/loader.js

@@ -2,6 +2,8 @@ import { existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { validateISGConfig, ISGConfigurationError } from '../core/isg/validation.js';
+import { validateImagesConfig } from '../images/config.js';
+import { ConfigValidationError } from './errors.js';
 import { compileStatiConfig, cleanupCompiledConfig } from '../core/utils/index.js';
 import { DEFAULT_SRC_DIR, DEFAULT_OUT_DIR, DEFAULT_STATIC_DIR, DEFAULT_SITE_TITLE, DEFAULT_DEV_BASE_URL, DEFAULT_TTL_SECONDS, DEFAULT_MAX_AGE_CAP_DAYS, CONFIG_FILE_PATTERNS, } from '../constants.js';
 /**
@@ -139,6 +141,16 @@ export async function loadConfig(cwd = process.cwd()) {
             }
             throw error; // Re-throw non-ISG errors
         }
+        // Validate image configuration
+        try {
+            validateImagesConfig(mergedConfig.images);
+        }
+        catch (error) {
+            if (error instanceof ConfigValidationError) {
+                throw new ConfigValidationError(`Invalid images configuration in ${configPath}:\n${error.message}`, { cause: error });
+            }
+            throw error;
+        }
         // Cache the loaded config with its modification time
         try {
             const mtime = statSync(resolvedConfigPath).mtimeMs;
@@ -154,8 +166,9 @@ export async function loadConfig(cwd = process.cwd()) {
         return mergedConfig;
     }
     catch (error) {
-        if (error instanceof Error && error.message.includes('Invalid ISG configuration')) {
-            // ISG validation errors should bubble up with context
+        if (error instanceof ConfigValidationError ||
+            (error instanceof Error && error.message.includes('Invalid ISG configuration'))) {
+            // Validation errors bubble up with context: the build cannot proceed with an invalid config
             throw error;
         }
         console.error(`Error loading config from ${configPath}:`, error);

package/dist/constants.d.ts

@@ -82,4 +82,30 @@ export declare const DEFAULT_BUNDLES: readonly [{
     readonly entryPoint: "main.ts";
     readonly bundleName: "main";
 }];
+/** Output directory for generated and copied images, relative to the build output */
+export declare const IMAGES_OUTPUT_DIR = "_img";
+/** Subdirectory of {@link IMAGES_OUTPUT_DIR} for generated Open Graph images */
+export declare const OG_IMAGES_SUBDIR = "og";
+/** Cache subdirectory (inside `.stati`) holding the images manifest */
+export declare const IMAGES_CACHE_SUBDIR = "images";
+/** Package that implements responsive images and Open Graph image generation */
+export declare const IMAGES_PACKAGE_NAME = "@stati/images";
+/** Default candidate widths for responsive images */
+export declare const DEFAULT_IMAGE_WIDTHS: readonly number[];
+/** Default modern formats for responsive images */
+export declare const DEFAULT_IMAGE_FORMATS: readonly ('avif' | 'webp')[];
+/** Default encoder quality per format; PNG stays lossless unless configured */
+export declare const DEFAULT_IMAGE_QUALITY: {
+    readonly avif: 50;
+    readonly webp: 75;
+    readonly jpeg: 80;
+};
+/** Default `sizes` attribute for responsive images */
+export declare const DEFAULT_IMAGE_SIZES = "100vw";
+/** Default Open Graph image template name */
+export declare const DEFAULT_OG_TEMPLATE = "og.eta";
+/** Default Open Graph image width in pixels */
+export declare const DEFAULT_OG_WIDTH = 1200;
+/** Default Open Graph image height in pixels */
+export declare const DEFAULT_OG_HEIGHT = 630;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,iDAAiD;AACjD,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,+CAA+C;AAC/C,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,iCAAiC;AACjC,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,4DAA4D;AAC5D,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC,kCAAkC;AAClC,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAIjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,iCAAkC,CAAC;AAEtE,mCAAmC;AACnC,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAE/C,2CAA2C;AAC3C,eAAO,MAAM,oBAAoB,UAEhC,CAAC;AAIF,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,kCAAkC;AAClC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,0BAAmD,CAAC;AAIrF,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAI9C,4BAA4B;AAC5B,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,0BAA0B;AAC1B,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AAExD,yBAAyB;AACzB,eAAO,MAAM,eAAe,QAAwB,CAAC;AAErD,0BAA0B;AAC1B,eAAO,MAAM,gBAAgB,QAAsB,CAAC;AAEpD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,QAAyB,CAAC;AAI3D,oDAAoD;AACpD,eAAO,MAAM,aAAa,QAAyB,CAAC;AAEpD,iDAAiD;AACjD,eAAO,MAAM,cAAc,QAA0B,CAAC;AAEtD,6CAA6C;AAC7C,eAAO,MAAM,UAAU,QAAmB,CAAC;AAE3C,iDAAiD;AACjD,eAAO,MAAM,WAAW,QAAuB,CAAC;AAEhD,uCAAuC;AACvC,eAAO,MAAM,WAAW,QAAsB,CAAC;AAE/C,2CAA2C;AAC3C,eAAO,MAAM,SAAS,QAAkB,CAAC;AAEzC,6CAA6C;AAC7C,eAAO,MAAM,UAAU,QAAmB,CAAC;AAI3C,kCAAkC;AAClC,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,+BAA+B;AAC/B,eAAO,MAAM,eAAe,eAAgC,CAAC;AAE7D,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAIvC,yBAAyB;AACzB,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,8CAA8C;AAC9C,eAAO,MAAM,cAAc,UAAU,CAAC;AAItC,0CAA0C;AAC1C,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,eAAe;;;EAA2D,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/constants.js

@@ -88,3 +88,26 @@ export const DEFAULT_TS_OUT_DIR = '_assets';
  * Creates a single global bundle from 'main.ts' entry point.
  */
 export const DEFAULT_BUNDLES = [{ entryPoint: 'main.ts', bundleName: 'main' }];
+// === Image Constants ===
+/** Output directory for generated and copied images, relative to the build output */
+export const IMAGES_OUTPUT_DIR = '_img';
+/** Subdirectory of {@link IMAGES_OUTPUT_DIR} for generated Open Graph images */
+export const OG_IMAGES_SUBDIR = 'og';
+/** Cache subdirectory (inside `.stati`) holding the images manifest */
+export const IMAGES_CACHE_SUBDIR = 'images';
+/** Package that implements responsive images and Open Graph image generation */
+export const IMAGES_PACKAGE_NAME = '@stati/images';
+/** Default candidate widths for responsive images */
+export const DEFAULT_IMAGE_WIDTHS = [480, 960, 1440];
+/** Default modern formats for responsive images */
+export const DEFAULT_IMAGE_FORMATS = ['avif', 'webp'];
+/** Default encoder quality per format; PNG stays lossless unless configured */
+export const DEFAULT_IMAGE_QUALITY = { avif: 50, webp: 75, jpeg: 80 };
+/** Default `sizes` attribute for responsive images */
+export const DEFAULT_IMAGE_SIZES = '100vw';
+/** Default Open Graph image template name */
+export const DEFAULT_OG_TEMPLATE = 'og.eta';
+/** Default Open Graph image width in pixels */
+export const DEFAULT_OG_WIDTH = 1200;
+/** Default Open Graph image height in pixels */
+export const DEFAULT_OG_HEIGHT = 630;

package/dist/core/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AA2DA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EASP,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACrC,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,sGAAsG;IACtG,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAkGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB5E"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AAuEA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EASP,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACrC,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,sGAAsG;IACtG,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAkGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB5E"}

package/dist/core/build.js

@@ -1,17 +1,20 @@
-import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, detectExistingBundles, autoInjectBundles, getBundlePathsForPage, formatBytes, } from './utils/index.js';
+import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, detectExistingBundles, autoInjectBundles, getBundlePathsForPage, formatBytes, isVirtualPage, getPageOutputFile, } from './utils/index.js';
 import { join, dirname, relative, posix } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { loadConfig } from '../config/loader.js';
 import { loadContent } from './content.js';
+import { expandPages } from './expand.js';
+import { createSummaryHasher, resolveCollectionPath, resolveSummaryFields, } from './collections.js';
 import { createMarkdownProcessor, renderMarkdown, extractToc } from './markdown.js';
 import { createTemplateEngine, renderPage } from './templates.js';
 import { buildNavigation } from './navigation.js';
-import { loadCacheManifest, saveCacheManifest, shouldRebuildPage, createCacheEntry, updateCacheEntry, withBuildLock, computeNavigationHash, computeContentHash, clearFileHashCache, clearTemplatePathCache, } from './isg/index.js';
+import { loadCacheManifest, saveCacheManifest, shouldRebuildPage, createCacheEntry, updateCacheEntry, hasRecordedReads, pruneOrphanedPages, withBuildLock, computeNavigationHash, computeContentHash, clearFileHashCache, clearTemplatePathCache, } from './isg/index.js';
 import { generateSitemap, generateRobotsTxtFromConfig, autoInjectSEO, } from '../seo/index.js';
 import { generateRSSFeeds, validateRSSConfig } from '../rss/index.js';
-import { computeSearchIndexFilename, generateSearchIndex, writeSearchIndex, autoInjectSearchMeta, } from '../search/index.js';
+import { computeSearchIndexFilename, generateSearchIndex, writeSearchIndex, autoInjectSearchMeta, isGeneratedPageExcludedFromSearch, } from '../search/index.js';
 import { getEnv, isDevelopment } from '../env.js';
 import { DEFAULT_OUT_DIR } from '../constants.js';
+import { ImageRuntime } from '../images/runtime.js';
 import { createMetricRecorder, noopMetricRecorder } from '../metrics/index.js';
 /**
  * Recursively calculates the total size of a directory in bytes.
@@ -179,12 +182,18 @@ async function setupCacheAndManifest(cacheDir) {
     return { manifest };
 }
 /**
- * Loads content and builds navigation.
+ * Loads content, expands generated and paginated pages, and builds navigation.
  */
 async function loadContentAndBuildNavigation(config, options, logger) {
-    // Load all content
-    const pages = await loadContent(config, options.includeDrafts);
-    logger.status(`Found ${pages.length} pages`);
+    // Load all content, then replace [param].md templates with their pages and add the
+    // pages of paginated listings. Navigation, SEO, sitemap and search see the result.
+    const loaded = await loadContent(config, options.includeDrafts);
+    const pages = await expandPages(loaded, config, logger);
+    const virtualCount = pages.filter((page) => isVirtualPage(page)).length;
+    logger.status(`Found ${pages.length - virtualCount} pages`);
+    if (virtualCount > 0) {
+        logger.status(`Generated ${virtualCount} more from templates and pagination`);
+    }
     // Build navigation from pages
     if (logger.step) {
         console.log(); // Add spacing before navigation step
@@ -201,12 +210,35 @@ async function loadContentAndBuildNavigation(config, options, logger) {
     // Create processors
     const md = await createMarkdownProcessor(config);
     const eta = createTemplateEngine(config);
-    return { pages, navigation, md, eta, navigationHash };
+    return { pages, markdownFiles: loaded.length, navigation, md, eta, navigationHash };
+}
+/**
+ * Output file and ISG cache key of a page.
+ */
+function getPageOutput(page, outDir) {
+    const outputPath = join(outDir, getPageOutputFile(page.url));
+    // Cache key is the output path relative to outDir
+    const relativePath = relative(outDir, outputPath).replace(/\\/g, '/');
+    const cacheKey = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+    return { outputPath, cacheKey };
+}
+/**
+ * Hashes a value for the render inputs, or returns a value that never matches when it
+ * cannot be serialized, so the page rebuilds instead of keeping stale output.
+ */
+function hashableData(value) {
+    try {
+        JSON.stringify(value);
+        return value ?? null;
+    }
+    catch {
+        return `unserializable:${Date.now()}:${Math.random()}`;
+    }
 }
 /**
  * Processes pages with ISG caching logic.
  */
-async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder, searchIndexFilename) {
+async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder, searchIndexFilename, imageRuntime = null, navigationHash = computeNavigationHash(navigation)) {
     let cacheHits = 0;
     let cacheMisses = 0;
     const searchablePages = [];
@@ -218,6 +250,18 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         await config.hooks.beforeAll(buildContext);
         endHookBeforeAll();
     }
+    // Collection summaries, hashed after beforeAll because the hook can change front matter
+    const summaries = createSummaryHasher(pages, resolveSummaryFields(config));
+    // The pages of a listing share one array of page URLs, hashed once for all of them
+    const urlListHashes = new WeakMap();
+    const hashUrlList = (urls) => {
+        let hash = urlListHashes.get(urls);
+        if (hash === undefined) {
+            hash = computeContentHash('', { urls });
+            urlListHashes.set(urls, hash);
+        }
+        return hash;
+    };
     // Render each page with progress tracking and ISG
     if (logger.step) {
         logger.step(2, 3, 'Rendering pages');
@@ -236,24 +280,14 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
     const isDevMode = isDevelopment();
     const pendingWrites = [];
     const pendingCacheUpdates = [];
+    // Image settings that change generated HTML, part of every page's render inputs
+    const imageFingerprint = imageRuntime?.fingerprint();
     for (let i = 0; i < pages.length; i++) {
         const page = pages[i];
         if (!page)
             continue; // Safety check
-        // Determine output path
-        let outputPath;
-        if (page.url === '/') {
-            outputPath = join(outDir, 'index.html');
-        }
-        else if (page.url.endsWith('/')) {
-            outputPath = join(outDir, page.url, 'index.html');
-        }
-        else {
-            outputPath = join(outDir, `${page.url}.html`);
-        }
-        // Get cache key (use output path relative to outDir)
-        const relativePath = relative(outDir, outputPath).replace(/\\/g, '/');
-        const cacheKey = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+        // Determine output path and cache key
+        const { outputPath, cacheKey } = getPageOutput(page, outDir);
         const existingEntry = manifest.entries[cacheKey];
         const bundlePaths = getBundlePathsForPage(page.url, compiledBundles);
         const assets = {
@@ -263,16 +297,58 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
                 searchIndexPath: `/${searchIndexFilename}`,
             }),
         };
-        const renderInputsHash = computeContentHash('', {
+        // Collection the page sees as stati.collection; a page whose collection appears,
+        // disappears or changes rebuilds even when it never read it
+        const collectionPath = resolveCollectionPath(page, pages);
+        const staticRenderInputs = {
             ...assets,
             bundleAutoInject: config.typescript?.autoInject !== false,
             searchAutoInject: config.search?.autoInjectMetaTag !== false,
+            // Omitted with images: false, so the hash matches builds without the image pipeline
+            ...(imageFingerprint && { images: imageFingerprint }),
+            collection: collectionPath ?? null,
+            // A listing page depends on its own slice and on the page count, which every page
+            // shows in its numbered links
+            ...(page.pagination && {
+                pagination: {
+                    pageNumber: page.pagination.pageNumber,
+                    totalPages: page.pagination.totalPages,
+                    urls: hashUrlList(page.pagination.urls),
+                    items: summaries.pages(page.pagination.items),
+                },
+            }),
+            // A generated page depends on its own items only, not on the whole collection
+            ...(page.generated && {
+                generated: {
+                    key: page.generated.key,
+                    label: page.generated.label,
+                    template: page.generated.template,
+                    items: summaries.pages(page.generated.items),
+                    data: hashableData(page.generated.data),
+                },
+            }),
+        };
+        // The data a render read: the collection summary and the navigation tree
+        const renderInputsHashFor = (reads) => computeContentHash('', {
+            ...staticRenderInputs,
+            ...(reads?.collection && {
+                collectionSummary: collectionPath !== undefined ? summaries.collection(collectionPath) : 'none',
+            }),
+            ...(reads?.nav && { navigation: navigationHash }),
         });
+        // Entries written before Stati recorded what pages read are rebuilt once to record it
+        const readsKnown = existingEntry !== undefined && hasRecordedReads(existingEntry);
+        const renderInputsHash = renderInputsHashFor(readsKnown
+            ? { collection: existingEntry.readsCollection, nav: existingEntry.readsNav }
+            : undefined);
         // Check if we should rebuild this page (considering ISG logic)
         const shouldRebuildStart = performance.now();
         const shouldRebuild = options.force ||
             config.isg?.enabled === false ||
             !(await pathExists(outputPath)) ||
+            (existingEntry !== undefined && !readsKnown) ||
+            // A cached page whose generated images are gone is rebuilt to regenerate them
+            (imageRuntime !== null && !imageRuntime.outputsExist(existingEntry?.images)) ||
             (await shouldRebuildPage(page, existingEntry, config, pages, buildTime, renderInputsHash));
         const shouldRebuildTime = performance.now() - shouldRebuildStart;
         totalShouldRebuildTime += shouldRebuildTime;
@@ -286,7 +362,7 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             recorder.recordPageTiming(page.url, 0, true);
             // Collect searchable page data for cached pages if search is enabled
             // Extract TOC without full HTML rendering for efficiency
-            if (config.search?.enabled === true) {
+            if (config.search?.enabled === true && !isGeneratedPageExcludedFromSearch(page)) {
                 const tocEnabled = config.markdown?.toc !== false;
                 const toc = tocEnabled ? extractToc(page.content, md) : [];
                 searchablePages.push({ page, toc, markdownContent: page.content });
@@ -302,12 +378,16 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             await config.hooks.beforeRender({ page, config });
             recorder.addToPhase('hookBeforeRenderTotalMs', performance.now() - hookStart);
         }
+        // Image state for this page: markup, dependencies and generated files
+        const pageImages = imageRuntime?.createPageContext(page);
         // Render markdown to HTML with TOC extraction
         const tocEnabled = config.markdown?.toc !== false;
-        const { html: htmlContent, toc } = renderMarkdown(page.content, md, tocEnabled);
+        const { html: htmlContent, toc } = renderMarkdown(page.content, md, tocEnabled, {
+            images: pageImages,
+        });
         // Render with template
         const renderPageStart = performance.now();
-        const renderResult = await renderPage(page, htmlContent, config, eta, navigation, pages, assets, toc, logger);
+        const renderResult = await renderPage(page, htmlContent, config, eta, navigation, pages, assets, toc, logger, { images: pageImages });
         const renderPageTime = performance.now() - renderPageStart;
         totalRenderTime += renderPageTime;
         let finalHtml = renderResult.html;
@@ -324,6 +404,9 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             if (config.seo?.debug !== undefined) {
                 injectOptions.debug = config.seo.debug;
             }
+            if (renderResult.ogImage) {
+                injectOptions.generatedImage = renderResult.ogImage;
+            }
             finalHtml = autoInjectSEO(finalHtml, injectOptions);
         }
         // Auto-inject search index meta tag if enabled (default: true)
@@ -336,6 +419,17 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         if (config.typescript?.autoInject !== false && assets.bundlePaths.length > 0) {
             finalHtml = autoInjectBundles(finalHtml, assets.bundlePaths);
         }
+        // Start the image jobs the final HTML needs and record its image files for the cache,
+        // along with what the render read, which decides the hash it is stored under
+        const committedImages = pageImages && imageRuntime
+            ? imageRuntime.commitPage(pageImages, finalHtml, { outputPath, cacheKey })
+            : undefined;
+        const renderedAssets = {
+            assetDeps: committedImages?.assetDeps ?? [],
+            images: committedImages?.images ?? [],
+            reads: renderResult.reads,
+        };
+        const renderedInputsHash = renderInputsHashFor(renderResult.reads);
         const renderTime = Math.round(performance.now() - startTime);
         // Record page timing for rendered pages (includes template count)
         recorder.recordPageTiming(page.url, renderTime, false, renderResult.templatesLoaded);
@@ -345,7 +439,13 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         // In dev mode, batch writes for parallel execution to avoid Windows filesystem slowdown
         if (isDevMode) {
             pendingWrites.push({ outputPath, content: finalHtml });
-            pendingCacheUpdates.push({ cacheKey, page, existingEntry, renderInputsHash });
+            pendingCacheUpdates.push({
+                cacheKey,
+                page,
+                existingEntry,
+                renderInputsHash: renderedInputsHash,
+                renderedAssets,
+            });
         }
         else {
             // Production mode: write immediately
@@ -357,17 +457,17 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             if (!options.skipCacheUpdate) {
                 const cacheEntryStart = performance.now();
                 if (existingEntry) {
-                    manifest.entries[cacheKey] = await updateCacheEntry(existingEntry, page, config, pages, buildTime, false, renderInputsHash);
+                    manifest.entries[cacheKey] = await updateCacheEntry(existingEntry, page, config, pages, buildTime, false, renderedInputsHash, renderedAssets);
                 }
                 else {
-                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderInputsHash);
+                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderedInputsHash, renderedAssets);
                 }
                 totalCacheEntryTime += performance.now() - cacheEntryStart;
             }
         }
         // Collect searchable page data if search is enabled
         // Uses TOC entries and markdown content instead of parsing rendered HTML
-        if (config.search?.enabled === true) {
+        if (config.search?.enabled === true && !isGeneratedPageExcludedFromSearch(page)) {
             searchablePages.push({ page, toc, markdownContent: page.content });
         }
         // Run afterRender hook
@@ -390,14 +490,14 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         // This avoids expensive template dependency tracking on each incremental rebuild
         if (!options.skipCacheUpdate) {
             const cacheEntryStart = performance.now();
-            for (const { cacheKey, page, existingEntry, renderInputsHash } of pendingCacheUpdates) {
+            for (const { cacheKey, page, existingEntry, renderInputsHash, renderedAssets, } of pendingCacheUpdates) {
                 if (existingEntry) {
                     // Fast update: reuse existing deps, just update hashes and timestamp
                     manifest.entries[cacheKey] = await updateCacheEntry(existingEntry, page, config, pages, buildTime, true, // fastUpdate = true in dev mode
-                    renderInputsHash);
+                    renderInputsHash, renderedAssets);
                 }
                 else {
-                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderInputsHash);
+                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderInputsHash, renderedAssets);
                 }
             }
             totalCacheEntryTime = performance.now() - cacheEntryStart;
@@ -501,6 +601,14 @@ async function buildInternal(options = {}) {
         await remove(cacheDir);
     }
     await ensureDir(outDir);
+    // Image pipeline; null with images: false. Fails here, before any page renders, when a
+    // feature needs @stati/images and it is missing or incompatible.
+    const imageRuntime = await ImageRuntime.create(config, {
+        outDir,
+        cacheDir,
+        logger,
+        development: isDevelopment(),
+    });
     // Enable Tailwind class inventory tracking only if Tailwind is detected
     const tailwindInitStart = performance.now();
     const hasTailwind = await isTailwindUsed();
@@ -534,14 +642,13 @@ async function buildInternal(options = {}) {
         console.log(); // Add spacing before content loading
     }
     const endContentSpan = recorder.startSpan('contentDiscoveryMs');
-    const { pages, navigation, md, eta, navigationHash } = await loadContentAndBuildNavigation(config, options, logger);
+    const { pages, markdownFiles, navigation, md, eta, navigationHash } = await loadContentAndBuildNavigation(config, options, logger);
     endContentSpan();
-    // Record content discovery counts.
-    // Both totalPages and markdownFilesProcessed are incremented by pages.length
-    // because loadContent() only processes *.md files, so all pages are markdown files.
+    // Record content discovery counts. Pages include the ones generated from [param].md
+    // templates and pagination; Markdown files include the templates.
     recorder.increment('totalPages', pages.length);
-    recorder.increment('markdownFilesProcessed', pages.length);
-    // Store navigation hash in manifest for change detection in dev server
+    recorder.increment('markdownFilesProcessed', markdownFiles);
+    // Recorded in the manifest; pages that read the navigation also hash it into their inputs
     manifest.navigationHash = navigationHash;
     // Compile TypeScript if enabled
     // In dev mode, skip compilation since esbuild watcher handles it
@@ -593,9 +700,40 @@ async function buildInternal(options = {}) {
     }
     const endPageRenderSpan = recorder.startSpan('pageRenderingMs');
     const buildTime = new Date();
-    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder, searchIndexFilename);
+    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder, searchIndexFilename, imageRuntime, navigationHash);
     endPageRenderSpan();
     const { cacheHits, cacheMisses, searchablePages } = pageProcessingResult;
+    // Remove the output of pages that no longer exist, such as a deleted post or a tag no post
+    // uses anymore. Runs before static assets are copied, so a file in the static directory at
+    // the same path is copied afterwards.
+    const liveCacheKeys = new Set(pages.map((page) => getPageOutput(page, outDir).cacheKey));
+    const pruned = await pruneOrphanedPages(manifest, liveCacheKeys, outDir);
+    for (const failure of pruned.failed) {
+        logger.warning(`Could not remove the stale page ${failure.key}: ${failure.message}`);
+    }
+    if (pruned.removed.length > 0) {
+        const count = pruned.removed.length;
+        logger.info(count === 1
+            ? 'Removed 1 page that no longer exists'
+            : `Removed ${count} pages that no longer exist`);
+    }
+    // Wait for image jobs; pages whose images failed are rewritten to show plain images
+    let imageFailures = [];
+    if (imageRuntime) {
+        const endImageSpan = recorder.startSpan('imageSettleMs');
+        const settled = await imageRuntime.settle(manifest);
+        await imageRuntime.save();
+        endImageSpan();
+        imageFailures = settled.failures;
+        const { generated, cached, failed } = imageRuntime.stats;
+        recorder.increment('imagesGenerated', generated);
+        recorder.increment('imagesCached', cached);
+        recorder.increment('imagesFailed', failed);
+        if (generated > 0 || failed > 0) {
+            logger.info('');
+            logger.info(`Images: ${generated} generated, ${cached} reused${failed > 0 ? `, ${failed} failed` : ''}`);
+        }
+    }
     // Generate search index if enabled
     // Uses markdown content and TOC entries
     let searchIndexMetadata;
@@ -638,6 +776,13 @@ async function buildInternal(options = {}) {
         await saveCacheManifest(cacheDir, manifest);
     }
     endManifestSaveSpan();
+    // In the dev server a failed Open Graph image goes to the error overlay, like a template error
+    const ogFailures = imageFailures.filter((failure) => failure.og);
+    if (isDevMode && ogFailures.length > 0) {
+        throw new Error(ogFailures
+            .map((failure) => `Open Graph image failed for ${failure.label}: ${failure.message}`)
+            .join('\n'));
+    }
     // Copy static assets and count them (skip for template-only changes in dev mode)
     const endAssetSpan = recorder.startSpan('assetCopyMs');
     let assetsCount = 0;
@@ -646,6 +791,21 @@ async function buildInternal(options = {}) {
     }
     endAssetSpan();
     recorder.increment('assetsCopied', assetsCount);
+    // Delete generated images no page of this build uses. Production only: dev builds skip
+    // responsive and Open Graph images by default and must not delete them.
+    if (imageRuntime && getEnv() === 'production') {
+        const liveImages = new Set();
+        const liveSources = new Set();
+        for (const page of pages) {
+            const entry = manifest.entries[getPageOutput(page, outDir).cacheKey];
+            entry?.images?.forEach((image) => liveImages.add(image));
+            entry?.assetDeps?.forEach((source) => liveSources.add(source));
+        }
+        const removed = await imageRuntime.prune(liveImages, liveSources);
+        if (removed > 0) {
+            logger.info(`Removed ${removed} unused generated image${removed === 1 ? '' : 's'}`);
+        }
+    }
     // Get current environment
     const currentEnv = getEnv();
     // Generate sitemap if enabled (only in production mode)