vagejs 0.3.5 → 0.5.0

package/README.md

@@ -13,13 +13,18 @@
 
 # vagejs
 
-An AI-native, static-first web framework. Write pages in Markdown, and vagejs builds a fast static site with SEO, `llms.txt`, accessibility and security handled for you. It's built so AI coding agents can use it without guessing. **Pre-release (0.x).**
+**A free static site generator built for AI coding assistants.** Your assistant (Claude Code, Cursor, Codex, Copilot) writes the pages; vagejs checks them before anything goes live. Write pages in Markdown and get a fast static site with SEO, `llms.txt`, accessibility and security handled for you. **Pre-release (0.x).**
+
+[Website](https://vagejs.com) · [Docs](https://vagejs.com/docs/) · [Use with AI assistants](https://vagejs.com/agents/) · [Changelog](https://vagejs.com/changelog/) · [Discussions](https://github.com/agevenkat/vagejs/discussions) · [LinkedIn](https://www.linkedin.com/company/vagejs/)
+
+<p align="center"><img src="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/demo.svg" alt="Terminal demo: create a vagejs site, install it, npm run check catches a broken link and names the file, the link is fixed, the check passes, and npm start runs the site." width="760"></p>
 
 - **Static by default**: plain HTML, no client JavaScript unless you add analytics.
 - **SEO built in**: `robots.txt`, `sitemap.xml`, `llms.txt`, canonical URLs, Open Graph and JSON-LD, generated from your pages.
 - **Checks before you ship**: `vage check` (links, SEO, structured data, accessibility) and `vage audit` (page-weight budgets, axe, optional Lighthouse and PageSpeed).
-- **Safe by default**: page content is sanitized; secrets, build output and force-pushes are refused; Cloudflare deploys get a computed Content-Security-Policy.
+- **Safe by default**: page content is sanitized; secrets, build output and force-pushes are refused; Cloudflare and Netlify deploys get a computed Content-Security-Policy.
 - **Agent-friendly**: every site ships with `AGENTS.md`, and `vage info --json` describes every command and config option.
+- **Runs everywhere**: macOS, Windows and Linux, tested on every change. Deploys to GitHub Pages, Cloudflare Workers and Netlify built in; any other static host (Vercel) works with `npm run build` and the `dist` folder.
 
 ## Quick start
 
@@ -31,9 +36,17 @@ cd my-site
 npm install
 npm start
 ```
-
 `npm start` opens the site in your browser. Edit `src/pages/index.md` and the page reloads. (`npm run dev` does the same without opening a browser, and prints the address.)
 
+### Windows
+
+vagejs works on Windows and is tested on Windows on every change.
+
+- **Node.js:** install Node.js **22.12 or newer** before creating a project. Then open a new PowerShell or Command Prompt window and check it with `node --version` and `npm --version`.
+- **PowerShell or Command Prompt:** the `npm` and `npx` commands in this README work in both. Command Prompt doesn't treat `#` as a comment, so leave out the `# …` notes shown after some commands.
+- **Line endings:** Windows usually saves files with CRLF line endings. vagejs handles them, so there's no need to convert files to LF.
+- **HTTP 431 in the browser:** open the direct address (`[::1]` or `127.0.0.1`) that `npm start` and `npm run dev` print. It's the same server, without the cookies other local projects left on `localhost`.
+
 ## Using vagejs
 
 ### Project layout
@@ -66,9 +79,9 @@ description: Plans and prices.
 Our plans start at …
 ```
 
-Save it as `src/pages/pricing.md` and it's served at `/pricing/`. `title` is required. `description`, `draft`, `noindex`, `canonical`, `image`, `type: article`, `author`, `datePublished` and `dateModified` are optional; see [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md).
+Save it as `src/pages/pricing.md` and it's served at `/pricing/`. `title` is required. `description`, `draft`, `noindex`, `canonical`, `image`, `type: article`, `author`, `datePublished`, `dateModified` and `tags` are optional (a future `datePublished` schedules the page; each tag gets a page at `/tags/<tag>/`); see [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md).
 
-Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` and `height` from the file, so the page doesn't jump while loading. With `images: { optimize: true }` (and `npm install --save-dev sharp`), vagejs also makes resized WebP copies of images in page content and offers them with `srcset`.
+Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` and `height` from the file, so the page doesn't jump while loading. With `images: { optimize: true }` (and `npm install --save-dev sharp`), vagejs also makes resized WebP copies of images in page content and offers them with `srcset`. Add `avif: true` for AVIF copies too, offered first through `<picture>` (usually smaller; slower to make). `vage audit` counts the copy browsers download, not the original.
 
 ### Navigation, feeds and AI extras
 
@@ -140,6 +153,7 @@ npx vage deploy:github --remote https://github.com/you/site.git   # check, build
 npx vage deploy                                                  # GitHub Pages via Actions
 npx vage deploy --target cloudflare-workers --project my-site    # Cloudflare Workers: new version, no downtime
 npx vage deploy --target cloudflare-pages --project my-site      # older Cloudflare Pages projects
+npx vage deploy --target netlify --project my-site               # Netlify production deploy (deploy.target: "netlify")
 ```
 
 Every deploy shows its plan and asks for confirmation (`--dry-run` to preview, `--yes` to skip). It reports success only after the host confirms.
@@ -173,6 +187,15 @@ npx vage info --json    # commands, options, config and frontmatter JSON Schemas
 npx vage check --json   # findings with file, rule and fix hints
 ```
 
+Or let the assistant call vagejs directly over MCP. `npx vage mcp` runs an MCP server with read-only tools (`vage_info`, `vage_check`, `vage_pages`, `vage_links`); it needs the optional SDK:
+
+```bash
+npm install --save-dev @modelcontextprotocol/sdk
+claude mcp add --transport stdio --scope project vagejs -- npx -p vagejs vage mcp   # Claude Code, in the project folder
+```
+
+Other assistants: `{ "mcpServers": { "vagejs": { "command": "npx", "args": ["-p", "vagejs", "vage", "mcp", "--root", "/absolute/path/to/the/site"] } } }`. `-p vagejs` makes npx run the vagejs installed in the project, and never a different package that happens to be called `vage`. Approving link domains and deploying stay CLI commands for the site owner.
+
 ## Command reference
 
 ```bash
@@ -187,6 +210,7 @@ vage deploy:github [--remote URL] [--branch B] [-m MSG] [--dry-run] [--yes] [--j
 vage deploy        [--remote URL] [--no-wait] [--dry-run] [--yes] # GitHub Pages via Actions; confirms with GitHub
 vage deploy --target cloudflare-workers [--project NAME]          # new Worker version at 100%; custom domains stay up
 vage deploy --target cloudflare-pages --project NAME [--branch B] # Wrangler upload; preview URL per branch
+vage deploy --target netlify [--project SITE]                     # netlify-cli production deploy, then a live check
 vage indexnow --changed-since REF | --urls … | --all              # IndexNow URL notification (asks first)
 vage connect gsc|ga4 / vage disconnect google      # read-only Google OAuth (PKCE, loopback); token outside the repo
 vage connect pagespeed|crux / vage disconnect …   # save your own Google API key for audit --url (outside the repo)
@@ -197,7 +221,7 @@ vage info     [--json]                            # commands + config/frontmatte
 
 ## Planned, not implemented
 
-Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server, AVIF images.
+Bing Webmaster Tools API, a Vercel adapter, CMS content sources, multi-language sites, base paths, sitemap indexes.
 
 ## Security
 
@@ -225,6 +249,8 @@ Also protect the accounts around the site: two-factor authentication on GitHub,
 
 ## Contributing
 
+New contributors are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and the issues labeled [good first issue](https://github.com/agevenkat/vagejs/labels/good%20first%20issue). Questions and ideas go in [Discussions](https://github.com/agevenkat/vagejs/discussions).
+
 ```bash
 npm install
 npm run typecheck

package/dist/audit/budgets.js

@@ -64,11 +64,31 @@ export function measurePages(outDir, pages, site) {
         for (const l of doc.querySelectorAll('link[rel="preload"][as="font"]'))
             add(l.getAttribute("href"), "font", route);
         for (const img of doc.querySelectorAll("img"))
-            add(img.getAttribute("src"), "image", route);
+            add(downloadedImage(img), "image", route);
         weight.total = Object.values(weight.bytes).reduce((a, b) => a + b, 0);
         return weight;
     });
 }
+/**
+ * The file a browser actually downloads for an <img>: the first <source> of its
+ * <picture> (AVIF from images.avif), else its srcset (WebP), else src. With several
+ * widths, the largest counts: what a wide, high-density screen loads.
+ */
+function downloadedImage(img) {
+    const source = img.parentNode?.rawTagName?.toLowerCase() === "picture" ? img.parentNode.querySelector("source[srcset]") : null;
+    const srcset = source?.getAttribute("srcset") ?? img.getAttribute("srcset");
+    if (!srcset)
+        return img.getAttribute("src");
+    let best;
+    for (const entry of srcset.split(",")) {
+        const [url, descriptor = "1x"] = entry.trim().split(/\s+/);
+        // "960w" (width) or "2x" (density): either way, the biggest number is the biggest file.
+        const size = Number(/^([\d.]+)[wx]$/.exec(descriptor)?.[1] ?? 0);
+        if (url && (!best || size > best.size))
+            best = { url, size };
+    }
+    return best?.url ?? img.getAttribute("src");
+}
 const BUDGET_KEYS = [
     ["javascriptKb", "javascript"],
     ["cssKb", "css"],

package/dist/checks/check.js

@@ -62,10 +62,17 @@ export function checkSite(root, model) {
         if (e.route)
             outputs.add(`${e.route}index.html`);
     const drafts = new Set(model.draftRoutes);
+    const scheduled = new Map(model.skippedScheduled.map((s) => [s.route, s.date]));
     const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
-    for (const page of pages) {
+    const docs = pages.map((page) => ({ page, doc: parse(page.html) }));
+    // Link targets on each output file: element ids and <a name>, for #fragment links.
+    const anchors = new Map(docs.map(({ page, doc }) => [
+        `/${page.outFile}`,
+        new Set([...doc.querySelectorAll("[id]").map((el) => el.getAttribute("id")), ...doc.querySelectorAll("a[name]").map((el) => el.getAttribute("name"))]),
+    ]));
+    for (const { page, doc } of docs) {
         const add = (f) => findings.push({ ...f, page: page.route, source: page.source });
-        checkPage(page, parse(page.html), model, outputs, drafts, add);
+        checkPage(page, doc, model, outputs, drafts, scheduled, anchors, add);
     }
     findings.push(...checkDuplicates(listedPages(model)));
     findings.push(...checkRobots(model));
@@ -73,7 +80,7 @@ export function checkSite(root, model) {
     findings.push(...checkOutboundLinks(root, model));
     return findings;
 }
-function checkPage(page, doc, model, outputs, drafts, add) {
+function checkPage(page, doc, model, outputs, drafts, scheduled, anchors, add) {
     const indexable = !page.meta.noindex;
     if (model.site.security.spamPatterns) {
         const text = `${doc.querySelector("body")?.text ?? ""} ${doc.querySelectorAll("a[href]").map((a) => a.getAttribute("href")).join(" ")}`;
@@ -101,6 +108,25 @@ function checkPage(page, doc, model, outputs, drafts, add) {
     if (titles.length !== 1 || !titles[0].text.trim()) {
         add({ rule: "title", severity: "error", message: `Expected exactly one non-empty <title>, found ${titles.length}.`, docs: DOCS.title });
     }
+    // Only pages shown in search results can be shortened there.
+    const renderedTitle = titles[0]?.text.trim() ?? "";
+    if (indexable && renderedTitle.length > 60) {
+        add({
+            rule: "title-length",
+            severity: "warning",
+            message: `Rendered <title> in "${page.source}" is ${renderedTitle.length} characters; it may be shortened in search results.`,
+            docs: DOCS.title,
+        });
+    }
+    const description = doc.querySelector('meta[name="description"]')?.getAttribute("content")?.trim() ?? "";
+    if (indexable && description.length > 160) {
+        add({
+            rule: "meta-description-length",
+            severity: "warning",
+            message: `Meta description in "${page.source}" is ${description.length} characters; it may be shortened in search results.`,
+            docs: DOCS.description,
+        });
+    }
     if (indexable && !doc.querySelector('meta[name="description"]')?.getAttribute("content")) {
         add({
             rule: "meta-description",
@@ -148,6 +174,10 @@ function checkPage(page, doc, model, outputs, drafts, add) {
         if (!a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])")) {
             add({ rule: "link-text", severity: "warning", message: `Link to "${href}" has no accessible text.`, docs: DOCS.linkPurpose });
         }
+        if (/^#./.test(href.trim())) {
+            checkFragment(href, `/${page.outFile}`, anchors, add);
+            continue;
+        }
         const target = internalPath(href, page.route, model.site.site);
         if (target === undefined)
             continue;
@@ -156,12 +186,19 @@ function checkPage(page, doc, model, outputs, drafts, add) {
             continue;
         }
         const resolved = resolveOutput(target, outputs);
+        if (resolved === "ok")
+            checkFragment(href, target.endsWith("/") ? `${target}index.html` : target, anchors, add);
         if (resolved === "missing") {
-            const draft = drafts.has(target.endsWith("/") ? target : `${target}/`);
+            const route = target.endsWith("/") ? target : `${target}/`;
+            const date = scheduled.get(route);
             add({
                 rule: "link-broken",
                 severity: "error",
-                message: draft ? `Link to "${href}" points to a draft page, which is not published.` : `Link to "${href}" does not match any page or file.`,
+                message: drafts.has(route)
+                    ? `Link to "${href}" points to a draft page, which is not published.`
+                    : date
+                        ? `Link to "${href}" points to a page scheduled for ${date}, which is not published yet.`
+                        : `Link to "${href}" does not match any page or file.`,
             });
         }
         else if (resolved === "needs-slash") {
@@ -423,6 +460,27 @@ function internalPath(href, base, site) {
         return MALFORMED;
     }
 }
+/**
+ * A #fragment must match an id (or <a name>) on the page it points to; otherwise the
+ * page opens at the top instead of the section. "#top" and text fragments (#:~:text=)
+ * work without one. Files that aren't rendered pages (PDFs, redirects) aren't checked.
+ */
+function checkFragment(href, outFile, anchors, add) {
+    const ids = anchors.get(outFile);
+    const hash = href.indexOf("#");
+    if (!ids || hash === -1)
+        return;
+    let fragment;
+    try {
+        fragment = decodeURIComponent(href.slice(hash + 1));
+    }
+    catch {
+        fragment = href.slice(hash + 1);
+    }
+    if (!fragment || fragment.toLowerCase() === "top" || fragment.startsWith(":~:") || ids.has(fragment))
+        return;
+    add({ rule: "link-fragment", severity: "warning", message: `Link to "${href}": no element with id "${fragment}" on that page, so it opens at the top.` });
+}
 function resolveOutput(target, outputs) {
     if (target.endsWith("/"))
         return outputs.has(`${target}index.html`) ? "ok" : "missing";

package/dist/cli/index.js

@@ -56,6 +56,8 @@ cli
         console.log(`  ${"".padEnd(30)} -> ${file}`);
     for (const draft of result.skippedDrafts)
         console.log(`  (draft, skipped) ${draft}`);
+    for (const s of result.skippedScheduled)
+        console.log(`  (scheduled for ${s.date}, skipped) ${s.source}`);
     for (const warning of result.warnings)
         console.log(`\nWarning: ${warning}`);
     console.log(`\nBuilt ${result.pages.length} page(s) into ${result.outDir} in ${result.durationMs}ms`);
@@ -142,6 +144,35 @@ cli
     if (opts.open && target)
         openBrowser(target);
 }));
+cli
+    .command("new <kind> <name>", 'Start a page (vage new page pricing) or a post (vage new post "Our first launch") as a draft with valid frontmatter')
+    .option("--root <dir>", "Project root", { default: "." })
+    .option("--title <text>", "Page title (pages; default from the path)")
+    .option("--description <text>", "One or two sentences for search results")
+    .option("--under <folder>", "Posts: section folder under src/pages (default: blog)")
+    .option("--date <YYYY-MM-DD>", "Posts: datePublished (default: today)")
+    .option("--author <name>", "Posts: author (only written when given)")
+    .option("--slug <name>", "Posts: file name, for titles without Latin letters or digits")
+    .option("--json", "Print machine-readable JSON")
+    .action((kind, name, opts) => run(opts, async () => {
+    if (kind !== "page" && kind !== "post")
+        throw new VageError(`Unknown kind "${kind}". Use vage new page <path> or vage new post "<title>".`);
+    const { createPage } = await import("./new.js");
+    // cac turns numeric values (--title 123) into numbers, so every option is read as text.
+    const text = (v) => (v === undefined ? undefined : String(v));
+    const created = createPage(opts.root, kind, String(name), { title: text(opts.title), description: text(opts.description), under: text(opts.under), date: text(opts.date), author: text(opts.author), slug: text(opts.slug) });
+    if (opts.json)
+        return print({ ok: true, ...created });
+    console.log(`Created ${created.file} (draft) for ${created.route}`);
+    console.log("Preview it with npm start (drafts show there); remove `draft: true` to publish it, then run npm run check.");
+}));
+cli
+    .command("mcp", "Run an MCP server over stdio so AI assistants can check this site (read-only tools; needs @modelcontextprotocol/sdk)")
+    .option("--root <dir>", "Project root", { default: "." })
+    .action((opts) => run({}, async () => {
+    const { startMcpServer } = await import("../mcp/server.js");
+    await startMcpServer(opts.root, { version, info: () => frameworkInfo(cli, version) });
+}));
 cli
     .command("info", "Describe commands, config and frontmatter (use --json for agents)")
     .option("--json", "Print machine-readable JSON")
@@ -174,10 +205,10 @@ cli
     reportPublish(result);
 }));
 cli
-    .command("deploy", "Deploy: GitHub Pages (workflow + push, waits for GitHub), Cloudflare Workers (new version, no downtime) or Cloudflare Pages")
+    .command("deploy", "Deploy: GitHub Pages (workflow + push, waits for GitHub), Cloudflare Workers (new version, no downtime), Cloudflare Pages or Netlify")
     .option("--root <dir>", "Project root", { default: "." })
-    .option("--target <host>", "github-pages, cloudflare-workers or cloudflare-pages (default: deploy.target in config)")
-    .option("--project <name>", "Cloudflare Pages project or Worker name (default: deploy.cloudflareProject / cloudflareWorker)")
+    .option("--target <host>", "github-pages, cloudflare-workers, cloudflare-pages or netlify (default: deploy.target in config)")
+    .option("--project <name>", "Cloudflare Pages project, Worker or Netlify site name (default: deploy.cloudflareProject / cloudflareWorker / netlifySite)")
     .option("--remote <url>", "Git URL to add as origin if there is none")
     .option("--branch <name>", "Branch for a new repository (default: main)")
     .option("-m, --message <msg>", "Commit message")
@@ -193,8 +224,13 @@ cli
         return deployToCloudflare(opts, config.deploy.cloudflareProject);
     if (target === "cloudflare-workers")
         return deployToWorkers(opts, config.deploy.cloudflareWorker ?? config.deploy.cloudflareProject, config.site);
+    if (target === "netlify") {
+        if (config.deploy.target !== "netlify")
+            throw new VageError('Set deploy.target to "netlify" in vage.config.ts, so the build writes Netlify\'s _redirects and _headers.');
+        return deployToNetlify(opts, config.deploy.netlifySite, config.site);
+    }
     if (target !== "github-pages")
-        throw new VageError(`Unknown --target "${target}". Use github-pages, cloudflare-workers or cloudflare-pages.`);
+        throw new VageError(`Unknown --target "${target}". Use github-pages, cloudflare-workers, cloudflare-pages or netlify.`);
     const { publish } = await import("../deploy/publish.js");
     const pages = await import("../deploy/github-pages.js");
     // Stop before pushing a site GitHub Pages would serve from a subfolder (its links would break).
@@ -460,7 +496,9 @@ cli
         urls = opts.urls.split(",").map((u) => abs(u.trim()));
     else if (opts.changedSince) {
         const { changedPageRoutes } = await import("../deploy/git.js");
-        urls = (await changedPageRoutes(root, opts.changedSince)).map(abs);
+        // Deleted pages are submitted too (so engines drop them); drafts and scheduled pages aren't live yet.
+        const unpublished = new Set([...model.draftRoutes, ...model.skippedScheduled.map((s) => s.route)]);
+        urls = (await changedPageRoutes(root, opts.changedSince)).filter((r) => !unpublished.has(r)).map(abs);
         if (!urls.length)
             return opts.json ? print({ ok: true, submitted: 0 }) : console.log(`No page changes since ${opts.changedSince}.`);
     }
@@ -618,6 +656,40 @@ async function deployToWorkers(opts, configuredWorker, siteUrl) {
     if (deployment.status === "failure")
         process.exit(1);
 }
+async function deployToNetlify(opts, configuredSite, siteUrl) {
+    const site = opts.project ?? configuredSite;
+    if (!site)
+        throw new VageError("No Netlify site. Pass --project <site name or ID> or set deploy.netlifySite in vage.config.ts (create the site in Netlify first).");
+    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(site))
+        throw new VageError(`"${site}" isn't a Netlify site name or ID (lowercase letters, digits and hyphens).`);
+    const root = path.resolve(opts.root);
+    const { check } = await import("../checks/check.js");
+    const checked = await check(root);
+    if (checked.errors)
+        throw new VageError(`vage check found ${checked.errors} error(s). Fix them before deploying.`);
+    const result = await build(root);
+    const { deployNetlify, NETLIFY_CLI } = await import("../deploy/netlify.js");
+    const steps = [
+        `upload ${result.outDir} (${result.pages.length} page(s), ${result.files.length} generated file(s)) to the Netlify site "${site}" (production)`,
+        `runs: npx ${NETLIFY_CLI} deploy --dir dist --prod --no-build --site ${site}`,
+        `verifies: ${siteUrl ?? "the site's Netlify URL"} answers 200`,
+    ];
+    const lines = ["Deploy plan (Netlify)", ...steps.map((s) => `  • ${s}`)];
+    if (!(await askConfirm(lines, opts))) {
+        if (opts.dryRun)
+            return opts.json ? print({ ok: true, dryRun: true, target: "netlify", site, steps }) : console.log("Dry run: nothing deployed.");
+        return opts.json ? print({ ok: false, status: "aborted" }) : console.log("Nothing deployed.");
+    }
+    const deployment = await deployNetlify(root, { site, siteUrl });
+    if (opts.json)
+        print({ ok: deployment.status !== "failure", target: "netlify", deployment });
+    else if (deployment.status === "success")
+        console.log(`Deployed and verified: ${deployment.pageUrl}${deployment.deployId ? ` (deploy ${deployment.deployId})` : ""}`);
+    else
+        console.log(`Deployment ${deployment.status === "failure" ? "FAILED" : "not confirmed"}: ${deployment.reason}`);
+    if (deployment.status === "failure")
+        process.exit(1);
+}
 async function confirmPlan(plan, opts, extra) {
     const lines = [`Publish plan for ${plan.root}`];
     if (plan.initRepo)

package/dist/cli/info.d.ts

@@ -88,6 +88,7 @@ export declare function frameworkInfo(cli: CAC, version: string): {
         VAGE_CONFIG_DIR: string;
         CLOUDFLARE_API_TOKEN: string;
         CLOUDFLARE_ACCOUNT_ID: string;
+        NETLIFY_AUTH_TOKEN: string;
     };
     notImplemented: string[];
 };

package/dist/cli/info.js

@@ -34,7 +34,7 @@ export function frameworkInfo(cli, version) {
                 "two files mapping to one route is an error",
             ],
             layouts: "see `layouts`",
-            drafts: "draft: true pages render in `vage dev` for preview, are skipped by build, and never appear in `pages`",
+            drafts: "draft: true pages render in `vage dev` for preview, are skipped by build, and never appear in `pages`. A future datePublished does the same until a build on or after that date (scheduled pages)",
         },
         layouts: {
             file: "src/layouts/<name>.ts, chosen with `layout: <name>` in frontmatter (default: default)",
@@ -63,7 +63,7 @@ export function frameworkInfo(cli, version) {
             feeds: 'seo.feeds: [{ under: "/blog/" }] writes /blog/feed.xml (RSS 2.0) and links it from that section\'s pages',
             markdownCopies: "seo.markdownCopies: true publishes /<path>.md copies of listed pages, made from each page's <main> and linked with rel=alternate type=text/markdown; layouts mark repeated extras (share links, calls to action) with data-vage-copy=\"skip\". On Cloudflare, _headers gives each copy a canonical Link header to its page",
             lastmod: 'seo.lastmod: "git" takes sitemap <lastmod> from each page\'s last commit (dateModified wins; skipped in shallow clones)',
-            images: 'images: { optimize: true } (needs the sharp package) makes resized WebP copies of content images in /_vage/img/ and adds srcset/sizes',
+            images: 'images: { optimize: true } (needs the sharp package) makes resized WebP copies of content images in /_vage/img/ and adds srcset/sizes; images: { avif: true } also makes AVIF copies, offered first through <picture>',
             navigation: "frontmatter order and navTitle; helpers tree(), breadcrumbs(), neighbors(); PageSummary.label",
         },
         checks: {
@@ -88,8 +88,9 @@ export function frameworkInfo(cli, version) {
             "llms-full.txt (opt-in)",
             "404.html",
             "redirect pages",
+            "/tags/<tag>/ pages for tags used in frontmatter (tags.pages)",
             "<indexnow-key>.txt (opt-in)",
-            "_redirects and _headers (cloudflare-workers and cloudflare-pages targets)",
+            "_redirects and _headers (cloudflare-workers, cloudflare-pages and netlify targets)",
             "<section>/feed.xml (seo.feeds)",
             "/<path>.md Markdown copies of listed pages (seo.markdownCopies)",
             "/_vage/img/*.webp resized images (images.optimize)",
@@ -102,14 +103,14 @@ export function frameworkInfo(cli, version) {
             VAGE_CONFIG_DIR: "optional; where the Google token is stored (default: OS user config dir)",
             CLOUDFLARE_API_TOKEN: "for Cloudflare deploys (cloudflare-workers or cloudflare-pages targets), or run `npx wrangler login`",
             CLOUDFLARE_ACCOUNT_ID: "for Cloudflare deploys (cloudflare-workers or cloudflare-pages targets)",
+            NETLIFY_AUTH_TOKEN: "for Netlify deploys (netlify target), or run `npx netlify-cli login`",
         },
         notImplemented: [
             "Bing Webmaster Tools API (use IndexNow for URL submission)",
-            "Netlify and Vercel deploy adapters",
+            "A Vercel deploy adapter (Vercel serves dist/ as plain files)",
+            "RSS feeds per tag",
             "CMS / external content-source adapters",
             "hreflang / multi-language sites, base paths, sitemap indexes",
-            "MCP server",
-            "AVIF images and <picture> (images.optimize makes WebP copies offered with srcset)",
         ],
     };
 }

package/dist/cli/new.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `vage new page <path>` and `vage new post <title>`: start a page with valid frontmatter.
+ * New files are drafts (`draft: true`), so placeholder text can't be published by
+ * accident: the dev server shows them, `vage build` skips them until the line is removed.
+ * Without a description, a comment marks where one goes (search engines then get the
+ * site's description, or nothing): vagejs never writes placeholder text that could publish.
+ */
+export interface NewOptions {
+    title?: string;
+    description?: string;
+    /** Posts: the section folder under src/pages (default "blog"). */
+    under?: string;
+    /** Posts: YYYY-MM-DD (default: today, local time). */
+    date?: string;
+    /** Posts: only written when given; vagejs never invents an author. */
+    author?: string;
+    /** Posts: the file name, when the title has no Latin letters or digits to make one from. */
+    slug?: string;
+}
+export interface Created {
+    file: string;
+    route: string;
+    draft: true;
+}
+/** "Getting Started: Part 2!" -> "getting-started-part-2" */
+export declare function slugify(text: string): string;
+export declare function createPage(root: string, kind: "page" | "post", name: string, options?: NewOptions): Created;

package/dist/cli/new.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { VageError } from "../core/errors.js";
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
+/** "Getting Started: Part 2!" -> "getting-started-part-2" */
+export function slugify(text) {
+    return text
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80)
+        .replace(/-+$/, "");
+}
+const titleFromSlug = (slug) => {
+    const last = slug.split("/").at(-1);
+    return last === "index" ? "Overview" : last.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
+};
+const today = () => {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+};
+/** YAML double-quoted scalars are JSON strings, so any title is written safely. */
+const yaml = (value) => JSON.stringify(value);
+export function createPage(root, kind, name, options = {}) {
+    const pagesDir = path.join(path.resolve(root), "src", "pages");
+    if (!fs.existsSync(pagesDir))
+        throw new VageError(`No src/pages folder in ${path.resolve(root)}. Run this inside a vagejs project.`);
+    // One line each: a line break would end up in the heading and fail the frontmatter schema.
+    for (const [label, value] of [["title", kind === "post" ? name : options.title], ["description", options.description], ["author", options.author]]) {
+        if (value !== undefined && /[\u0000-\u001f\u007f]/.test(value))
+            throw new VageError(`The ${label} must be one line of text, without line breaks or tabs.`);
+    }
+    let slug;
+    let title;
+    if (kind === "page") {
+        slug = name.replace(/^\/+|\/+$/g, "").replace(/\.md$/, "");
+        if (!SLUG.test(slug))
+            throw new VageError(`"${name}" isn't a valid page path. Use lowercase letters, numbers and hyphens, with / between folders (e.g. pricing or docs/setup).`);
+        title = options.title?.trim() || titleFromSlug(slug);
+    }
+    else {
+        title = name.trim();
+        if (!title)
+            throw new VageError('Give the post a title, e.g. vage new post "Our first launch".');
+        const under = (options.under ?? "blog").replace(/^\/+|\/+$/g, "");
+        if (!SLUG.test(under))
+            throw new VageError(`"${options.under}" isn't a valid section folder. Use lowercase letters, numbers, hyphens and /.`);
+        const base = options.slug !== undefined ? options.slug : slugify(title);
+        if (!base)
+            throw new VageError(`Couldn't make a file name from "${name}". Add --slug <name> (lowercase letters, numbers and hyphens).`);
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(base))
+            throw new VageError(`"${base}" isn't a valid --slug. Use lowercase letters, numbers and hyphens.`);
+        slug = `${under}/${base}`;
+    }
+    if (options.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(options.date))
+        throw new VageError(`--date must be YYYY-MM-DD, not "${options.date}".`);
+    const route = slug === "index" ? "/" : `/${slug.replace(/(^|\/)index$/, "")}/`.replace(/\/+/g, "/");
+    const rel = path.join("src", "pages", `${slug}.md`);
+    const file = path.join(pagesDir, `${slug}.md`);
+    // A page at /x/ can come from x.md or x/index.md: refuse either, never overwrite.
+    const twin = slug.endsWith("/index") ? path.join(pagesDir, `${slug.slice(0, -"/index".length)}.md`) : path.join(pagesDir, slug, "index.md");
+    for (const existing of [file, twin]) {
+        if (fs.existsSync(existing))
+            throw new VageError(`${path.relative(path.resolve(root), existing)} already exists, so ${route} is taken. Pick another name, or edit that file.`);
+    }
+    const lines = ["---", `title: ${yaml(title)}`];
+    if (options.description?.trim())
+        lines.push(`description: ${yaml(options.description.trim())}`);
+    else
+        lines.push("# description: one or two sentences for search results (until then, the site's description is used)");
+    if (kind === "post") {
+        lines.push("type: article", `datePublished: ${options.date ?? today()}`);
+        if (options.author?.trim())
+            lines.push(`author: ${yaml(options.author.trim())}`);
+    }
+    lines.push("# Remove the next line when the page is ready to publish.", "draft: true", "---", "", `# ${title}`, "", "Write here.", "");
+    // Never write through a symlinked folder: it can point outside the project.
+    let existing = path.dirname(file);
+    while (!fs.existsSync(existing))
+        existing = path.dirname(existing);
+    const realPages = fs.realpathSync(pagesDir);
+    const realParent = fs.realpathSync(existing);
+    if (realParent !== realPages && !realParent.startsWith(realPages + path.sep))
+        throw new VageError(`${path.relative(path.resolve(root), existing)} leads outside src/pages (a symlink?). Create the page in a regular folder.`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(file, lines.join("\n"), { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            throw new VageError(`${rel} already exists, so ${route} is taken. Pick another name, or edit that file.`);
+        throw err;
+    }
+    return { file: rel, route, draft: true };
+}

package/dist/content/markdown.d.ts

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

package/dist/content/markdown.js

@@ -30,6 +30,10 @@ export const frontmatterSchema = z.looseObject({
     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."),
+    tags: z
+        .array(singleLine.regex(/[\p{L}\p{N}]/u, "each tag needs a letter or digit (it becomes the address /tags/<tag>/)"))
+        .optional()
+        .describe('Topics, e.g. [SEO, AI]. Each tag gets a page at /tags/<tag>/ listing its pages (tags.pages); collection(pages, { tag: "SEO" }) picks them.'),
 });
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 const marked = new Marked({ gfm: true });

package/dist/content/optimize.d.ts

@@ -1,6 +1,7 @@
 /**
  * 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
+ * page content, offered to browsers with srcset; with images.avif, AVIF copies too,
+ * offered first through <picture>. 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.
  */
@@ -9,15 +10,18 @@ export interface ImageOptions {
     widths: number[];
     quality: number;
     sizes: string;
+    avif?: boolean;
 }
 export interface Variants {
-    /** "url 480w, url 960w" */
+    /** "url 480w, url 960w" (WebP) */
     srcset: string;
+    /** The same widths as AVIF, when images.avif is on. */
+    avifSrcset?: 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>;
+/** Turns an image into WebP (or AVIF) at a given width. Injected in tests; sharp otherwise. */
+export type Resize = (input: Buffer, width: number, quality: number, format?: "webp" | "avif") => 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. */