@stati/core 1.29.2 → 2.0.0

package/dist/core/utils/template-errors.utils.js

@@ -92,6 +92,34 @@ export class TemplateError extends Error {
         return errorDetails;
     }
 }
+/**
+ * Thrown by Stati's template functions, such as `stati.include()` and `stati.layout()`, for a
+ * mistake at the call: an unknown template name, props that are not an object, Eta's own
+ * `include()`. Thrown inside a template, so Eta's debug mode adds the calling template and line
+ * to the message, and keeps this error as its `cause`.
+ */
+export class TemplateUsageError extends Error {
+    /** Fixes to show in the error overlay */
+    suggestions;
+    constructor(message, suggestions = []) {
+        super(message);
+        this.name = 'TemplateUsageError';
+        this.suggestions = suggestions;
+    }
+}
+/**
+ * The errors an error wraps through `cause`, outermost first. Eta 4 sets `cause` on the errors
+ * its debug mode rethrows, once per template the error passes through.
+ */
+function causeChain(error) {
+    const chain = [];
+    let current = error;
+    while (current instanceof Error && !chain.includes(current) && chain.length < 64) {
+        chain.push(current);
+        current = current.cause;
+    }
+    return chain;
+}
 /**
  * Header that Eta's debug mode prepends to runtime errors:
  * `<path>:<line>` (or `line <line>` without a path), a numbered excerpt of the
@@ -106,14 +134,19 @@ const CONTEXT_ROOT_NAMES = new Set([
     'site',
     'page',
     'content',
+    'body',
     'nav',
-    'partials',
     'collection',
+    'pagination',
+    'generated',
     'props',
+    'helpers',
     'assets',
     'generator',
     'generateSEO',
     'propValue',
+    'slugify',
+    'image',
 ]);
 function getReferenceErrorSuggestions(message) {
     const name = message.match(/^(\S+) is not defined$/)?.[1];
@@ -155,10 +188,14 @@ export function parseEtaError(error, templatePath) {
     }
     let suggestions = [];
     const unknownProperty = parseUnknownPropertyMessage(message);
+    const usageError = causeChain(error).find((cause) => cause instanceof TemplateUsageError);
     if (unknownProperty) {
         message = unknownProperty.message;
         suggestions = unknownProperty.suggestions;
     }
+    else if (usageError) {
+        suggestions = [...usageError.suggestions];
+    }
     else if (error.name === 'ReferenceError') {
         suggestions = getReferenceErrorSuggestions(message);
     }
@@ -178,11 +215,15 @@ export function parseEtaError(error, templatePath) {
     return new TemplateError(message, filePath, line, column, undefined, suggestions);
 }
 /**
- * Enhances a generic error with template-specific context.
+ * Enhances a generic error with template-specific context. An error that wraps a
+ * {@link TemplateError}, as Eta's debug mode does for an error from a nested template, returns
+ * the innermost one, which points at the template that failed.
  */
 export function createTemplateError(error, templatePath, _line, _column) {
-    if (error instanceof TemplateError) {
-        return error;
+    const chain = causeChain(error);
+    const innermost = chain.reverse().find((cause) => cause instanceof TemplateError);
+    if (innermost) {
+        return innermost;
     }
     return parseEtaError(error, templatePath);
 }

package/dist/core/utils/theme.utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Look of the pages Stati shows about its own work: the development error overlay and the
+ * build metrics report. Both follow the design of the Stati documentation site: slate neutrals,
+ * one blue accent and hairline rules, in a light and a dark theme.
+ */
+/** The Stati mark, a lightning bolt, as an SVG path on a 24 by 24 grid */
+export declare const STATI_MARK_PATH = "M13 10V3L4 14h7v7l9-11h-7z";
+/** Inline favicon, so these pages never request the site's own favicon. */
+export declare const STATI_FAVICON_HREF: string;
+/**
+ * Color tokens as RGB channels, for `rgb(var(--ink))` and `rgb(var(--ink) / 0.4)`, in the light
+ * theme and, when the system asks for it, the dark theme; and the three font stacks.
+ */
+export declare const STATI_THEME_STYLES = "\n    :root {\n      --canvas: 255 255 255;\n      --raised: 248 250 252;\n      --sunken: 246 248 250;\n      --ink: 11 13 18;\n      --muted: 71 85 105;\n      --faint: 91 101 119;\n      --line: 226 232 240;\n      --line-strong: 203 213 225;\n      --accent: 37 99 235;\n      --accent-ink: 29 78 216;\n      --on-accent: 255 255 255;\n      --danger: 185 28 28;\n      --danger-wash: 254 242 242;\n      color-scheme: light;\n      --font-display: 'Archivo', 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;\n      --font-sans: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n      --font-mono: 'Fira Code', ui-monospace, 'Cascadia Code', Menlo, Monaco, Consolas, 'Liberation Mono', monospace;\n    }\n\n    @media (prefers-color-scheme: dark) {\n      :root {\n        --canvas: 2 6 23;\n        --raised: 15 23 42;\n        --sunken: 11 18 32;\n        --ink: 241 245 249;\n        --muted: 148 163 184;\n        --faint: 131 145 167;\n        --line: 30 41 59;\n        --line-strong: 51 65 85;\n        --accent: 96 165 250;\n        --accent-ink: 147 197 253;\n        --on-accent: 2 6 23;\n        --danger: 248 113 113;\n        --danger-wash: 38 12 20;\n        color-scheme: dark;\n      }\n    }";
+/** The light theme on paper, so a page viewed in the dark theme does not print light on white. */
+export declare const STATI_PRINT_STYLES = "\n    @media print {\n      :root {\n      --canvas: 255 255 255;\n      --raised: 248 250 252;\n      --sunken: 246 248 250;\n      --ink: 11 13 18;\n      --muted: 71 85 105;\n      --faint: 91 101 119;\n      --line: 226 232 240;\n      --line-strong: 203 213 225;\n      --accent: 37 99 235;\n      --accent-ink: 29 78 216;\n      --on-accent: 255 255 255;\n      --danger: 185 28 28;\n      --danger-wash: 254 242 242;\n      color-scheme: light;\n      }\n    }";
+//# sourceMappingURL=theme.utils.d.ts.map

package/dist/core/utils/theme.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/theme.utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAE5D,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,QAE5B,CAAC;AAkBJ;;;GAGG;AACH,eAAO,MAAM,kBAAkB,yvCAwBzB,CAAC;AAEP,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,wdAIzB,CAAC"}

package/dist/core/utils/theme.utils.js

@@ -0,0 +1,59 @@
+/**
+ * Look of the pages Stati shows about its own work: the development error overlay and the
+ * build metrics report. Both follow the design of the Stati documentation site: slate neutrals,
+ * one blue accent and hairline rules, in a light and a dark theme.
+ */
+/** The Stati mark, a lightning bolt, as an SVG path on a 24 by 24 grid */
+export const STATI_MARK_PATH = 'M13 10V3L4 14h7v7l9-11h-7z';
+/** Inline favicon, so these pages never request the site's own favicon. */
+export const STATI_FAVICON_HREF = `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#2563eb" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${STATI_MARK_PATH}"/></svg>`)}`;
+const LIGHT_COLORS = `
+      --canvas: 255 255 255;
+      --raised: 248 250 252;
+      --sunken: 246 248 250;
+      --ink: 11 13 18;
+      --muted: 71 85 105;
+      --faint: 91 101 119;
+      --line: 226 232 240;
+      --line-strong: 203 213 225;
+      --accent: 37 99 235;
+      --accent-ink: 29 78 216;
+      --on-accent: 255 255 255;
+      --danger: 185 28 28;
+      --danger-wash: 254 242 242;
+      color-scheme: light;`;
+/**
+ * Color tokens as RGB channels, for `rgb(var(--ink))` and `rgb(var(--ink) / 0.4)`, in the light
+ * theme and, when the system asks for it, the dark theme; and the three font stacks.
+ */
+export const STATI_THEME_STYLES = `
+    :root {${LIGHT_COLORS}
+      --font-display: 'Archivo', 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+      --font-sans: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      --font-mono: 'Fira Code', ui-monospace, 'Cascadia Code', Menlo, Monaco, Consolas, 'Liberation Mono', monospace;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --canvas: 2 6 23;
+        --raised: 15 23 42;
+        --sunken: 11 18 32;
+        --ink: 241 245 249;
+        --muted: 148 163 184;
+        --faint: 131 145 167;
+        --line: 30 41 59;
+        --line-strong: 51 65 85;
+        --accent: 96 165 250;
+        --accent-ink: 147 197 253;
+        --on-accent: 2 6 23;
+        --danger: 248 113 113;
+        --danger-wash: 38 12 20;
+        color-scheme: dark;
+      }
+    }`;
+/** The light theme on paper, so a page viewed in the dark theme does not print light on white. */
+export const STATI_PRINT_STYLES = `
+    @media print {
+      :root {${LIGHT_COLORS}
+      }
+    }`;

package/dist/images/index.d.ts

@@ -6,9 +6,8 @@
 export { resolveImagesConfig, validateImagesConfig } from './config.js';
 export type { ResolvedImagesConfig, ResolvedResponsiveConfig, ResolvedOgConfig } from './config.js';
 export { ImageRuntime, PageImages, validateOgBaseUrl } from './runtime.js';
-export type { StatiImageOptions, SettleResult, ImageRuntimeOptions } from './runtime.js';
+export type { StatiImageOptions, SettleResult, ImageRuntimeOptions, OgTemplateRenderer, } from './runtime.js';
 export { installImageRule, selectEagerImage } from './markdown-rule.js';
-export { findOgTemplatePath, clearOgTemplateCache } from './og.js';
 export { loadImageProvider, resolveImagesPackage, missingPackageMessage } from './provider.js';
 export { probeImage } from './utils/index.js';
 export type { ImageProbeResult } from './utils/index.js';

package/dist/images/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/images/index.js

@@ -6,6 +6,5 @@
 export { resolveImagesConfig, validateImagesConfig } from './config.js';
 export { ImageRuntime, PageImages, validateOgBaseUrl } from './runtime.js';
 export { installImageRule, selectEagerImage } from './markdown-rule.js';
-export { findOgTemplatePath, clearOgTemplateCache } from './og.js';
 export { loadImageProvider, resolveImagesPackage, missingPackageMessage } from './provider.js';
 export { probeImage } from './utils/index.js';

package/dist/images/markdown-rule.d.ts

@@ -2,8 +2,7 @@
  * The markdown-it `image` rule that adds dimensions, lazy loading and responsive variants.
  * @module images/markdown-rule
  */
-import type MarkdownIt from 'markdown-it';
-import type Token from 'markdown-it/lib/token.mjs';
+import type { MarkdownIt, Token } from 'markdown-it';
 /** Key of the page's image state in the markdown-it `env`. */
 export declare const IMAGES_ENV_KEY = "statiImages";
 /**

package/dist/images/markdown-rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-rule.d.ts","sourceRoot":"","sources":["../../src/images/markdown-rule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,UAAU,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,MAAM,2BAA2B,CAAC;AAGnD,8DAA8D;AAC9D,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAO5C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAwBrD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,SAAS,CAanE"}
+{"version":3,"file":"markdown-rule.d.ts","sourceRoot":"","sources":["../../src/images/markdown-rule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGrD,8DAA8D;AAC9D,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAO5C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAwBrD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,SAAS,CAanE"}

package/dist/images/og.d.ts

@@ -1,22 +1,9 @@
 /**
- * Helpers for Open Graph image generation: template lookup, exclusions and inlining.
+ * Helpers for Open Graph image generation: exclusions and inlining. Core finds a page's
+ * template through the template index, nearest folder first.
  * @module images/og
  */
 import type { PageModel } from '../types/index.js';
-/**
- * Clears the Open Graph template lookup cache.
- */
-export declare function clearOgTemplateCache(): void;
-/**
- * Finds the Open Graph template for a page: the nearest file named `templateName` in the
- * page's directory or one of its parents, up to the source directory.
- *
- * @param pageSourcePath - Absolute path of the page's Markdown file
- * @param srcDir - Absolute source directory
- * @param templateName - Template file name, such as `og.eta`
- * @returns Absolute path of the template, or null when there is none
- */
-export declare function findOgTemplatePath(pageSourcePath: string, srcDir: string, templateName: string): Promise<string | null>;
 /**
  * Whether a page gets no generated Open Graph image: it sets its own image in front matter
  * (`seo.openGraph.image`, or `false` to have none) or matches an `exclude` pattern.

package/dist/images/og.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"og.d.ts","sourceRoot":"","sources":["../../src/images/og.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAKnD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAOtF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU/C;AAsCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACrD,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwC5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE"}
+{"version":3,"file":"og.d.ts","sourceRoot":"","sources":["../../src/images/og.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAOtF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU/C;AAsCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACrD,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwC5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/images/og.js

@@ -1,54 +1,11 @@
 /**
- * Helpers for Open Graph image generation: template lookup, exclusions and inlining.
+ * Helpers for Open Graph image generation: exclusions and inlining. Core finds a page's
+ * template through the template index, nearest folder first.
  * @module images/og
  */
-import { dirname, extname, join, relative, resolve } from 'node:path';
-import { isPathWithinDirectory, pathExists, readFileBuffer } from '../core/utils/index.js';
+import { extname, join, relative, resolve } from 'node:path';
+import { isPathWithinDirectory, readFileBuffer } from '../core/utils/index.js';
 import { matchesGlob } from '../core/utils/glob-patterns.utils.js';
-/** Cache of template lookups per directory, cleared at the start of each build. */
-const templateCache = new Map();
-/**
- * Clears the Open Graph template lookup cache.
- */
-export function clearOgTemplateCache() {
-    templateCache.clear();
-}
-/**
- * Finds the Open Graph template for a page: the nearest file named `templateName` in the
- * page's directory or one of its parents, up to the source directory.
- *
- * @param pageSourcePath - Absolute path of the page's Markdown file
- * @param srcDir - Absolute source directory
- * @param templateName - Template file name, such as `og.eta`
- * @returns Absolute path of the template, or null when there is none
- */
-export async function findOgTemplatePath(pageSourcePath, srcDir, templateName) {
-    const root = resolve(srcDir);
-    let dir = dirname(resolve(pageSourcePath));
-    const visited = [];
-    while (isPathWithinDirectory(root, dir)) {
-        const cacheKey = `${dir}|${templateName}`;
-        if (templateCache.has(cacheKey)) {
-            const cached = templateCache.get(cacheKey);
-            for (const key of visited)
-                templateCache.set(key, cached);
-            return cached;
-        }
-        visited.push(cacheKey);
-        const candidate = join(dir, templateName);
-        if (await pathExists(candidate)) {
-            for (const key of visited)
-                templateCache.set(key, candidate);
-            return candidate;
-        }
-        if (dir === root)
-            break;
-        dir = dirname(dir);
-    }
-    for (const key of visited)
-        templateCache.set(key, null);
-    return null;
-}
 /**
  * Whether a page gets no generated Open Graph image: it sets its own image in front matter
  * (`seo.openGraph.image`, or `false` to have none) or matches an `exclude` pattern.

package/dist/images/runtime.d.ts

@@ -3,13 +3,32 @@
  * written pages need, recovers from failed jobs and prunes outputs no page uses.
  * @module images/runtime
  */
-import type { Eta } from 'eta';
-import type Token from 'markdown-it/lib/token.mjs';
+import type { Token } from 'markdown-it';
 import type { CacheManifest, GeneratedOgImage, ImageProvider, Logger, OgFont, PageModel, StatiConfig } from '../types/index.js';
 import type { RenderedAssets } from '../core/isg/builder.js';
 import { type ResolvedImagesConfig, type ResolvedOgConfig, type ResolvedResponsiveConfig } from './config.js';
 import { type SourceInfo } from './sources.js';
 import { type CopyPlan, type VariantPlan } from './plan.js';
+/**
+ * Finds and renders a page's Open Graph template, for {@link PageImages.renderOg}. Core's
+ * renderer resolves the template through the template index and renders it like any other
+ * template, so it can use `stati.include()` and `stati.layout()`.
+ */
+export interface OgTemplateRenderer {
+    /**
+     * Finds the page's template by file name, such as `og.eta`: the nearest one in the page's
+     * folder or a parent folder.
+     *
+     * @returns The template's absolute path, or null when there is none
+     */
+    find(templateName: string): string | null;
+    /** Renders a template that `find` returned, or the source of the built-in template */
+    render(template: {
+        path: string;
+    } | {
+        source: string;
+    }): Promise<string>;
+}
 /**
  * Options for `stati.image()` in templates.
  */
@@ -119,11 +138,11 @@ export declare class PageImages {
     /**
      * Renders this page's Open Graph template and registers the card.
      *
-     * @param context - Template context: the layout's, with an empty body and `stati.og`
-     * @param eta - The template engine
+     * @param renderer - Finds the page's template and renders it, or the built-in template, with
+     *   the layout's values, an empty body and `stati.og`
      * @returns The generated image, or null when the page gets none
      */
-    renderOg(context: object, eta: Eta): Promise<GeneratedOgImage | null>;
+    renderOg(renderer: OgTemplateRenderer): Promise<GeneratedOgImage | null>;
 }
 /**
  * Options for {@link ImageRuntime.create}.

package/dist/images/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/images/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/images/runtime.ts"],"names":[],"mappings":"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"}

package/dist/images/runtime.js

@@ -17,7 +17,7 @@ import { getSourceCacheEntries, inspectSourceSync, seedSourceCache, } from './so
 import { resolveImageSource } from './resolve.js';
 import { planCopy, planVariants } from './plan.js';
 import { renderImg, renderResponsiveImage } from './markup.js';
-import { displayTemplatePath, findOgTemplatePath, inlineLocalImages, isOgImageExcluded, ogImageSlug, } from './og.js';
+import { displayTemplatePath, inlineLocalImages, isOgImageExcluded, ogImageSlug } from './og.js';
 /**
  * Bumped when the generated markup changes, so pages rendered by an older pipeline rebuild.
  */
@@ -104,10 +104,13 @@ export class PageImages {
      *   is left as authored
      */
     renderMarkdownImage(token, alt) {
-        const attributes = (token.attrs ?? []).filter(([name]) => !['src', 'alt', 'title', 'width', 'height'].includes(name.toLowerCase()));
-        return this.renderImage(token.attrGet('src') ?? '', {
+        // markdown-it types attribute values as string | number; Stati handles them as text
+        const attributes = (token.attrs ?? [])
+            .filter(([name]) => !['src', 'alt', 'title', 'width', 'height'].includes(name.toLowerCase()))
+            .map(([name, value]) => [name, String(value)]);
+        return this.renderImage(token.attrGet('src')?.toString() ?? '', {
             alt,
-            title: token.attrGet('title') ?? undefined,
+            title: token.attrGet('title')?.toString(),
             attributes,
             width: token.attrGet('width') ?? undefined,
             height: token.attrGet('height') ?? undefined,
@@ -212,18 +215,18 @@ export class PageImages {
     /**
      * Renders this page's Open Graph template and registers the card.
      *
-     * @param context - Template context: the layout's, with an empty body and `stati.og`
-     * @param eta - The template engine
+     * @param renderer - Finds the page's template and renders it, or the built-in template, with
+     *   the layout's values, an empty body and `stati.og`
      * @returns The generated image, or null when the page gets none
      */
-    async renderOg(context, eta) {
+    async renderOg(renderer) {
         const { og, ogState, provider } = this.runtime;
         if (!og || !ogState || !provider?.renderOgImage)
             return null;
         if (isOgImageExcluded(this.page, og.exclude))
             return null;
         const srcDir = this.runtime.srcDir;
-        const templatePath = await findOgTemplatePath(this.page.sourcePath, srcDir, og.template);
+        const templatePath = renderer.find(og.template);
         if (!templatePath && !ogState.defaultTemplate)
             return null;
         const templateLabel = templatePath
@@ -231,9 +234,7 @@ export class PageImages {
             : 'built-in Open Graph template';
         let html;
         try {
-            html = templatePath
-                ? await eta.renderAsync(toPosix(relative(srcDir, templatePath)), context)
-                : await eta.renderStringAsync(ogState.defaultTemplate, context);
+            html = await renderer.render(templatePath ? { path: templatePath } : { source: ogState.defaultTemplate });
         }
         catch (error) {
             const failure = error instanceof Error ? error : new Error(String(error));
@@ -423,7 +424,8 @@ export class ImageRuntime {
      * @returns The files to record on the page's cache entry
      */
     commitPage(pageImages, html, info) {
-        // Partials are pre-rendered for every page, so keep only images the page really shows
+        // A template can render an image and then discard the output, so keep only images the
+        // written page really shows
         const used = pageImages.uses.filter((use) => html.includes(use.marker));
         for (const use of used) {
             this.startJob(use.jobKey);

package/dist/index.d.ts

@@ -19,10 +19,11 @@
  * await build({ clean: true });
  * ```
  */
