vagejs 0.1.0 → 0.3.0

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

@@ -2,6 +2,22 @@
  * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
  * contributors or (later) CMS sources, so scripts, event handlers, javascript:
  * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
- * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ * attributes (used by analytics events) are kept. style="" is removed unless
+ * `markdown.inlineStyles` is on. Loaded lazily: jsdom is heavy.
+ *
+ * With `publicDir`, images get their size and loading hints inside the sanitizer
+ * (a DOMPurify hook), so DOMPurify's serialization is the final output.
  */
-export declare function sanitizeHtml(html: string): Promise<string>;
+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, variants?: Map<string, {
+    srcset: string;
+    sizes: string;
+}>): Promise<string>;

package/dist/content/sanitize.js

@@ -1,17 +1,57 @@
+import { enhanceImage } from "./images.js";
 let purifier;
+let jsdom;
+async function load() {
+    if (!purifier) {
+        const [mod, { default: createDOMPurify }] = await Promise.all([import("jsdom"), import("dompurify")]);
+        jsdom = mod;
+        purifier = createDOMPurify(new mod.JSDOM("").window);
+    }
+    return { purifier, jsdom: jsdom };
+}
 /**
  * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
  * contributors or (later) CMS sources, so scripts, event handlers, javascript:
  * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
- * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ * attributes (used by analytics events) are kept. style="" is removed unless
+ * `markdown.inlineStyles` is on. Loaded lazily: jsdom is heavy.
+ *
+ * With `publicDir`, images get their size and loading hints inside the sanitizer
+ * (a DOMPurify hook), so DOMPurify's serialization is the final output.
  */
-export async function sanitizeHtml(html) {
-    if (!purifier) {
-        const [{ JSDOM }, { default: createDOMPurify }] = await Promise.all([import("jsdom"), import("dompurify")]);
-        purifier = createDOMPurify(new JSDOM("").window);
+export async function sanitizeHtml(html, options = {}) {
+    const { purifier } = await load();
+    let first = true;
+    const publicDir = options.publicDir;
+    const hook = (node) => {
+        if (publicDir && node.nodeName === "IMG") {
+            enhanceImage(node, publicDir, first, options.variants?.get(node.getAttribute("src") ?? ""));
+            first = false;
+        }
+    };
+    if (publicDir) {
+        purifier.addHook("afterSanitizeAttributes", hook);
     }
-    return purifier.sanitize(html, {
-        FORBID_TAGS: ["style", "form", "input", "button", "textarea", "select", "option", "base", "link", "meta", "object", "embed"],
-        ALLOW_DATA_ATTR: true,
-    });
+    try {
+        return purifier.sanitize(html, {
+            // font/marquee/center: legacy ways to hide or disguise text (white-on-white, 1px scrollers).
+            FORBID_TAGS: ["style", "form", "input", "button", "textarea", "select", "option", "base", "link", "meta", "object", "embed", "font", "marquee", "center"],
+            ALLOW_DATA_ATTR: true,
+            // Inline styles are the usual way to hide injected links (display:none, off-screen); layouts style pages.
+            // xlink:href: SVG links, which would slip past link checks.
+            FORBID_ATTR: options.inlineStyles ? ["xlink:href"] : ["style", "xlink:href"],
+        });
+    }
+    finally {
+        if (publicDir)
+            purifier.removeHook("afterSanitizeAttributes", hook);
+    }
+}
+/** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
+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, 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/clone.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copies plain data (objects and arrays) and keeps everything else as-is (URL, Date,
+ * class instances from Zod transforms), so values can be shared or frozen safely
+ * without breaking what layouts put in their schemas.
+ */
+export declare function clonePlain<T>(value: T): T;

package/dist/core/clone.js

@@ -0,0 +1,16 @@
+/**
+ * Copies plain data (objects and arrays) and keeps everything else as-is (URL, Date,
+ * class instances from Zod transforms), so values can be shared or frozen safely
+ * without breaking what layouts put in their schemas.
+ */
+export function clonePlain(value) {
+    if (Array.isArray(value))
+        return value.map(clonePlain);
+    if (value && typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clonePlain(v)]));
+    }
+    return value;
+}

package/dist/core/config.d.ts

@@ -5,11 +5,18 @@ 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";
             sanitize: "sanitize";
         }>>;
