blume 2.0.3 → 2.1.1

package/src/deploy/platforms/types.ts

@@ -2,7 +2,10 @@ import type { JsonValue } from "../../core/adapter.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import type { ProjectContext } from "../../core/types.ts";
-import type { DeployAdapterKind } from "../adapters/registry.ts";
+import type {
+  DeployAdapterKind,
+  ResolvedDeployOptions,
+} from "../adapters/registry.ts";
 import type { DeployOutput } from "../adapters/types.ts";
 
 /**
@@ -15,8 +18,16 @@ import type { DeployOutput } from "../adapters/types.ts";
 
 /** How the generated `astro.config.mjs` constructs the `@astrojs/*` adapter. */
 export interface AstroAdapterSpec {
-  /** Top-level `defineConfig` entries the adapter needs beside itself. */
-  config: Record<string, JsonValue>;
+  /**
+   * Top-level `defineConfig` entries the adapter needs beside itself, some
+   * of them set from the deployment's own options.
+   */
+  config: (options: ResolvedDeployOptions) => Record<string, JsonValue>;
+  /**
+   * The deployment options `config` reads, which therefore stay out of the
+   * passthrough to the `@astrojs/*` constructor.
+   */
+  configOptions: string[];
   /** Blume's own constructor options; the user's passthrough is spread over them. */
   options: (context: ProjectContext) => Record<string, JsonValue>;
   /** The package the config imports the adapter from. */
@@ -115,13 +126,16 @@ export interface DeployPlatform {
   /**
    * Whether the adapter moves a server build's client output under
    * `deployment.base` (`dist/client/<base>/`, the directory Astro then hands
-   * `astro:build:done`) while the platform keeps serving `serverStaticDir`
-   * as the assets root. The files the platform reads there, like `_headers`,
+   * `astro:build:done`) while the platform keeps serving `dist/client` as
+   * the assets root. The files the platform reads there, like `_headers`,
    * belong above the directory Astro reports.
    */
   serverClientUnderBase: boolean;
   /** Where a server build's deploy bundle lands. */
   serverOutputDir: (context: ProjectContext) => string;
-  /** The directory a server build serves as static files. */
-  serverStaticDir: (context: ProjectContext) => string;
+  /**
+   * The directory a server build serves as static files, given the normalized
+   * `deployment.base` for a platform that serves them from `<dir>/<base>/`.
+   */
+  serverStaticDir: (context: ProjectContext, base: string) => string;
 }

package/src/deploy/platforms/vercel.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 
-import { join } from "pathe";
+import { dirname, join } from "pathe";
 
 import { crossOriginDiscoveryPaths } from "../../ai/ai-catalog.ts";
 import {
@@ -20,7 +20,10 @@ import {
   SIGNATURES_DIRECTORY_PATH,
   SIGNATURES_DIRECTORY_TYPE,
 } from "../../ai/web-bot-auth.ts";
+import { mountBasePath, normalizeBasePath } from "../../core/base-path.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
+import { isPatternPath, regexRedirect } from "../../core/redirect-patterns.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
 import type { ProjectContext } from "../../core/types.ts";
 import { VERCEL_ADAPTER_PACKAGE } from "../adapters/vercel.ts";
 import {
@@ -29,8 +32,17 @@ import {
   blumeDependencyNames,
   functionBundleVerdict,
 } from "../function-bundle.ts";
-import { buildVercelConfig } from "../redirects.ts";
-import { injectNegotiationRoutes } from "../vercel-negotiation.ts";
+import {
+  buildVercelConfig,
+  platformRedirects,
+  vercelPatternRoutes,
+} from "../redirects.ts";
+import {
+  injectNegotiationRoutes,
+  injectRedirectRoutes,
+  rebaseAdapterRoutes,
+} from "../vercel-negotiation.ts";
+import type { VercelRoute } from "../vercel-negotiation.ts";
 import { adapterRoot, toSiteUrl } from "./paths.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 
@@ -49,6 +61,14 @@ export const VERCEL_JSON_FILE: RedirectFile = {
 const buildOutputDir = (context: ProjectContext): string =>
   join(adapterRoot(context), ".vercel", "output");
 
+/** The static files a server build serves, under the base's directory. */
+const staticDir = (context: ProjectContext, base: string): string =>
+  join(buildOutputDir(context), "static", base);
+
+/** The project's normalized `deployment.base`, `""` for none. */
+const deploymentBase = (project: BlumeProject): string =>
+  normalizeBasePath(project.config.deployment.options.base);
+
 /**
  * Refuse to ship a function bundle that would crash at runtime: a bare import
  * the adapter's dependency trace silently dropped (see
@@ -92,18 +112,21 @@ export const emitVercelNegotiation = async (
   log: BuildLog
 ): Promise<void> => {
   const { config, context } = project;
-  const outputDir = buildOutputDir(context);
-  const configPath = join(outputDir, "config.json");
+  const configPath = join(buildOutputDir(context), "config.json");
   if (!existsSync(configPath)) {
     return;
   }
+  const base = deploymentBase(project);
   const routePaths = markdownRoutePaths(project);
+  // Keyed by the file's path in `static/`, under the base's directory.
   const overrides: Record<string, string> = {};
   if (hasApiCatalog(config)) {
-    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+    overrides[mountBasePath(base, API_CATALOG_PATH).slice(1)] =
+      API_CATALOG_TYPE;
   }
   if (config.agents.webBotAuth.keys.length > 0) {
-    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+    overrides[mountBasePath(base, SIGNATURES_DIRECTORY_PATH).slice(1)] =
+      SIGNATURES_DIRECTORY_TYPE;
   }
   // The homepage rewrite serves `/index.md` from the static layer, so its
   // `x-markdown-tokens` estimate has to ride the routing config; the runtime
@@ -113,7 +136,7 @@ export const emitVercelNegotiation = async (
   // The Markdown and JSON 404 routes point at the prerendered twins; only
   // wire each when the build actually emitted it (a project that owns `/404`
   // gets none).
-  const staticDir = join(outputDir, "static");
+  const builtDir = staticDir(context, base);
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
@@ -121,13 +144,14 @@ export const emitVercelNegotiation = async (
     overrides,
     home ? markdownTokenCount(agentMarkdown(home)) : undefined,
     {
-      json: existsSync(join(staticDir, "404.json")),
-      markdown: existsSync(join(staticDir, "404.md")),
+      json: existsSync(join(builtDir, "404.json")),
+      markdown: existsSync(join(builtDir, "404.md")),
     },
     crossOriginDiscoveryPaths(config),
     // Downloaded content assets are prerendered static files; only a build
     // that has them needs the SVG sandbox route.
-    existsSync(join(staticDir, "blume-assets"))
+    existsSync(join(builtDir, "blume-assets")),
+    base
   );
   if (injected === null) {
     log.warn(
@@ -141,6 +165,103 @@ export const emitVercelNegotiation = async (
   );
 };
 
+/**
+ * Route the pattern redirects (`/beta/:slug*`) in the adapter's Build Output
+ * config: Astro's `redirects` carry only the exact ones, since it can't
+ * prerender a pattern's pages, so the adapter never sees these.
+ */
+export const emitVercelPatternRedirects = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const routes = vercelPatternRoutes(platformRedirects(project));
+  const configPath = join(buildOutputDir(project.context), "config.json");
+  if (routes.length === 0 || !existsSync(configPath)) {
+    return;
+  }
+  const injected = injectRedirectRoutes(
+    await readFile(configPath, "utf-8"),
+    routes
+  );
+  if (injected === null) {
+    log.warn(
+      "Could not route the pattern redirects in .vercel/output/config.json, so paths they cover answer 404."
+    );
+    return;
+  }
+  await writeFile(configPath, injected, "utf-8");
+};
+
+type Redirect = ResolvedConfig["redirects"][number];
+
+/**
+ * The exact redirects as Build Output routes, matched the way the pattern ones
+ * are (see `regexRedirect`): the served path, a trailing slash optional.
+ */
+const exactRedirectRoutes = (redirects: Redirect[]): VercelRoute[] =>
+  redirects
+    .filter((redirect) => !isPatternPath(redirect.from))
+    .map(({ from, status, to }) => ({
+      headers: { Location: encodeURI(to) },
+      src: regexRedirect({ parts: [{ kind: "text", text: from }], status, to })
+        .source,
+      status,
+    }));
+
+/**
+ * Move a server build's static files under `deployment.base`.
+ * `@astrojs/vercel` copies them to the root of the Build Output tree's
+ * `static/`, while the pages request `<base>/_astro/…` and link to
+ * `<base>/…`, so nothing the site asks for would be found. Moved to
+ * `static/<base>/`, they're served at the base, as the routes that
+ * {@link rebaseVercelRoutes} moves there expect.
+ */
+export const moveStaticUnderBase = async (
+  context: ProjectContext,
+  base: string
+): Promise<void> => {
+  const root = staticDir(context, "");
+  if (!base || !existsSync(root)) {
+    return;
+  }
+  // Through a sibling, since the target lies inside the directory it moves.
+  const staging = join(buildOutputDir(context), "static-unbased");
+  await rename(root, staging);
+  const target = staticDir(context, base);
+  await mkdir(dirname(target), { recursive: true });
+  await rename(staging, target);
+};
+
+/**
+ * Move the adapter's routing config under `deployment.base` to match the
+ * static files (see `rebaseAdapterRoutes`), its exact redirects rebuilt from
+ * the configured ones. Resolves to false when the config can't be read: the
+ * adapter's routes would then miss every path under the base.
+ */
+export const rebaseVercelRoutes = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<boolean> => {
+  const base = deploymentBase(project);
+  const configPath = join(buildOutputDir(project.context), "config.json");
+  if (!base || !existsSync(configPath)) {
+    return true;
+  }
+  const rebased = rebaseAdapterRoutes(
+    await readFile(configPath, "utf-8"),
+    base,
+    exactRedirectRoutes(platformRedirects(project))
+  );
+  if (rebased === null) {
+    log.error(
+      `Could not move the routes in .vercel/output/config.json under the deployment base "${base}", so the site would not be served there.`
+    );
+    return false;
+  }
+  await writeFile(configPath, rebased, "utf-8");
+  return true;
+};
+
 /**
  * Vercel. A server build's Build Output tree lands at `.vercel/output` — at
  * the project root, because the adapter is handed that root up front: its
@@ -149,11 +270,14 @@ export const emitVercelNegotiation = async (
  * Static assets are served from the tree's `static/` half, so the deploy
  * artifacts are written there; headers (the discovery files', the sandbox on
  * downloaded SVGs) arrive through the routing config rather than a
- * `_headers` file, which Vercel never reads.
+ * `_headers` file, which Vercel never reads. The adapter ignores
+ * `deployment.base`, so under one the build moves the static files and the
+ * routes beneath it.
  */
 export const vercelPlatform: DeployPlatform = {
   astro: {
-    config: {},
+    config: () => ({}),
+    configOptions: [],
     options: () => ({}),
     package: VERCEL_ADAPTER_PACKAGE,
   },
@@ -176,11 +300,19 @@ export const vercelPlatform: DeployPlatform = {
     if (!ok) {
       return false;
     }
+    // A verify build moves its static files too, where the budget gate reads
+    // them (`serverStaticDir`).
+    await moveStaticUnderBase(context, deploymentBase(project));
     // An isolated verify only proves the bundle would ship; the routing
     // config is a deploy artifact and stays untouched.
-    if (!isolated) {
-      await emitVercelNegotiation(project, log);
+    if (isolated) {
+      return true;
+    }
+    if (!(await rebaseVercelRoutes(project, log))) {
+      return false;
     }
+    await emitVercelNegotiation(project, log);
+    await emitVercelPatternRedirects(project, log);
     return true;
   },
   hiddenRuntime: {
@@ -196,5 +328,5 @@ export const vercelPlatform: DeployPlatform = {
   redirectFiles: [VERCEL_JSON_FILE],
   serverClientUnderBase: false,
   serverOutputDir: buildOutputDir,
-  serverStaticDir: (context) => join(buildOutputDir(context), "static"),
+  serverStaticDir: staticDir,
 };

package/src/deploy/redirects.ts

@@ -1,5 +1,7 @@
 import {
   normalizeBasePath,
+  normalizePath,
+  stripBasePath,
   withAuthoredBasePath,
   withBasePath,
   withComposedBasePath,
@@ -7,16 +9,29 @@ import {
 import { routeSetFor, servesRoute } from "../core/locale-links.ts";
 import type { RouteSet } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import {
+  compileRedirects,
+  exactFirst,
+  expandRedirect,
+  isPatternPath,
+  underscoreRedirect,
+  vercelRedirect,
+} from "../core/redirect-patterns.ts";
+import type { RedirectRule } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { escapeVercelSource } from "./headers.ts";
 import type { VercelHeader } from "./headers.ts";
+import type { VercelRoute } from "./vercel-negotiation.ts";
 
 /**
  * Platform redirect files for a static build. Astro already emits redirect HTML
  * (meta-refresh) pages for static output, but that's a soft client redirect.
  * These give the host a real HTTP 3xx: Netlify/Cloudflare read `_redirects`,
  * Vercel reads `vercel.json`, and `blume-redirects.json` is a structured
- * manifest for anything else (Apache/nginx rules, an edge worker).
+ * manifest for anything else (Apache/nginx rules, an edge worker). A pattern
+ * redirect (`/beta/:slug*`) gets no redirect page, since Astro can't
+ * prerender one for paths it doesn't know; each host file carries it in that
+ * host's syntax (see `core/redirect-patterns.ts`).
  */
 
 type Redirect = ResolvedConfig["redirects"][number];
@@ -97,39 +112,116 @@ export const applyBaseToPlatformRedirects = (
     : redirects;
 };
 
+/**
+ * The raw-Markdown copies Blume serves beside every page (`/guide.md`,
+ * `/guide.mdx`; see `rawMarkdownEndpointTemplate`).
+ */
+const MIRROR_EXTENSIONS = [".md", ".mdx"] as const;
+
+/**
+ * Where a page's Markdown copy is served, from the page's served path and the
+ * deployment base that path carries: the endpoints name the root `index`.
+ */
+const mirrorPath = (path: string, base: string, extension: string): string => {
+  const route = stripBasePath(base, path);
+  return `${base}${route === "/" ? "/index" : route}${extension}`;
+};
+
+/**
+ * Based `redirects`, each exact one that moves a page followed by the same
+ * redirect for the page's Markdown copies: from a path no page is served at
+ * to one a page is, `/old.md` goes to `/new.md` (and `.mdx` alike), where it
+ * would otherwise 404 for an agent still reading the old URL. A pattern gets
+ * none; one that carries its capture over (`/beta/:slug*` → `/v2/:slug*`)
+ * already moves `/beta/guide.md` along. `pages` are the served page routes
+ * (carrying `basePath`, not `deployment.base`), and `bases` the deployment
+ * base each end carries: Astro's config leaves it off `from` (see
+ * {@link applyBaseToAstroRedirects}).
+ */
+export const withMirrorRedirects = (
+  redirects: Redirect[],
+  pages: RouteSet,
+  bases: { from: string; to: string }
+): Redirect[] =>
+  redirects.flatMap((redirect) => {
+    const from = normalizePath(redirect.from);
+    const to = normalizePath(redirect.to);
+    const movesPage =
+      !isPatternPath(redirect.from) &&
+      servesRoute(pages, stripBasePath(bases.to, to)) &&
+      !servesRoute(pages, stripBasePath(bases.from, from));
+    return movesPage
+      ? [
+          redirect,
+          ...MIRROR_EXTENSIONS.map((extension) => ({
+            from: mirrorPath(from, bases.from, extension),
+            status: redirect.status,
+            to: mirrorPath(to, bases.to, extension),
+          })),
+        ]
+      : [redirect];
+  });
+
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}. The one basing every consumer must
- * share: the emitted redirect files and the Cloudflare worker-first redirect
- * exemptions both compare these paths against real served URLs.
+ * {@link applyBaseToPlatformRedirects} plus the Markdown copies of each moved
+ * page ({@link withMirrorRedirects}), exact paths ahead of patterns: hosts
+ * try rules in order, and an exact redirect wins over a pattern that also
+ * covers its path. The one basing every consumer must share: the emitted
+ * redirect files and the server wrappers all compare these paths against
+ * real served URLs.
  */
 export const platformRedirects = (project: {
   config: ResolvedConfig;
   manifest: Pick<BlumeProject["manifest"], "routes">;
 }): Redirect[] => {
   const { config } = project;
-  return applyBaseToPlatformRedirects(
-    config.redirects,
-    config.basePath,
-    config.deployment.options.base ?? "",
-    routeSetFor(project.manifest.routes)
+  const base = normalizeBasePath(config.deployment.options.base);
+  const pages = routeSetFor(project.manifest.routes);
+  return exactFirst(
+    withMirrorRedirects(
+      applyBaseToPlatformRedirects(
+        config.redirects,
+        config.basePath,
+        base,
+        pages
+      ),
+      pages,
+      { from: base, to: base }
+    )
   );
 };
 
 /**
- * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
- * `force` appends Netlify's `!` to each status (`301!`), so the rule wins over
- * the redirect page Astro writes at `from`; Cloudflare, which always applies
- * its rules first, rejects a line carrying it.
+ * A redirect as the entries a host file lists: itself when its path is
+ * exact, else the rules its pattern expands to, in the host's syntax.
+ */
+const hostEntries = <Entry>(
+  redirect: Redirect,
+  exact: (redirect: Redirect) => Entry,
+  pattern: (rule: RedirectRule) => Entry
+): Entry[] => {
+  const rules = expandRedirect(redirect);
+  return rules.length > 0 ? rules.map(pattern) : [exact(redirect)];
+};
+
+/**
+ * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line,
+ * a pattern as `:placeholder`s and a `*` splat the destination reads as
+ * `:splat`. `force` appends Netlify's `!` to each status (`301!`), so the rule
+ * wins over the redirect page Astro writes at `from`; Cloudflare, which always
+ * applies its rules first, rejects a line carrying it.
  */
 export const buildNetlifyRedirects = (
   redirects: Redirect[],
   force = false
 ): string =>
   `${redirects
-    .map(
-      (redirect) =>
-        `${redirect.from} ${redirect.to} ${redirect.status}${force ? "!" : ""}`
+    .flatMap((redirect) =>
+      hostEntries(redirect, (exact) => exact, underscoreRedirect).map(
+        (entry) =>
+          `${entry.from} ${entry.to} ${redirect.status}${force ? "!" : ""}`
+      )
     )
     .join("\n")}\n`;
 
@@ -145,19 +237,25 @@ interface VercelConfig {
  * alternative to the boolean `permanent`) so the configured code ships exactly:
  * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
  * from the `_redirects` file, which preserves exact codes. A `source` is a
- * `path-to-regexp` pattern, so each exact `from` path is escaped: unescaped,
- * `/c++-guide` fails the whole config and `/faq(old)` never matches.
+ * `path-to-regexp` pattern, so each literal run of a `from` path is escaped:
+ * unescaped, `/c++-guide` fails the whole config and `/faq(old)` never
+ * matches. A pattern's captures are `path-to-regexp` params.
  */
 export const buildVercelConfig = (
   redirects: Redirect[],
   headers: readonly VercelHeader[] = []
 ): string => {
   const config: VercelConfig = {
-    redirects: redirects.map((redirect) => ({
-      destination: redirect.to,
-      source: escapeVercelSource(redirect.from),
-      statusCode: redirect.status,
-    })),
+    redirects: redirects.flatMap((redirect) =>
+      hostEntries(
+        redirect,
+        (exact) => ({
+          destination: exact.to,
+          source: escapeVercelSource(exact.from),
+        }),
+        (rule) => vercelRedirect(rule, escapeVercelSource)
+      ).map((entry) => ({ ...entry, statusCode: redirect.status }))
+    ),
   };
   if (headers.length > 0) {
     config.headers = headers;
@@ -165,7 +263,36 @@ export const buildVercelConfig = (
   return `${JSON.stringify(config, null, 2)}\n`;
 };
 
-/** Structured manifest for hosts that need manual wiring. */
+/**
+ * The pattern redirects as `_redirects` entries, for the `redirects` of a
+ * Netlify server build's Frameworks API config (see
+ * {@link buildNetlifyRedirects} for the syntax).
+ */
+export const netlifyPatternRedirects = (
+  redirects: Redirect[]
+): { from: string; status: number; to: string }[] =>
+  redirects.flatMap(expandRedirect).map((rule) => ({
+    ...underscoreRedirect(rule),
+    status: rule.status,
+  }));
+
+/**
+ * The pattern redirects as Build Output API routes, for a Vercel server
+ * build: the adapter routes only the exact redirects Astro's config carries.
+ * Each matches the served path, a trailing slash optional, and fills its
+ * `Location` from numbered captures, as the adapter's own redirect routes do.
+ */
+export const vercelPatternRoutes = (redirects: Redirect[]): VercelRoute[] =>
+  compileRedirects(redirects).map(([src, location, status]) => ({
+    headers: { Location: location },
+    src,
+    status,
+  }));
+
+/**
+ * Structured manifest for hosts that need manual wiring. A pattern stays as
+ * configured (`/beta/:slug*`), for the rule it becomes to be written by hand.
+ */
 export const buildRedirectManifest = (redirects: Redirect[]): string =>
   `${JSON.stringify(
     redirects.map((redirect) => ({

package/src/deploy/rss.ts

@@ -78,7 +78,9 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     const items: RssItem[] = pages
       .map((page) => ({
         date: pageDate(page),
-        description: page.description,
+        // A page with only a meta description (a GitHub release, whose
+        // summary goes in `seo.description`) still describes its item.
+        description: page.description ?? page.meta.seo.description,
         // Encode like the sitemap does: a route with spaces or non-ASCII
         // must still yield a valid <link>/<guid> URL after XML decoding.
         link: encodeURI(`${base}${mountBasePath(deployBase, page.route)}`),

package/src/deploy/sitemap.ts

@@ -6,7 +6,11 @@ import {
   discoverPagesSync,
   hasGeneratedChangelog,
 } from "../astro/pages.ts";
-import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  normalizePath,
+} from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
 
@@ -30,6 +34,30 @@ const lastmodTag = (value: string | undefined): string => {
     : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
 };
 
+/**
+ * Whether a page's own `seo.canonical` names another URL. The sitemap lists
+ * canonical URLs only, so such a page stays out — `blume audit` reports a
+ * listed one as NON_CANONICAL_IN_SITEMAP and expects it unlisted. Compared by
+ * decoded path, as the audit does: `served` is the page's path with the
+ * deployment base mounted, which the canonical carries too.
+ */
+const canonicalElsewhere = (
+  canonical: string | undefined,
+  served: string
+): boolean => {
+  if (!canonical) {
+    return false;
+  }
+  const { pathname } = new URL(canonical);
+  let path = pathname;
+  try {
+    path = decodeURI(pathname);
+  } catch {
+    // A malformed escape stays as written; it can't match the served path.
+  }
+  return normalizePath(path) !== normalizePath(served);
+};
+
 /** One emitted sitemap artifact: its dist-root filename and XML body. */
 export interface SitemapFile {
   name: string;
@@ -62,7 +90,8 @@ ${urls.join("\n")}
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
  * the generated `/changelog` index. Returns null when the sitemap is disabled
  * or no `site` is configured (absolute URLs are required for a valid sitemap).
- * Drafts, hidden, and `noindex` pages are excluded.
+ * Drafts, hidden, and `noindex` pages are excluded, and so is a page whose
+ * `seo.canonical` points elsewhere.
  *
  * Sites within the per-file URL cap get the single classic `sitemap.xml`;
  * larger sites get `sitemap.xml` as a sitemap index over numbered
@@ -87,7 +116,9 @@ export const buildSitemapFiles = (
   // or when their canonical points at a still-existing latest equivalent —
   // listing a URL whose canonical says "index the other page" invites the
   // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
-  // that exists only in an archived version stays listed (self-canonical).
+  // that exists only in an archived version stays listed (self-canonical),
+  // and a page's own `seo.canonical` wins over the version's default, as it
+  // does in the page head (see `canonicalElsewhere`).
   const { versions } = project.config;
   const archivedById = new Map(
     (versions?.archived ?? []).map((version) => [version.id, version])
@@ -109,6 +140,7 @@ export const buildSitemapFiles = (
     return Boolean(
       archived?.noindex ||
       (archived?.canonical === "latest" &&
+        !page.meta.seo.canonical &&
         currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
     );
   };
@@ -128,16 +160,18 @@ export const buildSitemapFiles = (
     urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
   };
   for (const page of project.graph.pages) {
+    const served = mountBasePath(deployBase, page.route);
     if (
       page.meta.draft ||
       page.meta.sidebar.hidden ||
       page.meta.seo.noindex ||
       ERROR_ROUTES.has(page.route) ||
-      archivedExcluded(page)
+      archivedExcluded(page) ||
+      canonicalElsewhere(page.meta.seo.canonical, served)
     ) {
       continue;
     }
-    pushUrl(mountBasePath(deployBase, page.route), page.lastModified);
+    pushUrl(served, page.lastModified);
   }
   // Custom `.astro` pages and the generated changelog index mount outside
   // `basePath` (they're injected at their pattern — see `blumeIntegration`), so