-export type { SiteConfig, StatiConfig, PageModel, FrontMatter, BuildContext, PageContext, BuildHooks, NavNode, ISGConfig, AgingRule, BuildStats, BundleConfig, CollectionData, CollectionsConfig, GeneratedPageEntry, PaginationData, GeneratedPageData, PaginateOptions, GenerateOptions, } from './types/index.js';
+export type { SiteConfig, StatiConfig, StatiHelpers, TemplateContext, TemplateIncludeFunction, TemplateLayoutFunction, PageModel, FrontMatter, BuildContext, PageContext, BuildHooks, NavNode, ISGConfig, AgingRule, BuildStats, BundleConfig, CollectionData, CollectionsConfig, GeneratedPageEntry, PaginationData, GeneratedPageData, PaginateOptions, GenerateOptions, } from './types/index.js';
 export type { SEOMetadata, SEOConfig, SEOContext, SEOValidationResult, SEOTagType, RobotsConfig, OpenGraphConfig, OpenGraphImage, OpenGraphArticle, TwitterCardConfig, AuthorConfig, } from './types/index.js';
 export type { SitemapConfig, SitemapEntry, SitemapGenerationResult, ChangeFrequency, } from './types/index.js';
 export type { RSSConfig, RSSFeedConfig, RSSGenerationResult } from './types/index.js';
