vagejs 0.2.0 → 0.3.1

package/dist/content/images.js

@@ -33,22 +33,50 @@ export function imageSize(file) {
         if (chunk === "VP8X")
             return { width: buf.readUIntLE(24, 3) + 1, height: buf.readUIntLE(27, 3) + 1 };
     }
-    // JPEG: walk the segments to the first start-of-frame marker.
+    // JPEG: walk the segments to the first start-of-frame marker. EXIF orientations 5-8
+    // (phone photos taken sideways) display rotated, so width and height swap.
     if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
         let i = 2;
+        let orientation = 1;
         while (i + 9 < buf.length) {
             if (buf[i] !== 0xff)
                 return undefined;
             const marker = buf[i + 1];
             const length = buf.readUInt16BE(i + 2);
+            if (marker === 0xe1)
+                orientation = exifOrientation(buf, i + 4, length - 2) ?? orientation;
             if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
-                return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+                const width = buf.readUInt16BE(i + 7);
+                const height = buf.readUInt16BE(i + 5);
+                return orientation >= 5 && orientation <= 8 ? { width: height, height: width } : { width, height };
             }
             i += 2 + length;
         }
     }
     return undefined;
 }
+/** The EXIF Orientation tag (0x0112) from an APP1 segment, if present. */
+function exifOrientation(buf, start, length) {
+    const end = Math.min(buf.length, start + length);
+    if (end - start < 14 || buf.toString("latin1", start, start + 6) !== "Exif\0\0")
+        return undefined;
+    const tiff = start + 6;
+    const little = buf.toString("latin1", tiff, tiff + 2) === "II";
+    const u16 = (o) => (o + 2 <= end ? (little ? buf.readUInt16LE(o) : buf.readUInt16BE(o)) : undefined);
+    const u32 = (o) => (o + 4 <= end ? (little ? buf.readUInt32LE(o) : buf.readUInt32BE(o)) : undefined);
+    const ifd = u32(tiff + 4);
+    if (ifd === undefined)
+        return undefined;
+    const count = u16(tiff + ifd);
+    if (count === undefined)
+        return undefined;
+    for (let k = 0; k < count; k++) {
+        const entry = tiff + ifd + 2 + k * 12;
+        if (u16(entry) === 0x0112)
+            return u16(entry + 8);
+    }
+    return undefined;
+}
 function svgSize(svg) {
     const tag = /<svg\b[^>]*>/i.exec(svg)?.[0];
     if (!tag)
@@ -68,8 +96,13 @@ function svgSize(svg) {
  * remote images only get the loading hints. Works on DOM elements, never on HTML text,
  * so it can't change how the sanitized markup parses.
  */
-export function enhanceImage(img, publicDir, first) {
+export function enhanceImage(img, publicDir, first, variants) {
     const src = img.getAttribute("src");
+    if (variants && !img.hasAttribute("srcset")) {
+        img.setAttribute("srcset", variants.srcset);
+        if (!img.hasAttribute("sizes"))
+            img.setAttribute("sizes", variants.sizes);
+    }
     if (src && !img.hasAttribute("width") && !img.hasAttribute("height") && /^\/(?!\/)/.test(src)) {
         const size = localImageSize(src, publicDir);
         if (size) {

package/dist/content/markdown.d.ts

@@ -14,6 +14,8 @@ export declare const frontmatterSchema: z.ZodObject<{
     author: z.ZodOptional<z.ZodString>;
     datePublished: z.ZodOptional<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>, unknown>>;
     dateModified: z.ZodOptional<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>, unknown>>;
+    order: z.ZodOptional<z.ZodNumber>;
+    navTitle: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type Frontmatter = z.output<typeof frontmatterSchema>;
 export interface MarkdownPage {

package/dist/content/markdown.js

@@ -28,6 +28,8 @@ export const frontmatterSchema = z.looseObject({
     author: singleLine.min(1).optional().describe("Article author name. Only use a real author."),
     datePublished: isoDate.optional().describe("ISO date or datetime. Only use a real date."),
     dateModified: isoDate.optional().describe("ISO date or datetime; also the sitemap <lastmod>."),
+    order: z.number().finite().optional().describe('Position in navigation lists (lower first). Used by collection(pages, { sort: "order" }) and tree().'),
+    navTitle: singleLine.min(1).optional().describe("Shorter title for menus and breadcrumbs. Defaults to the title."),
 });
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 const marked = new Marked({ gfm: true });

package/dist/content/optimize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Opt-in image pipeline (images.optimize): resized WebP copies of the images used in
+ * page content, offered to browsers with srcset. Needs the `sharp` package in the
+ * project. Results are cached in node_modules/.cache/vagejs/img, keyed by the file's
+ * content and the settings, so unchanged images are never processed twice.
+ */
+export interface ImageOptions {
+    optimize: boolean;
+    widths: number[];
+    quality: number;
+    sizes: string;
+}
+export interface Variants {
+    /** "url 480w, url 960w" */
+    srcset: string;
+    /** Published path (e.g. "_vage/img/photo-ab12cd34-480.webp") -> cached file on disk. */
+    files: Map<string, string>;
+}
+/** Turns an image into WebP at a given width. Injected in tests; sharp otherwise. */
+export type Resize = (input: Buffer, width: number, quality: number) => Promise<Buffer>;
+export declare const IMAGE_DIR = "_vage/img";
+export declare function cacheDir(root: string): string;
+/** Loads sharp from the project (not from vagejs), with a clear message if it's missing. */
+export declare function sharpResize(root: string): Promise<Resize>;
+/**
+ * WebP variants for one site-path image in public/. Undefined for remote images,
+ * non-raster formats (SVG, GIF), paths outside public/ and unreadable files.
+ */
+export declare function imageVariants(src: string, root: string, options: ImageOptions, resize: Resize): Promise<Variants | undefined>;
+/** Image sources used in rendered Markdown, read with an HTML parser (so entities decode like the DOM's). */
+export declare function contentImageSources(html: string): string[];

package/dist/content/optimize.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse } from "node-html-parser";
+import { VageError } from "../core/errors.js";
+import { insidePublic } from "../dev/guard.js";
+import { imageSize } from "./images.js";
+const RASTER = /\.(jpe?g|png|webp)$/i;
+export const IMAGE_DIR = "_vage/img";
+export function cacheDir(root) {
+    return path.join(root, "node_modules", ".cache", "vagejs", "img");
+}
+/** Loads sharp from the project (not from vagejs), with a clear message if it's missing. */
+export async function sharpResize(root) {
+    let resolved;
+    try {
+        resolved = createRequire(path.join(root, "package.json")).resolve("sharp");
+    }
+    catch {
+        throw new VageError('images.optimize needs the "sharp" package. Install it with: npm install --save-dev sharp');
+    }
+    const sharp = (await import(pathToFileURL(resolved).href)).default;
+    // rotate() applies EXIF orientation first, so phone photos aren't served sideways.
+    return (input, width, quality) => sharp(input).rotate().resize({ width, withoutEnlargement: true }).webp({ quality }).toBuffer();
+}
+/**
+ * WebP variants for one site-path image in public/. Undefined for remote images,
+ * non-raster formats (SVG, GIF), paths outside public/ and unreadable files.
+ */
+export async function imageVariants(src, root, options, resize) {
+    if (!/^\/(?!\/)/.test(src))
+        return undefined;
+    let rel;
+    try {
+        rel = decodeURIComponent(src.split(/[?#]/)[0]);
+    }
+    catch {
+        return undefined;
+    }
+    if (!RASTER.test(rel))
+        return undefined;
+    const publicDir = path.join(root, "public");
+    const file = path.join(publicDir, rel);
+    if (!file.startsWith(publicDir + path.sep))
+        return undefined;
+    // Never follow symlinked files or folders: they can point outside the project.
+    if (!insidePublic(file, publicDir))
+        return undefined;
+    const size = imageSize(file);
+    if (!size)
+        return undefined;
+    const input = fs.readFileSync(file);
+    // "v2": variants are auto-rotated; older cached files (not rotated) must not be reused.
+    const hash = createHash("sha256").update(input).update(`q${options.quality}|v2`).digest("hex").slice(0, 10);
+    const slug = path.basename(rel).replace(RASTER, "").replace(/[^\w-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+    const base = /[a-z0-9]/i.test(slug) ? slug : "image";
+    // Never upscale; include the original width when it's smaller than every configured width.
+    const widths = [...new Set(options.widths.filter((w) => w < size.width).concat(size.width <= Math.max(...options.widths) ? [size.width] : []))].sort((a, b) => a - b);
+    const dir = cacheDir(root);
+    fs.mkdirSync(dir, { recursive: true });
+    const files = new Map();
+    const entries = [];
+    for (const w of widths) {
+        const name = `${base}-${hash}-${w}.webp`;
+        const cached = path.join(dir, name);
+        if (!fs.existsSync(cached)) {
+            const tmp = `${cached}.${process.pid}.tmp`;
+            let data;
+            try {
+                data = await resize(input, w, options.quality);
+            }
+            catch (err) {
+                throw new VageError(`Couldn't optimize ${src}: ${err.message}. Replace the file, or turn off images.optimize.`);
+            }
+            fs.writeFileSync(tmp, data);
+            fs.renameSync(tmp, cached);
+        }
+        // Label with the file's real width (rotation can change it); publish each width once.
+        const actual = imageSize(cached)?.width ?? w;
+        if (entries.some((e) => e.endsWith(` ${actual}w`)))
+            continue;
+        files.set(`${IMAGE_DIR}/${name}`, cached);
+        entries.push(`/${IMAGE_DIR}/${name} ${actual}w`);
+    }
+    return entries.length ? { srcset: entries.join(", "), files } : undefined;
+}
+/** Image sources used in rendered Markdown, read with an HTML parser (so entities decode like the DOM's). */
+export function contentImageSources(html) {
+    return [...new Set(parse(html).querySelectorAll("img").map((img) => img.getAttribute("src")).filter((s) => !!s))];
+}

package/dist/content/sanitize.d.ts

@@ -11,6 +11,13 @@
 export declare function sanitizeHtml(html: string, options?: {
     publicDir?: string;
     inlineStyles?: boolean;
+    variants?: Map<string, {
+        srcset: string;
+        sizes: string;
+    }>;
 }): Promise<string>;
 /** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
-export declare function enhanceTrustedHtml(html: string, publicDir: string): Promise<string>;
+export declare function enhanceTrustedHtml(html: string, publicDir: string, variants?: Map<string, {
+    srcset: string;
+    sizes: string;
+}>): Promise<string>;

package/dist/content/sanitize.js

@@ -25,7 +25,7 @@ export async function sanitizeHtml(html, options = {}) {
     const publicDir = options.publicDir;
     const hook = (node) => {
         if (publicDir && node.nodeName === "IMG") {
-            enhanceImage(node, publicDir, first);
+            enhanceImage(node, publicDir, first, options.variants?.get(node.getAttribute("src") ?? ""));
             first = false;
         }
     };
@@ -48,10 +48,10 @@ export async function sanitizeHtml(html, options = {}) {
     }
 }
 /** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
-export async function enhanceTrustedHtml(html, publicDir) {
+export async function enhanceTrustedHtml(html, publicDir, variants) {
     const { jsdom } = await load();
     const template = new jsdom.JSDOM("").window.document.createElement("template");
     template.innerHTML = html;
-    template.content.querySelectorAll("img").forEach((img, i) => enhanceImage(img, publicDir, i === 0));
+    template.content.querySelectorAll("img").forEach((img, i) => enhanceImage(img, publicDir, i === 0, variants?.get(img.getAttribute("src") ?? "")));
     return template.innerHTML;
 }

package/dist/core/build.js

@@ -25,6 +25,10 @@ export async function buildSite(root) {
             outputs.set(r.outFile, r.html);
         for (const [name, content] of model.files)
             outputs.set(name, content);
+        const assets = new Map();
+        for (const p of [...model.pages, ...(model.notFound ? [model.notFound] : [])])
+            for (const [k, f] of p.assets)
+                assets.set(k, f);
         fs.rmSync(outDir, { recursive: true, force: true });
         const publicDir = path.join(root, "public");
         if (fs.existsSync(publicDir))
@@ -37,6 +41,13 @@ export async function buildSite(root) {
             fs.mkdirSync(path.dirname(target), { recursive: true });
             fs.writeFileSync(target, content);
         }
+        for (const [output, file] of assets) {
+            const target = path.resolve(outDir, output);
+            if (!target.startsWith(outDir + path.sep))
+                throw new VageError(`Refusing to write outside ${OUT_DIR}/: ${output}`);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.copyFileSync(file, target);
+        }
         const result = {
             outDir,
             pages: model.pages.map((p) => ({ route: p.route, source: p.source, output: p.outFile })),

package/dist/core/config.d.ts

@@ -5,6 +5,12 @@ export declare const configSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     lang: z.ZodDefault<z.ZodString>;
+    images: z.ZodDefault<z.ZodObject<{
+        optimize: z.ZodDefault<z.ZodBoolean>;
+        widths: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+        quality: z.ZodDefault<z.ZodNumber>;
+        sizes: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
     markdown: z.ZodDefault<z.ZodObject<{
         html: z.ZodDefault<z.ZodEnum<{
             allow: "allow";
@@ -44,6 +50,17 @@ export declare const configSchema: z.ZodObject<{
             aiTraining?: "allow" | "disallow" | undefined;
             aiSearch?: "allow" | "disallow" | undefined;
         }>>;
+        feeds: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            under: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            limit: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        lastmod: z.ZodDefault<z.ZodEnum<{
+            frontmatter: "frontmatter";
+            git: "git";
+        }>>;
+        markdownCopies: z.ZodDefault<z.ZodBoolean>;
         sitemap: z.ZodDefault<z.ZodBoolean>;
         llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             full: z.ZodDefault<z.ZodBoolean>;

package/dist/core/config.js

@@ -31,14 +31,28 @@ const robotsSchema = z.strictObject({
     aiTraining: z
         .enum(["allow", "disallow"])
         .optional()
-        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended). Unset: the * group applies."),
+        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended, Applebot-Extended). Google-Extended also covers grounding in Gemini Apps and Vertex AI. Unset: the * group applies."),
     aiSearch: z
         .enum(["allow", "disallow"])
         .optional()
-        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot). Unset: the * group applies."),
+        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot, PerplexityBot). Unset: the * group applies."),
 });
 const seoSchema = z.strictObject({
     robots: toggle(robotsSchema).describe("Generate robots.txt (true/false or options)."),
+    feeds: z
+        .array(z.strictObject({
+        under: z.string().regex(/^\/(?:[\w-]+\/)*$/, 'must be a section path like "/blog/" (letters, digits, "_" and "-")').describe("Section whose pages the feed lists."),
+        title: z.string().min(1).optional().describe("Feed title. Defaults to the section page's title."),
+        description: z.string().min(1).optional().describe("Feed description. Defaults to the section page's description."),
+        limit: z.number().int().min(1).max(500).default(20).describe("Most recent pages to include."),
+    }))
+        .default([])
+        .describe('RSS feeds, e.g. [{ under: "/blog/" }] writes /blog/feed.xml (needs `site`). Pages in the section link to it.'),
+    lastmod: z
+        .enum(["frontmatter", "git"])
+        .default("frontmatter")
+        .describe('Where sitemap <lastmod> dates come from: "frontmatter" (dateModified/datePublished) or "git" (each page\'s last commit; dateModified still wins). Git dates are skipped in shallow clones.'),
+    markdownCopies: z.boolean().default(false).describe("Also publish each listed page as Markdown at /<path>.md (e.g. /docs/cli.md), linked from the page, for AI tools."),
     sitemap: z.boolean().default(true).describe("Generate sitemap.xml (needs `site`)."),
     llmsTxt: toggle(z.strictObject({
         full: z.boolean().default(false).describe("Also emit llms-full.txt with the Markdown of every listed page."),
@@ -171,6 +185,14 @@ export const configSchema = z.strictObject({
     title: z.string().min(1).optional().describe("Site name: page titles, og:site_name, llms.txt heading."),
     description: z.string().min(1).optional().describe("Fallback meta description; llms.txt summary."),
     lang: z.string().min(1).default("en").describe("<html lang> value."),
+    images: z
+        .strictObject({
+        optimize: z.boolean().default(false).describe('Make resized WebP copies of images in page content and offer them with srcset. Needs "sharp" in the project (npm install --save-dev sharp).'),
+        widths: z.array(z.number().int().min(16).max(8000)).min(1).max(8).default([480, 960, 1600]).describe("Widths to generate (never larger than the original)."),
+        quality: z.number().int().min(1).max(100).default(75).describe("WebP quality."),
+        sizes: z.string().regex(/^[^<>"]+$/).default("(max-width: 48rem) 100vw, 48rem").describe('The sizes attribute: how wide images display, so browsers pick the right file.'),
+    })
+        .default({ optimize: false, widths: [480, 960, 1600], quality: 75, sizes: "(max-width: 48rem) 100vw, 48rem" }),
     markdown: z
         .strictObject({
         html: z

package/dist/core/dates.d.ts

@@ -0,0 +1,2 @@
+/** A frontmatter date as a point in time ("2026-10-24" = midnight UTC); NaN when missing. */
+export declare function instant(date: string | undefined): number;

package/dist/core/dates.js

@@ -0,0 +1,4 @@
+/** A frontmatter date as a point in time ("2026-10-24" = midnight UTC); NaN when missing. */
+export function instant(date) {
+    return date ? Date.parse(date.length === 10 ? `${date}T00:00:00Z` : date) : NaN;
+}

package/dist/core/pages.d.ts

@@ -7,6 +7,8 @@ export interface PageSummary {
     /** Absolute canonical URL, when `site` is set and the page is indexable. */
     url?: string;
     title: string;
+    /** Menu and breadcrumb text: `navTitle`, or the title. */
+    label: string;
     description?: string;
     /** Source path relative to the project root, e.g. "src/pages/blog/first-post.md". */
     source: string;
@@ -28,13 +30,38 @@ export interface CollectionOptions {
     includeIndex?: boolean;
     /**
      * "date": newest `datePublished` first (undated pages last, then by title).
+     * "order": by the `order` field, lowest first (pages without one last, then by title).
      * "title": A to Z. "route" (default): by URL. Or a compare function.
      */
-    sort?: "date" | "title" | "route" | ((a: PageSummary, b: PageSummary) => number);
+    sort?: "date" | "title" | "route" | "order" | ((a: PageSummary, b: PageSummary) => number);
     limit?: number;
 }
 /**
  * Picks and orders pages for lists such as a blog index, a sidebar or "latest posts":
  *   collection(pages, { under: "/blog/", sort: "date", limit: 5 })
  */
+/** By `order` (lowest first; pages without one last), then title. */
+export declare function byOrder(a: PageSummary, b: PageSummary): number;
 export declare function collection(pages: readonly PageSummary[], options?: CollectionOptions): PageSummary[];
+/** The pages before and after `route` in an ordered list (e.g. from collection()), for "Previous / Next" links. */
+export declare function neighbors(list: readonly PageSummary[], route: string): {
+    prev?: PageSummary;
+    next?: PageSummary;
+};
+/**
+ * The trail from the home page to `route`, using the pages that exist at each level:
+ * /docs/guides/setup/ -> [Home, Docs, Guides, Setup] (missing levels are skipped).
+ */
+export declare function breadcrumbs(pages: readonly PageSummary[], route: string): PageSummary[];
+export interface TreeNode {
+    page: PageSummary;
+    children: TreeNode[];
+}
+/**
+ * Pages under `under` as a nested tree (folders become levels), each level sorted by
+ * `order`, then title: ready for a sidebar. A folder without its own index page is
+ * skipped; its pages move up a level.
+ */
+export declare function tree(pages: readonly PageSummary[], under?: string): TreeNode[];
+/** A tree() in sidebar reading order (each page, then its children), for neighbors() in nested docs. */
+export declare function flatten(nodes: readonly TreeNode[]): PageSummary[];

package/dist/core/pages.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parseFrontmatter } from "../content/markdown.js";
 import { pageMeta } from "../seo/head.js";
 import { clonePlain } from "./clone.js";
+import { instant } from "./dates.js";
 import { applyLayoutFields } from "./render.js";
 import { VageError } from "./errors.js";
 import { discoverRoutes } from "./routes.js";
@@ -34,6 +35,7 @@ export async function collectPages(root, site, load, options = {}) {
             route: entry.route,
             url: pageMeta(site, entry.route, frontmatter).canonical,
             title: frontmatter.title,
+            label: frontmatter.navTitle ?? frontmatter.title,
             description: frontmatter.description,
             source: path.relative(root, entry.file),
             frontmatter,
@@ -52,11 +54,19 @@ function deepFreeze(value) {
     }
     return value;
 }
-const SORTS = ["date", "title", "route"];
+const SORTS = ["date", "title", "route", "order"];
 /**
  * Picks and orders pages for lists such as a blog index, a sidebar or "latest posts":
  *   collection(pages, { under: "/blog/", sort: "date", limit: 5 })
  */
+/** By `order` (lowest first; pages without one last), then title. */
+export function byOrder(a, b) {
+    const oa = a.frontmatter.order;
+    const ob = b.frontmatter.order;
+    if (oa !== ob)
+        return oa === undefined ? 1 : ob === undefined ? -1 : oa - ob;
+    return a.title.localeCompare(b.title);
+}
 export function collection(pages, options = {}) {
     if (!Array.isArray(pages))
         throw new VageError("collection(): pass the layout's `pages` as the first argument.");
@@ -65,7 +75,7 @@ export function collection(pages, options = {}) {
         throw new VageError(`collection(): "under" must be a site path starting with "/", like "/blog/" (got ${JSON.stringify(under)}).`);
     }
     if (typeof sort !== "function" && !SORTS.includes(sort)) {
-        throw new VageError(`collection(): "sort" must be "date", "title", "route" or a compare function (got ${JSON.stringify(sort)}).`);
+        throw new VageError(`collection(): "sort" must be "date", "order", "title", "route" or a compare function (got ${JSON.stringify(sort)}).`);
     }
     if (typeof includeIndex !== "boolean")
         throw new VageError(`collection(): "includeIndex" must be true or false (got ${JSON.stringify(includeIndex)}).`);
@@ -79,15 +89,80 @@ export function collection(pages, options = {}) {
         ? sort
         : sort === "title"
             ? byTitle
-            : sort === "date"
-                ? (a, b) => {
-                    const da = a.frontmatter.datePublished ?? "";
-                    const db = b.frontmatter.datePublished ?? "";
-                    if (da !== db)
-                        return da && db ? db.localeCompare(da) : da ? -1 : 1;
-                    return byTitle(a, b);
-                }
-                : (a, b) => a.route.localeCompare(b.route);
+            : sort === "order"
+                ? byOrder
+                : sort === "date"
+                    ? (a, b) => {
+                        const ta = instant(a.frontmatter.datePublished);
+                        const tb = instant(b.frontmatter.datePublished);
+                        if (ta !== tb && !(Number.isNaN(ta) && Number.isNaN(tb)))
+                            return Number.isNaN(ta) ? 1 : Number.isNaN(tb) ? -1 : tb - ta;
+                        return byTitle(a, b);
+                    }
+                    : (a, b) => a.route.localeCompare(b.route);
     const sorted = [...picked].sort(compare);
     return limit === undefined ? sorted : sorted.slice(0, limit);
 }
+/** The pages before and after `route` in an ordered list (e.g. from collection()), for "Previous / Next" links. */
+export function neighbors(list, route) {
+    const i = list.findIndex((p) => p.route === route);
+    if (i === -1)
+        return {};
+    return { prev: list[i - 1], next: list[i + 1] };
+}
+/**
+ * The trail from the home page to `route`, using the pages that exist at each level:
+ * /docs/guides/setup/ -> [Home, Docs, Guides, Setup] (missing levels are skipped).
+ */
+export function breadcrumbs(pages, route) {
+    const byRoute = new Map(pages.map((p) => [p.route, p]));
+    const parts = route.split("/").filter(Boolean);
+    const trail = [];
+    for (let i = 0; i <= parts.length; i++) {
+        const r = i === 0 ? "/" : `/${parts.slice(0, i).join("/")}/`;
+        const page = byRoute.get(r);
+        if (page)
+            trail.push(page);
+    }
+    return trail;
+}
+/**
+ * Pages under `under` as a nested tree (folders become levels), each level sorted by
+ * `order`, then title: ready for a sidebar. A folder without its own index page is
+ * skipped; its pages move up a level.
+ */
+export function tree(pages, under = "/") {
+    if (!/^\/(?!\/)/.test(under))
+        throw new VageError(`tree(): "under" must be a site path starting with "/" (got ${JSON.stringify(under)}).`);
+    const prefix = under.endsWith("/") ? under : `${under}/`;
+    const inside = pages.filter((p) => p.route.startsWith(prefix) && p.route !== prefix);
+    const routes = new Set(inside.map((p) => p.route));
+    const parentOf = (route) => {
+        const parts = route.split("/").filter(Boolean);
+        for (let i = parts.length - 1; i > 0; i--) {
+            const r = `/${parts.slice(0, i).join("/")}/`;
+            if (r.length <= prefix.length)
+                return undefined;
+            if (routes.has(r))
+                return r;
+        }
+        return undefined;
+    };
+    const nodes = new Map(inside.map((p) => [p.route, { page: p, children: [] }]));
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = parentOf(node.page.route);
+        (parent ? nodes.get(parent).children : roots).push(node);
+    }
+    const sort = (list) => {
+        list.sort((a, b) => byOrder(a.page, b.page));
+        for (const n of list)
+            sort(n.children);
+        return list;
+    };
+    return sort(roots);
+}
+/** A tree() in sidebar reading order (each page, then its children), for neighbors() in nested docs. */
+export function flatten(nodes) {
+    return nodes.flatMap((n) => [n.page, ...flatten(n.children)]);
+}

package/dist/core/render.d.ts

@@ -1,4 +1,5 @@
 import { type Frontmatter } from "../content/markdown.js";
+import { type Resize } from "../content/optimize.js";
 import type { ModuleLoader, SiteConfig } from "./config.js";
 import { type SafeHtml } from "./html.js";
 import { type PageMeta } from "../seo/head.js";
@@ -25,6 +26,10 @@ export interface LayoutProps {
 export type Layout = (props: LayoutProps) => string | SafeHtml | Promise<string | SafeHtml>;
 export interface RenderedPage {
     html: string;
+    /** The page body as rendered and sanitized, before the layout (source of Markdown copies). */
+    content: string;
+    /** Generated image files this page uses: published path -> file on disk (images.optimize). */
+    assets: Map<string, string>;
     frontmatter: Frontmatter;
     /** Markdown body without frontmatter. */
     body: string;
@@ -42,6 +47,8 @@ export declare function renderPage(options: {
     analytics?: boolean;
     /** Published pages for `props.pages`. */
     pages?: readonly PageSummary[];
+    /** Resizer for images.optimize (tests inject one; sharp otherwise). */
+    resize?: Resize;
 }): Promise<RenderedPage>;
 /**
  * Loads the page's layout and, if it exports a `frontmatter` schema, validates the page

package/dist/core/render.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { frontmatterSchema, parseMarkdown } from "../content/markdown.js";
+import { contentImageSources, imageVariants, sharpResize } from "../content/optimize.js";
 import { enhanceTrustedHtml, sanitizeHtml } from "../content/sanitize.js";
 import { VageError } from "./errors.js";
 import { clonePlain } from "./clone.js";
@@ -13,7 +14,23 @@ export async function renderPage(options) {
     const parsed = parseMarkdown(fs.readFileSync(file, "utf8"), file);
     const { frontmatter, body } = parsed;
     const publicDir = path.join(root, "public");
-    const content = site.markdown.html === "allow" ? await enhanceTrustedHtml(parsed.html, publicDir) : await sanitizeHtml(parsed.html, { publicDir, inlineStyles: site.markdown.inlineStyles });
+    const assets = new Map();
+    let variants;
+    if (site.images.optimize) {
+        const resize = options.resize ?? (await sharpResize(root));
+        variants = new Map();
+        for (const src of contentImageSources(parsed.html)) {
+            const v = await imageVariants(src, root, site.images, resize);
+            if (!v)
+                continue;
+            variants.set(src, { srcset: v.srcset, sizes: site.images.sizes });
+            for (const [k, f] of v.files)
+                assets.set(k, f);
+        }
+    }
+    const content = site.markdown.html === "allow"
+        ? await enhanceTrustedHtml(parsed.html, publicDir, variants)
+        : await sanitizeHtml(parsed.html, { publicDir, inlineStyles: site.markdown.inlineStyles, variants });
     const layout = await applyLayoutFields(root, frontmatter, load, file);
     const meta = pageMeta(site, route, frontmatter, options.notFound);
     const result = await layout({
@@ -30,7 +47,7 @@ export async function renderPage(options) {
     const tags = options.analytics ? analyticsTags(site) : undefined;
     if (tags)
         out = injectAnalytics(out, tags, file);
-    return { html: out, frontmatter, body, meta };
+    return { html: out, content, frontmatter, body, meta, assets };
 }
 const LAYOUT_EXTENSIONS = [".ts", ".js", ".mjs"];
 async function resolveLayout(root, name, load, pageFile) {