blume 1.4.2 → 1.4.3

package/src/core/frontmatter.ts

@@ -28,13 +28,57 @@ const withYamlEngine = <O>(options: O): O =>
     },
   }) as O;
 
+/**
+ * True when a document's leading `---` line is a CommonMark thematic break,
+ * not a front matter fence. Two shapes qualify (mirroring
+ * `linesWithoutFrontMatter` in `sources/normalize.ts`):
+ *   - the next line is blank (or absent) — YAML metadata starts on the very
+ *     next line, so a gap means the body *opens* with a divider (e.g. a
+ *     Notion page whose first block is one);
+ *   - no closing `---` line follows — gray-matter would swallow the whole
+ *     document as one unclosed YAML block and hand it to js-yaml, which
+ *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ */
+const opensWithThematicBreak = (input: string): boolean => {
+  const [first = "", second] = input.split(/\r?\n/u, 2);
+  if (!/^-{3}\s*$/u.test(first)) {
+    return false;
+  }
+  if (second === undefined || second.trim() === "") {
+    return true;
+  }
+  // gray-matter closes the block at the next line-leading `---`; matching its
+  // search exactly keeps this guard from firing on any document it parses.
+  return !input.includes("\n---", 1);
+};
+
+/**
+ * The parse result for a document with no front matter: the input passes
+ * through as content, untouched. Shaped like gray-matter's own no-matter
+ * result (every Blume call site reads only `content` and `data`).
+ */
+const passthrough = (input: string): ReturnType<typeof baseMatter> =>
+  ({
+    content: input,
+    data: {},
+    excerpt: "",
+    isEmpty: false,
+    language: "",
+    matter: "",
+    orig: input,
+    // Recomposing a file with no matter and empty data is the content itself.
+    stringify: (): string => input,
+  }) as unknown as ReturnType<typeof baseMatter>;
+
 // Every helper that parses or emits YAML (`read`, `stringify`) must be
 // re-wrapped here — Object.assign copies gray-matter's own helpers, which use
 // its default `safeLoad` engine and would reintroduce the crash. `test` only
 // checks for a delimiter, so the copied original is safe.
 const matter = Object.assign(
   (input: MatterInput, options?: MatterOptions) =>
-    baseMatter(input, withYamlEngine(options)),
+    typeof input === "string" && opensWithThematicBreak(input)
+      ? passthrough(input)
+      : baseMatter(input, withYamlEngine(options)),
   baseMatter,
   {
     read: (filepath: ReadArgs[0], options?: ReadArgs[1]) =>

package/src/core/probe.ts

@@ -1,3 +1,5 @@
+import pMap from "p-map";
+
 import type { DiagnosticSeverity } from "./types.ts";
 
 export const PROBE_CONCURRENCY = 8;
@@ -113,24 +115,10 @@ export const probeAll = async (
   options: { concurrency?: number; timeoutMs?: number } = {}
 ): Promise<Map<string, ProbeResult>> => {
   const unique = [...new Set(urls)];
-  const results = new Map<string, ProbeResult>();
-  const limit = Math.min(
-    options.concurrency ?? PROBE_CONCURRENCY,
-    unique.length
+  const entries = await pMap(
+    unique,
+    async (url) => [url, await probe(url, options)] as const,
+    { concurrency: Math.max(1, options.concurrency ?? PROBE_CONCURRENCY) }
   );
-
-  let cursor = 0;
-  const worker = async (): Promise<void> => {
-    while (cursor < unique.length) {
-      const url = unique[cursor];
-      cursor += 1;
-      if (url !== undefined) {
-        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
-        results.set(url, await probe(url, options));
-      }
-    }
-  };
-  await Promise.all(Array.from({ length: limit }, worker));
-
-  return results;
+  return new Map(entries);
 };

package/src/core/project-graph.ts

@@ -262,6 +262,17 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
+  // Folder meta contributed by the sources themselves (the OpenAPI source
+  // labels each tag directory with the spec's own tag name). It applies to
+  // every locale, so it merges into the shared map — beneath user-authored
+  // entries, which are spread last and win.
+  const sharedFolderMeta = new Map([
+    ...loaded.flatMap(({ folderMeta: sourceMeta }) =>
+      Object.entries(sourceMeta ?? {})
+    ),
+    ...folderMeta.shared,
+  ]);
+
   const {
     diagnostics: contentDiagnostics,
     droppedPages,
@@ -301,7 +312,7 @@ export const scanProject = async (
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
-    sharedFolderMeta: folderMeta.shared,
+    sharedFolderMeta,
   });
   const manifest = buildManifest({ config, context, graph });
 

package/src/core/schema.ts

@@ -304,6 +304,8 @@ const sanitySourceSchema = z.object({
 
 /** A Notion database; pages become entries, blocks become MDX. */
 const notionSourceSchema = z.object({
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency: z.number().positive().optional(),
   database: z.string(),
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
   pollInterval: z.number().positive().optional(),
@@ -780,6 +782,10 @@ const aiConfigSchema = z.strictObject({
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
       // paths are both valid; the built-in request/stream contract is unchanged.
       endpoint: askEndpointSchema.optional(),
+      // Extra system-prompt text (identity, language, tone) appended to the
+      // built-in instructions, so the grounding contract — answer from the
+      // retrieved excerpts, cite pages as Markdown links — stays intact.
+      instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
       // Empty-state prompts shown before the first question. Each renders as a

package/src/core/site-url.ts

@@ -0,0 +1,27 @@
+import { joinURL } from "ufo";
+
+import { trimEnd } from "./trim.ts";
+
+/**
+ * Absolute-URL building for the configured `deployment.site`, shared by every
+ * emitter that prints site URLs (sitemap, RSS, robots, llms.txt, the MCP and
+ * agent-discovery documents). One implementation replaces eight per-file
+ * copies that had drifted across three different trailing-slash treatments.
+ *
+ * Deliberately not `new URL(path, site)`: a root-absolute path would drop the
+ * base path of a subpath deployment (`acme.com/docs`). ufo's `joinURL` joins
+ * without that footgun; the site is first trimmed with the ReDoS-safe
+ * `trimEnd` loop so even a malformed `site` with piled-up trailing slashes
+ * joins cleanly.
+ */
+
+/** The configured site with any trailing slashes dropped. */
+export const siteRoot = (site: string): string => trimEnd(site, "/");
+
+/** `site` + root-absolute `path` (already carrying any deployment base). */
+export const absoluteUrl = (site: string, path: string): string => {
+  const root = siteRoot(site);
+  // joinURL folds a lone "/" away entirely; the homepage keeps its slash
+  // (`https://example.com/`), matching what every emitter always printed.
+  return path === "/" ? `${root}/` : joinURL(root, path);
+};

package/src/core/sources/cache.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 import { join } from "pathe";
@@ -6,14 +7,15 @@ import { BlumeError } from "../diagnostics.ts";
 import type { Diagnostic } from "../types.ts";
 import type { SourceEntry, SourceLoadResult } from "./types.ts";
 
-/** Small, stable content hash for cache/HMR bookkeeping (non-bitwise). */
-export const hashText = (text: string): string => {
-  let hash = 5381;
-  for (let i = 0; i < text.length; i += 1) {
-    hash = (hash * 33 + (text.codePointAt(i) ?? 0)) % 2_147_483_647;
-  }
-  return hash.toString(36);
-};
+/**
+ * Small, stable content hash for cache/HMR bookkeeping — and for staged asset
+ * *filenames* (see sources/assets.ts and content-assets.ts), where a collision
+ * silently serves the wrong file. 64 bits of SHA-256 keeps those names
+ * collision-safe at any realistic asset count; the old 31-bit DJB2 hash had a
+ * ~46k-item birthday bound.
+ */
+export const hashText = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
 
 /** A stable digest of a source's entries, for change detection while polling. */
 export const entriesDigest = (entries: SourceEntry[]): string =>

package/src/core/sources/github-releases.ts

@@ -85,6 +85,26 @@ const NON_PROSE = new Set(["code", "heading", "html", "thematicBreak"]);
  * content kept — then cut at a word boundary to fit the search snippet cap.
  * Undefined when the notes have no prose at all.
  */
+/**
+ * The longest prefix of `text` that fits `max` UTF-16 units without cutting
+ * inside a grapheme cluster. A bare `String#slice` counts code units, so it
+ * can split a surrogate pair (emitting a lone surrogate — invalid Unicode —
+ * into a meta description) or halve an emoji sequence. Grapheme segmentation
+ * is rule-based (UAX #29), so unlike word segmentation it does not drift
+ * across ICU builds.
+ */
+const graphemePrefix = (text: string, max: number): string => {
+  let end = 0;
+  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  for (const { index, segment } of graphemes.segment(text)) {
+    if (index + segment.length > max) {
+      break;
+    }
+    end = index + segment.length;
+  }
+  return text.slice(0, end);
+};
+
 const releaseDescription = (body: string): string | undefined => {
   const tree = fromMarkdown(body.replaceAll(CHANGESET_HASH, "$<mark>"), {
     extensions: [gfm()],
@@ -108,7 +128,7 @@ const releaseDescription = (body: string): string | undefined => {
   }
   // Cut before the cap at a word boundary (kept only when it doesn't drop the
   // summary under the minimum), shed any dangling punctuation, and mark the cut.
-  const slice = text.slice(0, DESCRIPTION_MAX - 1);
+  const slice = graphemePrefix(text, DESCRIPTION_MAX - 1);
   const boundary = slice.lastIndexOf(" ");
   const head = (
     boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice

package/src/core/sources/normalize.ts

@@ -28,12 +28,19 @@ const groupLabel = (segment: string): string | null =>
  * anchor ids are *not* slugged here — they use a `github-slugger` in
  * {@link extractHeadings}, matching the renderer (see `markdown/heading-anchors`)
  * so `blume validate` checks anchors against the exact rendered heading ids.
+ *
+ * The keep-class is Unicode letters/marks/numbers, not `\w`: ASCII slugs are
+ * unchanged, but a CJK/Cyrillic/accented slug keeps its characters instead of
+ * collapsing to `""` (which forced Sanity/Notion routes onto their opaque
+ * document-id fallbacks) or dropping accents (`café` → `caf`). NFC first so a
+ * macOS-NFD `é` (e + combining mark) slugs identically to the composed form.
  */
 export const slugify = (text: string): string =>
   text
+    .normalize("NFC")
     .toLowerCase()
     .trim()
-    .replaceAll(/[^\w\s-]/gu, "")
+    .replaceAll(/[^\p{L}\p{M}\p{N}\s_-]/gu, "")
     .replaceAll(/[\s_]+/gu, "-")
     .replaceAll(/-+/gu, "-")
     .replaceAll(/^-|-$/gu, "");
@@ -55,6 +62,18 @@ const titleCase = (value: string): string =>
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(" ");
 
+/**
+ * Strip characters that cannot survive the route → URL → output-file round
+ * trip. A `:` ahead of the first `/` makes `new URL()` read the segment as a
+ * scheme (`Guide: Architecture.md` → `guide:`), which crashes Astro's
+ * prerender write with "The URL must be of scheme file"; control characters
+ * (an embedded newline in a filename) are silently dropped by the URL parser,
+ * desyncing the route from its output path. Both are legal in macOS/Linux
+ * filenames, so they are removed here rather than rejected.
+ */
+const sanitizeSegment = (segment: string): string =>
+  segment.replaceAll(/[:\p{Cc}]/gu, "");
+
 /** Fold one raw path part into the accumulating route segments/groups. */
 const addRouteSegment = (
   part: string,
@@ -75,7 +94,12 @@ const addRouteSegment = (
   if (clean === "index") {
     return;
   }
-  segments.push(clean);
+  const safe = sanitizeSegment(clean);
+  // A part that was nothing but stripped characters cannot name a segment.
+  if (safe === "") {
+    return;
+  }
+  segments.push(safe);
 };
 
 /** Convert a content-root-relative path into URL + nav metadata. */

package/src/core/sources/notion.ts

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from "node:timers/promises";
 
+import pLimit from "p-limit";
 import { join } from "pathe";
 
 import { BlumeError } from "../diagnostics.ts";
@@ -96,6 +97,12 @@ export interface NotionSourceOptions {
   prefix?: string;
   /** The Notion database id. */
   database: string;
+  /**
+   * Maximum concurrent Notion API requests. Notion allows an average of 3
+   * requests per second per integration, so a large database must pace its
+   * block-tree fan-out or every request 429s. Default 3.
+   */
+  concurrency?: number;
   /** Integration token; defaults to `NOTION_TOKEN`. */
   token?: string;
   properties?: NotionPropertyMap;
@@ -141,12 +148,15 @@ const RATE_LIMITED = 429;
 const MAX_RETRIES = 4;
 const BASE_DELAY_MS = 500;
 const SECOND_MS = 1000;
+const DEFAULT_CONCURRENCY = 3;
 
 /**
  * Retry a Notion API call on a `429 rate_limited`, honoring the `Retry-After`
  * header and otherwise backing off exponentially. A large workspace fans out
  * many concurrent block-children requests, so without this a single 429 would
- * reject the batch and abort the whole import.
+ * reject the batch and abort the whole import. The exponential wait is
+ * jittered so calls rate-limited together don't retry in lockstep and trip
+ * the limit again as a herd.
  */
 const withNotionRetry = async <T>(
   call: () => Promise<T>,
@@ -163,7 +173,9 @@ const withNotionRetry = async <T>(
       (error as { headers?: Record<string, string> }).headers?.["retry-after"]
     );
     const wait =
-      retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      retryAfter > 0
+        ? retryAfter * SECOND_MS
+        : BASE_DELAY_MS * 2 ** attempt * (1 + Math.random());
     await sleep(wait);
     return withNotionRetry(call, attempt + 1);
   }
@@ -252,6 +264,16 @@ export const notionSource = (
   ctx?: SourceContext
 ): ContentSource => {
   const props = options.properties ?? {};
+  // A FIFO semaphore: at most N calls run at once, the rest queue. Notion's
+  // rate limit is per-integration (an average of 3 req/s), and a large
+  // database fans out one block-children request per page plus one per nested
+  // container — an unbounded burst guarantees 429s that even the retry loop
+  // can't recover from, so every API call funnels through this limiter.
+  const limit = pLimit(Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY));
+  // Every Notion API call goes through the limiter, inside the retry — so a
+  // call sleeping through a backoff doesn't hold a slot while it waits.
+  const notionCall = <T>(call: () => Promise<T>): Promise<T> =>
+    withNotionRetry(() => limit(call));
   const cache = snapshotCache(
     ctx?.cacheDir ?? join(".blume", "cache", options.name)
   );
@@ -284,7 +306,7 @@ export const notionSource = (
     blockId: string
   ): Promise<NotionBlock[]> =>
     collectAll((cursor) =>
-      withNotionRetry(() =>
+      notionCall(() =>
         client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
       )
     );
@@ -458,12 +480,12 @@ export const notionSource = (
   };
 
   // Hoisted out of `load` so the retry closure doesn't nest past the linter's
-  // 4-level limit (source factory → queryDatabase → withNotionRetry callback).
+  // 4-level limit (source factory → queryDatabase → notionCall callback).
   const queryDatabase = (
     client: NotionClientLike,
     cursor?: string
   ): Promise<NotionList<NotionPage>> =>
-    withNotionRetry(() =>
+    notionCall(() =>
       client.databases.query({
         database_id: options.database,
         start_cursor: cursor,

package/src/core/sources/portable-text.ts

@@ -45,12 +45,27 @@ const HEADING_STYLES: Record<string, string> = {
   h6: "###### ",
 };
 
+// Markdown/raw-HTML structure characters. Portable Text spans are *plain
+// text* — formatting arrives as marks, never as syntax in the text — so a
+// literal `*`, `_`, `[`, backtick, `~`, or `<` typed in the CMS must render
+// as itself. Unescaped, it opened emphasis or a code span mid-paragraph, and
+// `<` let CMS prose inject raw HTML into the rendered page. CommonMark
+// backslash-escapes every ASCII punctuation character, so `\*` is always the
+// literal asterisk.
+const MARKDOWN_SPECIALS = /[\\`*_[\]~<]/gu;
+
+const escapeText = (text: string): string =>
+  text.replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`);
+
 /** Wrap a span's text in Markdown for its marks (decorators + link defs). */
 const renderSpan = (
   span: PortableTextSpan,
   defs: Map<string, PortableTextMarkDef>
 ): string => {
-  let text = span.text ?? "";
+  // Code spans stay verbatim: their text is literal inside the backticks,
+  // and backslash escapes would render as backslashes.
+  const isCode = span.marks?.includes("code") ?? false;
+  let text = isCode ? (span.text ?? "") : escapeText(span.text ?? "");
   if (!span.marks || span.marks.length === 0) {
     return text;
   }

package/src/core/sources/resolve.ts

@@ -86,6 +86,7 @@ const buildSource = (
   if (def.type === "notion") {
     return notionSource(
       {
+        concurrency: def.concurrency,
         database: def.database,
         name,
         pollInterval: def.pollInterval,

package/src/core/sources/types.ts

@@ -1,4 +1,8 @@
-import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
+import type {
+  FolderMeta,
+  FrontmatterExtend,
+  ResolvedI18nConfig,
+} from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
 /**
@@ -40,6 +44,14 @@ export interface SourceLoadResult {
   entries: SourceEntry[];
   /** Source-level diagnostics (e.g. an offline cache fallback warning). */
   diagnostics: Diagnostic[];
+  /**
+   * Folder meta the source derives for the sidebar groups its entries create,
+   * keyed by locale-stripped group path (the `meta.ts` key space). The OpenAPI
+   * source labels each tag directory with the spec's own tag name, so the
+   * sidebar shows `OAuth2`/`Größe` instead of a re-humanized slug. Merged
+   * beneath user-authored meta files, which always win.
+   */
+  folderMeta?: Record<string, FolderMeta>;
 }
 
 /**

package/src/deploy/cloudflare-negotiation.ts

@@ -276,6 +276,20 @@ const redirectFor = (pathname) => {
   return Object.hasOwn(REDIRECTS, path) ? REDIRECTS[path] : null;
 };
 
+// \`_redirects\` semantics, which the static layer applies to these same
+// paths: the request's query string is forwarded unless the destination
+// carries its own, and a destination fragment stays after the query.
+const redirectLocation = (destination, search) => {
+  const hashIndex = destination.indexOf("#");
+  const bare = hashIndex === -1 ? destination : destination.slice(0, hashIndex);
+  if (!search || bare.includes("?")) {
+    return destination;
+  }
+  return hashIndex === -1
+    ? bare + search
+    : bare + search + destination.slice(hashIndex);
+};
+
 const parseAccept = (accept) =>
   accept.split(",").map((part) => {
     const segments = part.trim().split(";");
@@ -355,7 +369,7 @@ export default {
     const redirect = redirectFor(url.pathname);
     if (redirect !== null) {
       return new Response(null, {
-        headers: { location: redirect[0] },
+        headers: { location: redirectLocation(redirect[0], url.search) },
         status: redirect[1],
       });
     }

package/src/deploy/robots.ts

@@ -1,6 +1,7 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 
 /**
  * Ordered mapping from config field to its `Content-Signal` token. The order
@@ -52,7 +53,7 @@ export const buildRobots = (project: BlumeProject): string | null => {
       normalizeBasePath(config.deployment.base),
       "/sitemap.xml"
     );
-    lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}${sitemapPath}`);
+    lines.push("", `Sitemap: ${absoluteUrl(site, sitemapPath)}`);
   }
   return `${lines.join("\n")}\n`;
 };

package/src/deploy/rss.ts

@@ -4,6 +4,7 @@ import { escape as escapeXml } from "html-escaper";
 
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { siteRoot } from "../core/site-url.ts";
 import type { PageRecord } from "../core/types.ts";
 
 /** A single feed entry derived from a content page. */
@@ -55,7 +56,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   if (!(rss.enabled && site)) {
     return [];
   }
-  const base = site.replace(/\/$/u, "");
+  const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   // The feed's own `link`/self URL points at the docs root under that base, while
   // `path` stays base-less (it's also the on-disk output location).

package/src/deploy/sitemap.ts

@@ -8,6 +8,7 @@ import {
 } from "../astro/pages.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { siteRoot } from "../core/site-url.ts";
 
 /**
  * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
@@ -29,20 +30,48 @@ const lastmodTag = (value: string | undefined): string => {
     : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
 };
 
+/** One emitted sitemap artifact: its dist-root filename and XML body. */
+export interface SitemapFile {
+  name: string;
+  xml: string;
+}
+
 /**
- * Build a sitemap.xml from the route manifest plus the routes the manifest
+ * The sitemaps.org cap on `<url>` entries in a single file. Beyond it,
+ * `sitemap.xml` becomes a sitemap index pointing at numbered chunk files —
+ * search engines reject an oversized urlset outright.
+ */
+const URLS_PER_FILE = 50_000;
+
+const renderUrlset = (
+  urls: string[]
+): string => `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.join("\n")}
+</urlset>
+`;
+
+/**
+ * Build the sitemap files from the route manifest plus the routes the manifest
  * 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.
+ *
+ * Sites within the per-file URL cap get the single classic `sitemap.xml`;
+ * larger sites get `sitemap.xml` as a sitemap index over numbered
+ * `sitemap-N.xml` chunks, all served from the same directory robots.txt
+ * already points at.
  */
-export const buildSitemap = (project: BlumeProject): string | null => {
+export const buildSitemapFiles = (
+  project: BlumeProject
+): SitemapFile[] | null => {
   const { site } = project.config.deployment;
   if (!(site && project.config.seo.sitemap)) {
     return null;
   }
 
-  const base = site.replace(/\/$/u, "");
+  const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   const deployBase = normalizeBasePath(project.config.deployment.base);
   const seen = new Set<string>();
@@ -87,9 +116,29 @@ export const buildSitemap = (project: BlumeProject): string | null => {
   }
   urls.sort();
 
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${urls.join("\n")}
-</urlset>
+  if (urls.length <= URLS_PER_FILE) {
+    return [{ name: "sitemap.xml", xml: renderUrlset(urls) }];
+  }
+
+  const chunks: SitemapFile[] = [];
+  const references: string[] = [];
+  for (let start = 0; start < urls.length; start += URLS_PER_FILE) {
+    const name = `sitemap-${chunks.length + 1}.xml`;
+    chunks.push({
+      name,
+      xml: renderUrlset(urls.slice(start, start + URLS_PER_FILE)),
+    });
+    // Chunks sit next to sitemap.xml, so their URLs layer the same deployment
+    // base robots.txt uses for the index.
+    const loc = escapeXml(
+      encodeURI(`${base}${withBasePath(deployBase, `/${name}`)}`)
+    );
+    references.push(`  <sitemap><loc>${loc}</loc></sitemap>`);
+  }
+  const index = `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${references.join("\n")}
+</sitemapindex>
 `;
+  return [{ name: "sitemap.xml", xml: index }, ...chunks];
 };