+        inlineStyles: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     seo: z.ZodDefault<z.ZodObject<{
         robots: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
@@ -43,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>;
@@ -95,9 +113,11 @@ export declare const configSchema: z.ZodObject<{
     deploy: z.ZodDefault<z.ZodObject<{
         target: z.ZodDefault<z.ZodEnum<{
             "cloudflare-pages": "cloudflare-pages";
+            "cloudflare-workers": "cloudflare-workers";
             "github-pages": "github-pages";
         }>>;
         cloudflareProject: z.ZodOptional<z.ZodString>;
+        cloudflareWorker: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     security: z.ZodDefault<z.ZodObject<{
         headers: z.ZodDefault<z.ZodBoolean>;
@@ -115,6 +135,12 @@ export declare const configSchema: z.ZodObject<{
             "script-src": "script-src";
             "style-src": "style-src";
         }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+        outboundLinks: z.ZodDefault<z.ZodEnum<{
+            lock: "lock";
+            off: "off";
+            require: "require";
+        }>>;
+        spamPatterns: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     guidelines: z.ZodDefault<z.ZodObject<{
         rulePack: z.ZodOptional<z.ZodString>;

package/dist/core/config.js

@@ -39,6 +39,20 @@ const robotsSchema = z.strictObject({
 });
 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,25 +185,45 @@ 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
             .enum(["sanitize", "allow"])
             .default("sanitize")
             .describe('"sanitize" removes scripts, event handlers, javascript: URLs, iframes and forms from page content. "allow" trusts all content authors.'),
+        inlineStyles: z
+            .boolean()
+            .default(false)
+            .describe('Keep style="..." attributes in page content (sanitize mode). Off by default: inline styles are the usual way to hide spam links. Put styling in layouts.'),
     })
-        .default({ html: "sanitize" }),
+        .default({ html: "sanitize", inlineStyles: false }),
     seo: seoSchema.default(() => seoSchema.parse({})),
     performance: performanceSchema.default(() => performanceSchema.parse({})),
     deploy: z
         .strictObject({
-        target: z.enum(["github-pages", "cloudflare-pages"]).default("github-pages").describe("Host used by `vage deploy`."),
+        target: z
+            .enum(["github-pages", "cloudflare-pages", "cloudflare-workers"])
+            .default("github-pages")
+            .describe("Host used by `vage deploy`. Cloudflare now creates new sites as Workers: prefer cloudflare-workers there."),
         cloudflareProject: z.string().regex(/^[a-z0-9][a-z0-9-]{0,57}$/).optional().describe("Cloudflare Pages project name."),
+        cloudflareWorker: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
+            .optional()
+            .describe("Cloudflare Worker name (cloudflare-workers target, when the project has no wrangler config). Defaults to cloudflareProject."),
     })
         .default({ target: "github-pages" }),
     security: z
         .strictObject({
-        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare Pages target)."),
+        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare targets)."),
         csp: z
             .enum(["enforce", "report-only", "off"])
             .default("enforce")
@@ -198,8 +232,13 @@ export const configSchema = z.strictObject({
             .partialRecord(z.enum(["script-src", "style-src", "img-src", "font-src", "connect-src", "frame-src", "media-src"]), z.array(z.string().regex(/^('[a-z0-9-]+'|https?:\/\/[^\s;,']+|[a-z]+:)$/, "must be a source like https://cdn.example.com or 'self'")))
             .default({})
             .describe("Extra sources per directive, e.g. { \"connect-src\": [\"https://api.example.com\"] }."),
+        outboundLinks: z
+            .enum(["require", "lock", "off"])
+            .default("lock")
+            .describe('"lock": when links.lock.json exists, every external domain the site links to must be listed there (approve with `vage links approve`); new domains fail `vage check`. Catches injected spam links. "require": the same, and a missing links.lock.json is an error, so deleting it can\'t switch the guard off. "off": no guard.'),
+        spamPatterns: z.boolean().default(true).describe("Warn in `vage check` about common spam words (casino, pills, payday loans...) in page text and links."),
     })
-        .default({ headers: true, csp: "enforce", cspSources: {} }),
+        .default({ headers: true, csp: "enforce", cspSources: {}, outboundLinks: "lock", spamPatterns: true }),
     guidelines: z
         .strictObject({
         rulePack: 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/errors.d.ts

@@ -1,5 +1,7 @@
 /** An expected, user-facing error. The CLI prints its message without a stack trace. */
 export declare class VageError extends Error {
     readonly file?: string | undefined;
+    /** The message without the "at <file>" suffix. */
+    readonly detail: string;
     constructor(message: string, file?: string | undefined);
 }

package/dist/core/errors.js

@@ -1,9 +1,12 @@
 /** An expected, user-facing error. The CLI prints its message without a stack trace. */
 export class VageError extends Error {
     file;
+    /** The message without the "at <file>" suffix. */
+    detail;
     constructor(message, file) {
         super(file ? `${message}\n  at ${file}` : message);
         this.file = file;
+        this.detail = message;
         this.name = "VageError";
     }
 }

package/dist/core/html.d.ts

@@ -1,2 +1,24 @@
 /** Escapes text for safe use in HTML content and attribute values. */
 export declare function escapeHtml(value: unknown): string;
+declare const SAFE: unique symbol;
+/** HTML that `html` inserts as-is. Create it with `html` or `raw()`; `String(x)` gives the markup. */
+export interface SafeHtml {
+    readonly [SAFE]: true;
+    readonly value: string;
+    toString(): string;
+}
+export declare const isSafeHtml: (v: unknown) => v is SafeHtml;
+/**
+ * Marks trusted markup so `html` won't escape it, such as `props.content` (already
+ * sanitized) or a JSON-LD script from `jsonLdScript()`. Never pass user or frontmatter text.
+ */
+export declare function raw(markup: string): SafeHtml;
+/**
+ * Template tag for layouts: every `${value}` is escaped unless it is `html` itself or `raw()`.
+ * Arrays are joined, and null, undefined and false render nothing, so lists and conditions read naturally:
+ *
+ *   html`<ul>${posts.map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>`
+ *   html`<main>${raw(content)}</main>`
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): SafeHtml;
+export {};

package/dist/core/html.js

@@ -9,3 +9,34 @@ const ESCAPES = {
 export function escapeHtml(value) {
     return String(value ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]);
 }
+const SAFE = Symbol.for("vagejs.safeHtml");
+const safe = (value) => ({ [SAFE]: true, value, toString: () => value });
+export const isSafeHtml = (v) => typeof v === "object" && v !== null && SAFE in v;
+/**
+ * Marks trusted markup so `html` won't escape it, such as `props.content` (already
+ * sanitized) or a JSON-LD script from `jsonLdScript()`. Never pass user or frontmatter text.
+ */
+export function raw(markup) {
+    return safe(String(markup));
+}
+function interpolate(v) {
+    if (isSafeHtml(v))
+        return v.value;
+    if (Array.isArray(v))
+        return v.map(interpolate).join("");
+    if (v === null || v === undefined || v === false)
+        return "";
+    return escapeHtml(v);
+}
+/**
+ * Template tag for layouts: every `${value}` is escaped unless it is `html` itself or `raw()`.
+ * Arrays are joined, and null, undefined and false render nothing, so lists and conditions read naturally:
+ *
+ *   html`<ul>${posts.map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>`
+ *   html`<main>${raw(content)}</main>`
+ */
+export function html(strings, ...values) {
+    let out = strings[0];
+    values.forEach((v, i) => (out += interpolate(v) + strings[i + 1]));
+    return safe(out);
+}

package/dist/core/pages.d.ts

@@ -0,0 +1,67 @@
+import { type Frontmatter } from "../content/markdown.js";
+import type { ModuleLoader, SiteConfig } from "./config.js";
+/** One published page, as layouts see it in `props.pages`. */
+export interface PageSummary {
+    /** URL path with a trailing slash, e.g. "/blog/first-post/". */
+    route: string;
+    /** 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;
+    frontmatter: Frontmatter;
+}
+/**
+ * Every published page (drafts and 404.md excluded), sorted by route. Reads frontmatter
+ * and applies each page's layout schema, so list entries get the same defaults as the
+ * page itself. The result is frozen: layouts share it, so none may change it.
+ * `skipInvalid` (dev server, `vage check`) leaves out pages whose frontmatter is invalid;
+ * they report their own error instead of breaking every page that lists others.
+ */
+export declare function collectPages(root: string, site: SiteConfig, load: ModuleLoader, options?: {
+    skipInvalid?: boolean;
+}): Promise<readonly PageSummary[]>;
+export interface CollectionOptions {
+    /** Only pages below this route, e.g. "/blog/". The section's own index page is left out unless `includeIndex`. */
+    under?: string;
+    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" | "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[];