+export type { MarkdownIt } from './types/index.js';
 export type { ImagesConfig, ResponsiveImagesConfig, OgImagesConfig, OgImageFontConfig, ImagesQualityConfig, ImageVariantFormat, ImageOutputFormat, ImageSourceFormat, ImageProvider, VariantRequest, VariantOutput, OgImageRequest, OgFont, OgDefaults, GeneratedOgImage, } from './types/index.js';
 export type { BuildOptions, MetricsOptions, BuildResult, DevServerOptions, PreviewServerOptions, InvalidationResult, } from './core/index.js';
 export { build, createDevServer, createPreviewServer, invalidate } from './core/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,MAAM,EACN,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG1F,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC3B,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/metrics/noop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/metrics/noop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,YAAY,CAAC;AAqGpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAyC,CAAC"}
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/metrics/noop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,YAAY,CAAC;AAyGpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAyC,CAAC"}

package/dist/metrics/noop.js

@@ -31,7 +31,7 @@ class NoopMetricRecorder {
     setGauge(_name, _value) {
         /* noop */
     }
-    recordPageTiming(_url, _durationMs, _cached, _templatesLoaded) {
+    recordPageTiming(_url, _durationMs, _cached, _templatesLoaded, _templateRenders) {
         /* noop */
     }
     snapshotMemory() {
@@ -71,6 +71,9 @@ class NoopMetricRecorder {
                 cachedPages: 0,
                 assetsCopied: 0,
                 templatesLoaded: 0,
+                templateRenders: 0,
+                includeCacheHits: 0,
+                templatesIndexed: 0,
                 markdownFilesProcessed: 0,
                 imagesGenerated: 0,
                 imagesCached: 0,

package/dist/metrics/recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/metrics/recorder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAQtB,MAAM,YAAY,CAAC;AAsOpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAaxF"}
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/metrics/recorder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAQtB,MAAM,YAAY,CAAC;AAiPpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAaxF"}

package/dist/metrics/recorder.js

@@ -23,6 +23,9 @@ class ActiveMetricRecorder {
         cachedPages: 0,
         assetsCopied: 0,
         templatesLoaded: 0,
+        templateRenders: 0,
+        includeCacheHits: 0,
+        templatesIndexed: 0,
         markdownFilesProcessed: 0,
         imagesGenerated: 0,
         imagesCached: 0,
@@ -72,15 +75,15 @@ class ActiveMetricRecorder {
         const current = this.gauges.get(name) ?? 0;
         this.gauges.set(name, Math.max(current, value));
     }
-    recordPageTiming(url, durationMs, cached, templatesLoaded) {
+    recordPageTiming(url, durationMs, cached, templatesLoaded, templateRenders) {
         if (this.detailed) {
-            const timing = { url, durationMs, cached };
-            if (templatesLoaded !== undefined) {
-                this.pageTimings.push({ ...timing, templatesLoaded });
-            }
-            else {
-                this.pageTimings.push(timing);
-            }
+            this.pageTimings.push({
+                url,
+                durationMs,
+                cached,
+                ...(templatesLoaded !== undefined && { templatesLoaded }),
+                ...(templateRenders !== undefined && { templateRenders }),
+            });
         }
     }
     snapshotMemory() {

package/dist/metrics/types.d.ts

@@ -89,12 +89,24 @@ export interface MetricsPhases {
     readonly cacheManifestLoadMs?: number;
     /** TypeScript compilation */
     readonly typescriptCompileMs?: number;
-    /** Total page rendering time (includes shouldRebuild + render + fileWrite + cacheEntry) */
+    /** Reading the names of every template in the source directory, once per build */
+    readonly templateIndexMs?: number;
+    /**
+     * Total page pipeline time; includes the beforeAll hook, the search index and the per-page
+     * totals below
+     */
     readonly pageRenderingMs?: number;
     /** Aggregate time checking if pages need rebuild (shouldRebuildPage) */
     readonly shouldRebuildTotalMs?: number;
-    /** Aggregate time rendering pages (renderPage) */
+    /** Aggregate time rendering each page's Markdown to HTML */
+    readonly markdownRenderTotalMs?: number;
+    /** Aggregate time rendering pages through their templates (renderPage) */
     readonly renderPageTotalMs?: number;
+    /**
+     * Aggregate time spent on each rendered page between its templates and the file write: SEO,
+     * search and bundle tag injection, registering its images, and hashing what it read
+     */
+    readonly postRenderTotalMs?: number;
     /** Aggregate time writing HTML files to disk */
     readonly fileWriteTotalMs?: number;
     /** Aggregate time updating cache entries */
@@ -143,7 +155,18 @@ export interface MetricsCounts {
     readonly renderedPages: number;
     readonly cachedPages: number;
     readonly assetsCopied: number;
+    /** Distinct template files each rendered page used, summed over the rendered pages */
     readonly templatesLoaded: number;
+    /**
+     * Template renders across the rendered pages: each page's layout, the parents it names, every
+     * included template and the Open Graph template. An include served from the page's cache is
+     * not a render.
+     */
+    readonly templateRenders?: number;
+    /** Includes without props or children that reused the page's earlier render of the template */
+    readonly includeCacheHits?: number;
+    /** Templates in the source directory */
+    readonly templatesIndexed?: number;
     readonly markdownFilesProcessed: number;
     /** Image files generated or copied this build */
     readonly imagesGenerated?: number;
@@ -185,8 +208,10 @@ export interface PageTiming {
     readonly durationMs: number;
     /** Whether page was served from cache */
     readonly cached: boolean;
-    /** Number of templates loaded for this page (undefined for cached pages) */
+    /** Distinct template files the page rendered (undefined for cached pages) */
     readonly templatesLoaded?: number;
+    /** Template renders for the page, repeated includes counted each time (undefined for cached pages) */
+    readonly templateRenders?: number;
 }
 /**
  * Incremental rebuild metrics for dev server.
@@ -249,9 +274,10 @@ export interface MetricRecorder {
     setGauge(name: GaugeName, value: number): void;
     /**
      * Record page timing (only when detailed mode enabled).
-     * @param templatesLoaded - Number of templates loaded (optional, typically undefined for cached pages)
+     * @param templatesLoaded - Distinct template files the page rendered (undefined for cached pages)
+     * @param templateRenders - Template renders for the page (undefined for cached pages)
      */
-    recordPageTiming(url: string, durationMs: number, cached: boolean, templatesLoaded?: number): void;
+    recordPageTiming(url: string, durationMs: number, cached: boolean, templatesLoaded?: number, templateRenders?: number): void;
     /**
      * Take memory snapshot to track peak RSS.
      */