vagejs 0.1.0 → 0.3.0

package/dist/core/pages.js

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+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";
+/**
+ * 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 async function collectPages(root, site, load, options = {}) {
+    const pagesDir = path.join(root, "src", "pages");
+    const out = [];
+    for (const entry of discoverRoutes(pagesDir)) {
+        let frontmatter;
+        try {
+            ({ frontmatter } = parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file));
+            if (frontmatter.draft)
+                continue;
+            await applyLayoutFields(root, frontmatter, load, entry.file);
+        }
+        catch (err) {
+            // Any failure (bad frontmatter, a layout that throws or doesn't compile) is that page's own error.
+            if (options.skipInvalid)
+                continue;
+            throw err;
+        }
+        out.push({
+            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,
+        });
+    }
+    // A frozen deep copy: shared by every layout, and never the objects a page renders with.
+    return deepFreeze(clonePlain(out));
+}
+/** Freezes plain data only; URL/Date/class instances from schema transforms stay usable. */
+function deepFreeze(value) {
+    const plain = Array.isArray(value) || (value && typeof value === "object" && [Object.prototype, null].includes(Object.getPrototypeOf(value)));
+    if (plain && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+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.");
+    const { under, includeIndex = false, sort = "route", limit } = options;
+    if (under !== undefined && !/^\/(?!\/)/.test(under)) {
+        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", "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)}).`);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 0)) {
+        throw new VageError(`collection(): "limit" must be a whole number of 0 or more (got ${JSON.stringify(limit)}).`);
+    }
+    const prefix = under ? (under.endsWith("/") ? under : `${under}/`) : undefined;
+    const picked = pages.filter((p) => !prefix || (p.route.startsWith(prefix) && (includeIndex || p.route !== prefix)));
+    const byTitle = (a, b) => a.title.localeCompare(b.title);
+    const compare = typeof sort === "function"
+        ? sort
+        : sort === "title"
+            ? byTitle
+            : 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,6 +1,9 @@
 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";
+import type { PageSummary } from "./pages.js";
 export interface LayoutProps {
     /** Rendered page body HTML. Insert as-is; do not escape. */
     content: string;
@@ -13,10 +16,20 @@ export interface LayoutProps {
         frontmatter: Frontmatter;
     };
     site: SiteConfig;
+    /**
+     * Every published page (drafts excluded), sorted by route. Use `collection()` to
+     * pick a section and order it, e.g. a blog index or a sidebar.
+     */
+    pages: readonly PageSummary[];
 }
-export type Layout = (props: LayoutProps) => string | Promise<string>;
+/** Returns the page's HTML: a string, or `html\`...\`` (escapes values automatically). */
+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;
@@ -32,6 +45,16 @@ export declare function renderPage(options: {
     notFound?: boolean;
     /** Add configured analytics tags. Off in the dev server so development traffic is never measured. */
     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
+ * against it and fills in defaults (mutating `frontmatter`). Used for rendering and for
+ * `props.pages`, so both see the same values. Returns the layout function.
+ */
+export declare function applyLayoutFields(root: string, frontmatter: Frontmatter, load: ModuleLoader, file: string): Promise<Layout>;
 /** Used when a project has no src/layouts/default.ts. */
 export declare const defaultLayout: Layout;

package/dist/core/render.js

@@ -1,31 +1,53 @@
 import fs from "node:fs";
 import path from "node:path";
-import { parseMarkdown } from "../content/markdown.js";
-import { sanitizeHtml } from "../content/sanitize.js";
+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 { escapeHtml } from "./html.js";
+import { clonePlain } from "./clone.js";
+import { escapeHtml, isSafeHtml } from "./html.js";
 import { headTags, injectHead, pageMeta } from "../seo/head.js";
 import { analyticsTags, injectAnalytics } from "../integrations/tags.js";
 export async function renderPage(options) {
     const { root, file, route, site, load } = options;
     const parsed = parseMarkdown(fs.readFileSync(file, "utf8"), file);
     const { frontmatter, body } = parsed;
-    const content = site.markdown.html === "allow" ? parsed.html : await sanitizeHtml(parsed.html);
+    const publicDir = path.join(root, "public");
+    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 layout = await resolveLayout(root, frontmatter.layout, load, file);
-    const html = await layout({
+    const result = await layout({
         content,
         page: { route, title: frontmatter.title, description: frontmatter.description, url: meta.canonical, frontmatter },
         site,
+        pages: options.pages ?? [],
     });
+    const html = isSafeHtml(result) ? result.value : result;
     if (typeof html !== "string") {
-        throw new VageError(`Layout "${frontmatter.layout ?? "default"}" must return an HTML string.`, file);
+        throw new VageError(`Layout "${frontmatter.layout ?? "default"}" must return an HTML string or html\`...\`.`, file);
     }
     let out = injectHead(html, headTags(site, meta), file);
     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) {
@@ -33,15 +55,52 @@ async function resolveLayout(root, name, load, pageFile) {
     const file = LAYOUT_EXTENSIONS.map((ext) => base + ext).find((f) => fs.existsSync(f));
     if (!file) {
         if (!name)
-            return defaultLayout;
+            return { layout: defaultLayout };
         throw new VageError(`Layout "${name}" not found. Expected src/layouts/${name}.ts`, pageFile);
     }
-    const layout = (await load(file)).default;
+    const mod = await load(file);
+    const layout = mod.default;
     if (typeof layout !== "function") {
         throw new VageError("Layout files must default-export a function that returns an HTML string.", file);
     }
+    const schema = mod.frontmatter;
+    if (schema !== undefined && (typeof schema?.safeParse !== "function" || typeof schema.shape !== "object")) {
+        throw new VageError('`export const frontmatter` in a layout must be a Zod object schema: z.object({ ... }) (import { z } from "vagejs").', file);
+    }
+    return { layout: layout, schema };
+}
+const BUILT_IN_FIELDS = new Set(Object.keys(frontmatterSchema.shape));
+/**
+ * Loads the page's layout and, if it exports a `frontmatter` schema, validates the page
+ * against it and fills in defaults (mutating `frontmatter`). Used for rendering and for
+ * `props.pages`, so both see the same values. Returns the layout function.
+ */
+export async function applyLayoutFields(root, frontmatter, load, file) {
+    const { layout, schema } = await resolveLayout(root, frontmatter.layout, load, file);
+    if (schema)
+        Object.assign(frontmatter, validateLayoutFields(frontmatter, schema, frontmatter.layout ?? "default", file));
     return layout;
 }
+/**
+ * Checks the fields a page adds for its layout against the layout's schema. Unknown
+ * fields are errors (a typo would otherwise do nothing); defaults are filled in. A
+ * schema may also declare built-in fields (e.g. make `author` required); those are
+ * validated too. Built-in defaults (type "website", draft/noindex false) are applied
+ * first, so a layout can restrict them but not change their defaults.
+ */
+function validateLayoutFields(frontmatter, schema, layoutName, file) {
+    const declared = new Set(Object.keys(schema.shape ?? {}));
+    const own = Object.fromEntries(Object.entries(frontmatter).filter(([k]) => !BUILT_IN_FIELDS.has(k) || declared.has(k)));
+    // Strict unless the layout chose otherwise (.passthrough() / z.looseObject set a catchall).
+    const loose = schema._zod?.def?.catchall !== undefined;
+    const result = (loose || !schema.strict ? schema : schema.strict()).safeParse(own);
+    if (!result.success) {
+        const detail = result.error instanceof z.ZodError ? z.prettifyError(result.error) : String(result.error);
+        throw new VageError(`Frontmatter doesn't match the "${layoutName}" layout's fields:\n${detail}`, file);
+    }
+    // Zod reuses a default's nested objects across parses; give each page its own copy.
+    return clonePlain(result.data);
+}
 /** Used when a project has no src/layouts/default.ts. */
 export const defaultLayout = ({ content, page, site }) => {
     const title = site.title && site.title !== page.title ? `${page.title} | ${site.title}` : page.title;

package/dist/core/site.d.ts

@@ -12,8 +12,17 @@ export interface SiteRedirect {
     outFile: string;
     html: string;
 }
+export interface PageError {
+    /** Source path relative to the project root. */
+    source: string;
+    /** The route the page would have had (links to it aren't reported again as broken). */
+    route?: string;
+    message: string;
+}
 export interface SiteModel {
     site: SiteConfig;
+    /** Pages that failed to render (only with `collectErrors`; otherwise the first failure throws). */
+    pageErrors: PageError[];
     /** Published pages (drafts excluded). */
     pages: SitePage[];
     skippedDrafts: string[];
@@ -26,6 +35,8 @@ export interface SiteModel {
     warnings: string[];
 }
 /** Renders every page and derives discovery files from the same data, without writing anything. */
-export declare function renderSite(root: string, load: ModuleLoader): Promise<SiteModel>;
+export declare function renderSite(root: string, load: ModuleLoader, options?: {
+    collectErrors?: boolean;
+}): Promise<SiteModel>;
 /** Pages that should appear in sitemap.xml and llms.txt: indexable and canonical to themselves. */
 export declare function listedPages(model: SiteModel): SitePage[];

package/dist/core/site.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { llmsFullTxt, llmsTxt } from "../discovery/llms.js";
+import { feedPath, rssFeed } from "../discovery/feed.js";
+import { gitPageDates } from "../discovery/git-dates.js";
+import { htmlToMarkdown, markdownCopy, markdownCopyPath } from "../discovery/markdown-copy.js";
 import { robotsTxt } from "../discovery/robots.js";
 import { SITEMAP_URL_LIMIT, sitemapXml } from "../discovery/sitemap.js";
 import { headersFile } from "../deploy/headers.js";
@@ -12,12 +15,15 @@ import { loadConfig } from "./config.js";
 import { VageError } from "./errors.js";
 import { escapeHtml } from "./html.js";
 import { renderPage } from "./render.js";
+import { parseFrontmatter } from "../content/markdown.js";
+import { sharpResize } from "../content/optimize.js";
+import { collectPages } from "./pages.js";
 import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "./routes.js";
 /** Renders every page and derives discovery files from the same data, without writing anything. */
-export async function renderSite(root, load) {
+export async function renderSite(root, load, options = {}) {
     const pagesDir = path.join(root, "src", "pages");
     if (!fs.existsSync(pagesDir)) {
-        throw new VageError(`No src/pages directory found in ${root}. Is this a VAGE JS project?`);
+        throw new VageError(`No src/pages directory found in ${root}. Is this a vagejs project?`);
     }
     const site = await loadConfig(root, load);
     const pinned = site.guidelines.rulePack;
@@ -25,35 +31,64 @@ export async function renderSite(root, load) {
         throw new VageError(`This project pins rule pack ${pinned}, but the installed vagejs ships ${rulePack.version}. ` +
             `Review what changed with "vage guidelines", then update guidelines.rulePack in vage.config.ts.`);
     }
-    const model = { site, pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    const model = { site, pageErrors: [], pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    const collect = options.collectErrors === true;
+    const attempt = async (file, route, work) => {
+        try {
+            await work();
+        }
+        catch (err) {
+            if (!collect)
+                throw err;
+            // Layout code can throw anything (or fail to compile); report it as this page's error.
+            const message = err instanceof VageError ? err.detail : `Layout or render error: ${err?.message ?? String(err)}`;
+            model.pageErrors.push({ source: path.relative(root, file), route, message });
+        }
+    };
+    const pages = await collectPages(root, site, load, { skipInvalid: collect });
+    // Loaded once for the whole site, so a missing sharp is one clear error, not one per page.
+    const resize = site.images.optimize ? await sharpResize(root) : undefined;
     for (const entry of discoverRoutes(pagesDir)) {
-        const page = await renderPage({ root, file: entry.file, route: entry.route, site, load, analytics: true });
         const source = path.relative(root, entry.file);
-        if (page.frontmatter.draft) {
-            model.skippedDrafts.push(source);
-            model.draftRoutes.push(entry.route);
-        }
-        else
+        await attempt(entry.file, entry.route, async () => {
+            // Drafts are skipped before rendering, so their fields can't fail a build.
+            if (parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file).frontmatter.draft) {
+                model.skippedDrafts.push(source);
+                model.draftRoutes.push(entry.route);
+                return;
+            }
+            const page = await renderPage({ root, file: entry.file, route: entry.route, site, load, analytics: true, pages, resize });
             model.pages.push({ ...page, route: entry.route, source, outFile: entry.outFile });
+        });
     }
     const notFound = findNotFoundPage(pagesDir);
     if (notFound) {
-        const page = await renderPage({ root, file: notFound, route: "/404/", site, load, notFound: true, analytics: true });
-        model.notFound = { ...page, route: "/404/", source: path.relative(root, notFound), outFile: "404.html" };
+        await attempt(notFound, undefined, async () => {
+            const page = await renderPage({ root, file: notFound, route: "/404/", site, load, notFound: true, analytics: true, pages, resize });
+            model.notFound = { ...page, route: "/404/", source: path.relative(root, notFound), outFile: "404.html" };
+        });
     }
     checkPublicDir(root, model.warnings);
+    // Markdown versions of pages, converted from their sanitized HTML (copies and llms-full.txt).
+    const markdown = new Map();
+    if (site.seo.markdownCopies || (site.seo.llmsTxt && site.seo.llmsTxt.full)) {
+        for (const p of listedPages(model))
+            markdown.set(p.route, await htmlToMarkdown(p.content, { route: p.route, origin: site.site }));
+    }
     model.redirects = buildRedirects(site, new Set(model.pages.map((p) => p.route)));
-    addDiscoveryFiles(root, model);
+    addDiscoveryFiles(root, model, markdown);
     return model;
 }
 /** Pages that should appear in sitemap.xml and llms.txt: indexable and canonical to themselves. */
 export function listedPages(model) {
     return model.pages.filter((p) => !p.meta.noindex && p.meta.canonical === absoluteUrl(model.site.site, p.route));
 }
-function addDiscoveryFiles(root, model) {
+function addDiscoveryFiles(root, model, markdown) {
     const { site, files, warnings } = model;
     const listed = listedPages(model);
     const generate = (name, content) => {
+        if (files.has(name))
+            throw new VageError(`Two generated files would be written to ${name}. Rename one of the pages behind it.`);
         if (fs.existsSync(path.join(root, "public", name))) {
             throw new VageError(`public/${name} conflicts with the generated ${name}. Delete it, or turn generation off in vage.config.ts (seo).`);
         }
@@ -73,14 +108,37 @@ function addDiscoveryFiles(root, model) {
         if (listed.length > SITEMAP_URL_LIMIT) {
             throw new VageError(`sitemap.xml would list ${listed.length} URLs; sitemap indexes (over ${SITEMAP_URL_LIMIT}) are not supported yet.`);
         }
-        generate("sitemap.xml", () => sitemapXml(listed.map((p) => ({ url: p.meta.canonical, lastmod: p.frontmatter.dateModified ?? p.frontmatter.datePublished }))));
+        let gitDates;
+        if (site.seo.lastmod === "git") {
+            const result = gitPageDates(root);
+            gitDates = result.dates;
+            if (result.problem)
+                warnings.push(`seo.lastmod is "git", but ${result.problem}; sitemap dates come from frontmatter instead.`);
+        }
+        generate("sitemap.xml", () => sitemapXml(listed.map((p) => ({ url: p.meta.canonical, lastmod: p.frontmatter.dateModified ?? gitDates?.get(p.source) ?? p.frontmatter.datePublished }))));
+    }
+    for (const feed of site.seo.feeds) {
+        if (!site.site) {
+            warnings.push(`seo.feeds: the feed for ${feed.under} needs "site" in vage.config.ts and was skipped.`);
+            continue;
+        }
+        if (!listed.some((p) => p.route.startsWith(feed.under) && p.route !== feed.under)) {
+            warnings.push(`seo.feeds: no published pages under ${feed.under}, so its feed is empty.`);
+        }
+        generate(feedPath(feed.under), () => rssFeed(site, feed, listed, site.site));
+    }
+    if (site.seo.markdownCopies) {
+        for (const p of listed)
+            generate(markdownCopyPath(p.route), () => markdownCopy(p.frontmatter.title, p.frontmatter.description, markdown.get(p.route) ?? ""));
     }
     const indexNow = site.integrations.indexNow;
     if (indexNow)
         generate(`${indexNow.key}.txt`, () => `${indexNow.key}\n`);
-    if (site.deploy.target === "cloudflare-pages" && model.redirects.length)
+    // Cloudflare Pages and Workers static assets both read _redirects and _headers.
+    const cloudflare = site.deploy.target === "cloudflare-pages" || site.deploy.target === "cloudflare-workers";
+    if (cloudflare && model.redirects.length)
         generate("_redirects", () => cloudflareRedirects(model.redirects));
-    if (site.deploy.target === "cloudflare-pages" && site.security.headers) {
+    if (cloudflare && site.security.headers) {
         const html = [...model.pages, ...(model.notFound ? [model.notFound] : []), ...model.redirects].map((p) => p.html);
         generate("_headers", () => headersFile(html, site));
     }
@@ -91,9 +149,10 @@ function addDiscoveryFiles(root, model) {
         else {
             const pages = listed.map((p) => ({
                 title: p.frontmatter.title,
-                url: absoluteUrl(site.site, p.route) ?? p.route,
+                // With Markdown copies, AI tools are pointed at the plain-text version (llmstxt.org).
+                url: site.seo.markdownCopies ? (absoluteUrl(site.site, `/${markdownCopyPath(p.route)}`) ?? `/${markdownCopyPath(p.route)}`) : (absoluteUrl(site.site, p.route) ?? p.route),
                 description: p.frontmatter.description,
-                body: p.body,
+                body: markdown.get(p.route) ?? "",
             }));
             generate("llms.txt", () => llmsTxt(site.title, site.description, pages));
             if (site.seo.llmsTxt.full)

package/dist/core/validate.d.ts

@@ -4,6 +4,8 @@
  */
 export declare function assertBranchName(value: string, flag?: string): string;
 export declare function assertCloudflareProject(value: string): string;
+/** Cloudflare Worker names: lowercase letters, digits and "-", up to 63 characters. */
+export declare function assertWorkerName(value: string): string;
 /** https://, ssh://, git@host:path, or a local path. Refuses options and git's command-running transports. */
 export declare function assertGitRemote(value: string): string;
 /** npm dependency spec for new projects: a version/range, "latest", or a local file: tarball. */

package/dist/core/validate.js

@@ -14,6 +14,12 @@ export function assertCloudflareProject(value) {
         throw new VageError(`Invalid --project "${value}". Use lowercase letters, digits and "-".`);
     return value;
 }
+/** Cloudflare Worker names: lowercase letters, digits and "-", up to 63 characters. */
+export function assertWorkerName(value) {
+    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(value))
+        throw new VageError(`Invalid Worker name "${value}". Use lowercase letters, digits and "-" (up to 63).`);
+    return value;
+}
 /** https://, ssh://, git@host:path, or a local path. Refuses options and git's command-running transports. */
 export function assertGitRemote(value) {
     if (value.startsWith("-") || /^(ext|fd)::/i.test(value) || /[\s\u0000-\u001f]/.test(value)) {

package/dist/deploy/cloudflare-pages.js

@@ -20,7 +20,9 @@ export async function deployCloudflarePages(root, options) {
     if (res.code !== 0) {
         const auth = /auth|login|token|unauthori[sz]ed|10000/i.test(output)
             ? " Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, or run `npx wrangler login`."
-            : "";
+            : /pages_build_output_dir|project not found|delegat|Workers/i.test(output)
+                ? ' Cloudflare now creates new sites as Workers rather than Pages projects. Set deploy.target to "cloudflare-workers" in vage.config.ts and run vage deploy again.'
+                : "";
         return { status: "failure", branch: options.branch, reason: `wrangler failed (exit ${res.code}).${auth}\n${tail(output)}` };
     }
     const deploymentUrl = output.match(/https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.pages\.dev/gi)?.at(-1);

package/dist/deploy/cloudflare-workers.d.ts

@@ -0,0 +1,59 @@
+import type { DeployStatus, Runner } from "./github-pages.js";
+/** In wrangler's own lookup order. */
+export declare const WRANGLER_CONFIGS: string[];
+/** Compatibility date for the generated config; Workers static assets need nothing newer. Checked 2026-10-23. */
+export declare const COMPATIBILITY_DATE = "2026-10-01";
+/** What vagejs needs to know from a project's own wrangler config. */
+export interface WranglerConfig {
+    file: string;
+    name?: string;
+    /** assets.directory, resolved against the project root. */
+    assetsDir?: string;
+    notFoundHandling?: string;
+}
+/**
+ * Reads name and assets settings from the project's wrangler config. Refuses setups where
+ * wrangler could pick a different file or Worker than the one shown: several config files,
+ * a CLOUDFLARE_ENV environment, or a .wrangler/deploy redirect.
+ */
+export declare function readWranglerConfig(root: string, env?: Record<string, string | undefined>): WranglerConfig | undefined;
+export interface WorkersPlan {
+    /** The Worker that will actually be deployed. */
+    worker: string;
+    /** The project's wrangler config, if it has one. */
+    config?: WranglerConfig;
+    warnings: string[];
+}
+/**
+ * Decides which Worker gets deployed, and refuses setups where the plan and what
+ * wrangler would actually do differ (another Worker name, or a folder other than dist/).
+ */
+export declare function planWorkersDeploy(root: string, requested: string | undefined): WorkersPlan;
+export interface WorkersDeployment extends DeployStatus {
+    worker: string;
+    /** How it was deployed: a new version switched to 100% (existing Worker), or a full first deploy. */
+    mode?: "version" | "first-deploy";
+    versionId?: string;
+}
+/**
+ * Deploys dist/ as a Cloudflare Worker with static assets (what Cloudflare now creates
+ * instead of Pages projects; `_headers` and `_redirects` still apply).
+ *
+ * - With a wrangler config in the project (needed for custom domains and routes), that
+ *   file is used as-is; `planWorkersDeploy` has already checked its name and folder.
+ *   Otherwise a temporary config pointing at dist/ is generated, so the project gains no files.
+ * - Existing Workers get `wrangler versions upload` + `versions deploy <id>@100%`: the new
+ *   version takes all traffic without re-applying routes or custom domains, so the site
+ *   stays up. Only Cloudflare's "Worker doesn't exist" error leads to a first `wrangler deploy`.
+ * - Success needs wrangler to succeed AND the live site to answer 200: `siteUrl` when set,
+ *   else the Worker's workers.dev URL (never a version preview URL).
+ */
+export declare function deployCloudflareWorkers(root: string, options: {
+    plan: WorkersPlan;
+    tag?: string;
+    siteUrl?: string;
+    run?: Runner;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    env?: Record<string, string | undefined>;
+}): Promise<WorkersDeployment>;