blume 0.3.0 → 0.4.0

package/src/components/content/youtube.ts

@@ -0,0 +1,46 @@
+/**
+ * Helpers for the `<YouTube>` content component. Kept in a sibling `.ts` (like
+ * `diff.ts`/`github-info.ts`) so the id parsing and embed-URL building are pure,
+ * unit-testable functions — the `.astro` file stays a thin presentational shell.
+ */
+
+// A YouTube video id is 11 characters of [A-Za-z0-9_-].
+const BARE_ID = /^[\w-]{11}$/u;
+
+// Pull the id out of any common YouTube URL: youtu.be/<id>, watch?v=<id>,
+// /embed/<id>, /shorts/<id>, /live/<id>.
+const URL_ID =
+  /(?:youtu\.be\/|\/embed\/|\/shorts\/|\/live\/|[?&]v=)(?<id>[\w-]{11})/u;
+
+/**
+ * Resolve a YouTube video id from either a bare id or a full URL. Returns `null`
+ * when nothing that looks like an id can be found, so the component can render
+ * nothing rather than a broken embed.
+ */
+export const parseYouTubeId = (input: string): string | null => {
+  const value = input.trim();
+  if (!value) {
+    return null;
+  }
+  if (BARE_ID.test(value)) {
+    return value;
+  }
+  return URL_ID.exec(value)?.groups?.id ?? null;
+};
+
+/**
+ * Build a privacy-enhanced (`youtube-nocookie.com`) embed URL, optionally
+ * starting at `start` seconds.
+ */
+export const youtubeEmbedUrl = (
+  id: string,
+  options: { start?: number } = {}
+): string => {
+  const base = `https://www.youtube-nocookie.com/embed/${id}`;
+  const { start } = options;
+  if (start && start > 0) {
+    const params = new URLSearchParams({ start: String(Math.floor(start)) });
+    return `${base}?${params.toString()}`;
+  }
+  return base;
+};

package/src/components/islands/ask-ai.tsx

@@ -93,21 +93,21 @@ const AskAI = ({ strings }: { strings?: UIStrings["ask"] }) => {
         headers: { "content-type": "application/json" },
         method: "POST",
       });
-      const reader = response.body?.getReader();
+      // A 4xx/5xx still has a body; without this guard its error text would be
+      // decoded and shown as the assistant's answer instead of the error notice.
+      if (!(response.ok && response.body)) {
+        throw new Error(`Ask AI request failed (${response.status}).`);
+      }
+      const reader = response.body.getReader();
       const decoder = new TextDecoder();
-      if (reader) {
-        let done = false;
-        while (!done) {
-          // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
-          const chunk = await reader.read();
-          ({ done } = chunk);
-          if (chunk.value) {
-            assistant.content += decoder.decode(chunk.value);
-            setMessages((current) => [
-              ...current.slice(0, -1),
-              { ...assistant },
-            ]);
-          }
+      let done = false;
+      while (!done) {
+        // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+        const chunk = await reader.read();
+        ({ done } = chunk);
+        if (chunk.value) {
+          assistant.content += decoder.decode(chunk.value);
+          setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
         }
       }
     } catch {

package/src/components/props.ts

@@ -65,4 +65,7 @@ export type TileProps = ComponentProps<
 export type TooltipProps = ComponentProps<
   typeof import("./content/Tooltip.astro").default
 >;
+export type YouTubeProps = ComponentProps<
+  typeof import("./content/YouTube.astro").default
+>;
 export type IconProps = ComponentProps<typeof import("./Icon.astro").default>;

package/src/core/assets.ts

@@ -0,0 +1,31 @@
+import { join } from "pathe";
+
+/** A static directory served at a URL prefix, in addition to `public/`. */
+export interface AssetMount {
+  /** Absolute filesystem path to the source directory (or file). */
+  dir: string;
+  /** URL path prefix the source is served at, e.g. `/images`. */
+  url: string;
+}
+
+/**
+ * Resolve `content.assets` entries (top-level dirs served at the site root,
+ * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
+ * runtime (dev middleware + build copy) and by link validation, so all three
+ * agree on where a `/images/foo.png` reference resolves on disk.
+ *
+ * Each entry is normalized to a leading-slash URL and joined to the project
+ * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
+ * escape the root or collide with the site's own routing prefix.
+ */
+export const resolveAssetMounts = (
+  root: string,
+  assets: string[]
+): AssetMount[] =>
+  assets.map((entry) => {
+    const rel = entry
+      .replace(/^[./]+/u, "")
+      .replaceAll(/\.\.\/?/gu, "")
+      .replace(/\/+$/u, "");
+    return { dir: join(root, rel), url: `/${rel}` };
+  });

package/src/core/bridge.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 
 import { join } from "pathe";
 
+import { assetSegments } from "../migrate/mintlify/assets.ts";
 import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
 import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
 import type { BlumeConfig } from "./schema.ts";
@@ -64,11 +65,20 @@ export const detectMintlifyBridge = async (
   const root_ = config.content?.root ?? ".";
   const exclude = config.content?.exclude ?? [];
 
+  // Mintlify serves assets from the project root; the bridge never moves files,
+  // so referenced root-level asset folders (e.g. `images/`) are served in place
+  // via `content.assets` instead. This is the read-only twin of the migrator's
+  // relocation — same referenced segments, just no `public/` move.
+  const assets = assetSegments(config).filter(
+    (segment) => segment !== "public" && existsSync(join(root, segment))
+  );
+
   return {
     configFile,
     raw: {
       ...config,
       content: {
+        assets,
         // Mirror the excludes onto `content.exclude` too: the generated Astro
         // `docs` collection globs `content.root` (here the project root) and
         // must skip node_modules/snippets just like the source does.

package/src/core/builtin-tags.ts

@@ -36,4 +36,5 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Tree",
   "TypeTable",
   "Visibility",
+  "YouTube",
 ]);

package/src/core/diagnostics.ts

@@ -84,7 +84,12 @@ const locatePath = (
     if (typeof segment !== "string") {
       continue;
     }
-    const matcher = new RegExp(`${escapeRegExp(segment)}\\s*[:=]`, "gu");
+    // The negative lookbehind keeps a segment like `title` from matching the
+    // tail of an unrelated key such as `subtitle:`.
+    const matcher = new RegExp(
+      `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
+      "gu"
+    );
     matcher.lastIndex = cursor;
     const match = matcher.exec(source);
     if (!match) {

package/src/core/gitignore.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+/** A `.gitignore` line, normalized for comparison (trailing slashes dropped). */
+const gitignoreKey = (line: string): string => line.trim().replace(/\/+$/u, "");
+
+/**
+ * Ensure `.gitignore` ignores each of `entries`, appending any that are missing
+ * (creating the file when absent). Trailing-slash differences (`dist` vs
+ * `dist/`) count as already present. Returns the entries actually added.
+ */
+export const ensureGitignore = async (
+  root: string,
+  entries: string[]
+): Promise<string[]> => {
+  const path = join(root, ".gitignore");
+  const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
+  const present = new Set(
+    existing.split("\n").map(gitignoreKey).filter(Boolean)
+  );
+  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
+  if (added.length === 0) {
+    return [];
+  }
+  const gap = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await writeFile(path, `${existing}${gap}${added.join("\n")}\n`, "utf-8");
+  return added;
+};

package/src/core/links.ts

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 
-import { join } from "pathe";
+import { basename, join } from "pathe";
 
+import type { AssetMount } from "./assets.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -37,20 +38,52 @@ interface ExternalRef extends LinkSite {
 /** Lookups derived once from the content graph. */
 interface LinkContext {
   anchors: Map<string, Set<string>>;
+  /** `content.assets` mounts served alongside `public/` (checked in place). */
+  assetMounts: AssetMount[];
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
   routes: Set<string>;
 }
 
+/** Whether a resolved asset path exists under `public/` or an asset mount. */
+const assetIsPresent = (resolved: string, ctx: LinkContext): boolean => {
+  if (ctx.publicDir && existsSync(join(ctx.publicDir, resolved))) {
+    return true;
+  }
+  return ctx.assetMounts.some(
+    (mount) =>
+      (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) &&
+      existsSync(join(mount.dir, resolved.slice(mount.url.length)))
+  );
+};
+
 /** Outcome of classifying one link target. */
 type LinkResult = Diagnostic | "asset-unchecked" | null;
 
+/**
+ * Whether a page is a directory index (`…/index.md(x)`). Its route already *is*
+ * its directory, so a relative link must resolve against the route itself, not
+ * its parent — otherwise `./sibling` from `guides/index.mdx` (route `/guides`)
+ * would resolve to `/sibling` and be falsely flagged as broken.
+ */
+const isIndexPage = (page: PageRecord): boolean => {
+  const ref = page.source?.ref ?? page.sourcePath ?? "";
+  return /^index\.(?:md|mdx)$/iu.test(basename(ref));
+};
+
 /** Resolve a relative link target against the directory of a page route. */
-const resolveRelative = (pageRoute: string, target: string): string => {
+const resolveRelative = (
+  pageRoute: string,
+  target: string,
+  isIndex: boolean
+): string => {
   const segments = pageRoute.split("/").filter(Boolean);
-  // Drop the page's own segment so links resolve against its parent directory.
-  segments.pop();
+  // Drop a leaf page's own segment so links resolve against its parent
+  // directory. An index page's route already is its directory, so keep it.
+  if (!isIndex) {
+    segments.pop();
+  }
   for (const part of target.split("/")) {
     if (part === "" || part === ".") {
       continue;
@@ -114,13 +147,28 @@ const checkPathLink = (
   site: LinkSite,
   ctx: LinkContext
 ): LinkResult => {
+  // A real route always wins over the asset-extension heuristic, so a path
+  // whose last segment merely contains a dot (e.g. a page at `/releases/v1.0`)
+  // isn't misread as a missing asset.
+  const route = toRoute(resolved);
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // Its destination (and any anchor there) is validated on its own page, so we
+  // don't follow the redirect to check the fragment here.
+  if (ctx.redirects.has(route)) {
+    return null;
+  }
+
   if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (ctx.publicDir === null) {
-      return "asset-unchecked";
-    }
-    if (existsSync(join(ctx.publicDir, resolved))) {
+    if (assetIsPresent(resolved, ctx)) {
       return null;
     }
+    // Nowhere to look: no `public/` and no asset mounts configured.
+    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+      return "asset-unchecked";
+    }
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
@@ -130,16 +178,6 @@ const checkPathLink = (
     };
   }
 
-  const route = toRoute(resolved);
-  if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
-  }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
-  // Its destination (and any anchor there) is validated on its own page, so we
-  // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
-    return null;
-  }
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
@@ -295,7 +333,7 @@ const classifyLink = (
 
   const resolved = rawPath.startsWith("/")
     ? rawPath
-    : resolveRelative(page.route, rawPath);
+    : resolveRelative(page.route, rawPath, isIndexPage(page));
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 
@@ -309,12 +347,15 @@ export const validateLinks = async (
   options: {
     publicDir: string | null;
     checkExternal?: boolean;
+    /** `content.assets` mounts served alongside `public/`. */
+    assetMounts?: AssetMount[];
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
 ): Promise<Diagnostic[]> => {
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
+    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) => toRoute(redirect.from))

package/src/core/schema.ts

@@ -365,6 +365,13 @@ export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
 
 const contentConfigSchema = z
   .object({
+    /**
+     * Extra top-level directories (relative to the project root) served as
+     * static assets at the site root, alongside `public/`. Lets projects keep
+     * root-served asset folders in place — e.g. a Mintlify migration keeps
+     * `images/` where it is instead of relocating it under `public/`.
+     */
+    assets: z.array(z.string()).default([]),
     defaultType: z.string().default("doc"),
     exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
     include: z.array(z.string()).default(["**/*.{md,mdx}"]),

package/src/core/sources/mdx-remote.ts

@@ -1,5 +1,6 @@
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
+import type { Diagnostic } from "../types.ts";
 import {
   hashText,
   loadWithCache,
@@ -105,7 +106,7 @@ const enumerateGithub = async (
   github: { owner: string; repo: string; ref: string; path: string },
   include: string[],
   doFetch: typeof fetch
-): Promise<RemoteRef[]> => {
+): Promise<{ refs: RemoteRef[]; truncated: boolean }> => {
   const { owner, repo, ref } = github;
   const base = github.path.replaceAll(/^\/|\/$/gu, "");
   const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
@@ -113,9 +114,12 @@ const enumerateGithub = async (
   if (!res.ok) {
     throw new Error(`${treeUrl} -> ${res.status}`);
   }
-  const body = (await res.json()) as { tree?: GithubTreeEntry[] };
+  const body = (await res.json()) as {
+    tree?: GithubTreeEntry[];
+    truncated?: boolean;
+  };
   const prefix = base ? `${base}/` : "";
-  return (body.tree ?? [])
+  const refs = (body.tree ?? [])
     .filter((node) => node.type === "blob" && node.path.startsWith(prefix))
     .map((node) => node.path.slice(prefix.length))
     .filter((rel) => matchesInclude(rel, include))
@@ -124,6 +128,9 @@ const enumerateGithub = async (
       fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
       ref: rel,
     }));
+  // GitHub caps the recursive tree response (~100k entries / 7MB) and flags it
+  // with `truncated`; ignoring it would silently import only part of the repo.
+  return { refs, truncated: body.truncated === true };
 };
 
 /**
@@ -139,19 +146,23 @@ export const mdxRemoteSource = (
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map<string, SourceEntry>();
 
-  const enumerate = async (): Promise<RemoteRef[]> => {
+  const enumerate = async (): Promise<{
+    refs: RemoteRef[];
+    truncated: boolean;
+  }> => {
     if (options.github) {
       return await enumerateGithub(options.github, options.include, doFetch);
     }
     if (options.files && options.url) {
       const base = options.url.replace(/\/$/u, "");
-      return options.files
+      const refs = options.files
         .filter((ref) => matchesInclude(ref, options.include))
         .map((ref) => ({
           editUrl: `${base}/${ref}`,
           fetchUrl: `${base}/${ref}`,
           ref,
         }));
+      return { refs, truncated: false };
     }
     throw new BlumeError({
       code: "BLUME_SOURCE_MISCONFIGURED",
@@ -179,17 +190,52 @@ export const mdxRemoteSource = (
   };
 
   const load = async (): Promise<SourceLoadResult> => {
+    const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
       cache,
       async () => {
-        const refs = await enumerate();
-        return await Promise.all(refs.map(fetchEntry));
+        const { refs, truncated } = await enumerate();
+        if (truncated) {
+          skipped.push({
+            code: "BLUME_SOURCE_TRUNCATED",
+            message: `Source "${options.name}" hit GitHub's tree listing limit; some files were not enumerated. Narrow the source path or split the repo.`,
+            severity: "warning",
+          });
+        }
+        const settled = await Promise.all(
+          refs.map(async (ref) => {
+            try {
+              return await fetchEntry(ref);
+            } catch (error) {
+              skipped.push({
+                code: "BLUME_SOURCE_FETCH_FAILED",
+                message: `Source "${options.name}" skipped "${ref.ref}" (${(error as Error).message}); the rest were imported.`,
+                severity: "warning",
+              });
+              return null;
+            }
+          })
+        );
+        const entries = settled.filter(
+          (entry): entry is SourceEntry => entry !== null
+        );
+        // Only a total wipeout is a hard failure — let loadWithCache fall back
+        // to cache or fail loudly rather than silently importing nothing. A
+        // partial failure keeps the healthy pages and warns about the rest.
+        if (refs.length > 0 && entries.length === 0) {
+          skipped.length = 0;
+          throw new Error(`all ${refs.length} remote file(s) failed to fetch`);
+        }
+        return entries;
       },
       ctx.refresh ?? true
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return {
+      ...result,
+      diagnostics: [...result.diagnostics, ...skipped],
+    };
   };
 
   const read = async (ref: string): Promise<string> => {

package/src/core/sources/normalize.ts

@@ -137,8 +137,13 @@ export const extractLinks = (body: string): PageLink[] => {
       if (target === undefined || match.index === undefined) {
         continue;
       }
+      // Locate the target from the `](` boundary rather than searching for the
+      // target text from the match start — otherwise a label that contains the
+      // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
+      // label can't contain `]`, so `](` is unambiguous.
+      const targetOffset = match.index + match[0].indexOf("](") + "](".length;
       links.push({
-        column: line.indexOf(target, match.index) + 1,
+        column: targetOffset + 1,
         line: lineNumber,
         target,
       });

package/src/core/sources/notion.ts

@@ -1,3 +1,5 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
 import { join } from "pathe";
 
 import { BlumeError } from "../diagnostics.ts";
@@ -136,6 +138,44 @@ const blockField = (block: NotionBlock): NotionRichText[] =>
   ((block[block.type] as { rich_text?: NotionRichText[] })?.rich_text ??
     []) as NotionRichText[];
 
+const RATE_LIMITED = 429;
+const MAX_RETRIES = 4;
+const BASE_DELAY_MS = 500;
+const SECOND_MS = 1000;
+
+/**
+ * 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.
+ */
+const withNotionRetry = async <T>(call: () => Promise<T>): Promise<T> => {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
+      return await call();
+    } catch (error) {
+      lastError = error;
+      const { status } = error as { status?: number };
+      if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
+        throw error;
+      }
+      const retryAfter = Number(
+        (error as { headers?: Record<string, string> }).headers?.["retry-after"]
+      );
+      const wait =
+        retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      // oxlint-disable-next-line no-await-in-loop -- back off before retrying
+      await sleep(wait);
+    }
+  }
+  // Unreachable — the loop always returns or rethrows — but keeps types honest.
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("Notion request failed after retries.");
+};
+
 /** Paginate a Notion list endpoint via recursion (no await-in-loop). */
 const collectAll = async <T>(
   page: (cursor?: string) => Promise<NotionList<T>>,
@@ -251,7 +291,9 @@ export const notionSource = (
     blockId: string
   ): Promise<NotionBlock[]> =>
     collectAll((cursor) =>
-      client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
+      withNotionRetry(() =>
+        client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
+      )
     );
 
   // `render` is injected (rather than referenced) so this stays a forward-free
@@ -396,10 +438,12 @@ export const notionSource = (
       async () => {
         const client = await resolveClient();
         const pages = await collectAll((cursor) =>
-          client.databases.query({
-            database_id: options.database,
-            start_cursor: cursor,
-          })
+          withNotionRetry(() =>
+            client.databases.query({
+              database_id: options.database,
+              start_cursor: cursor,
+            })
+          )
         );
         const built = await Promise.all(
           pages.map((page) => toEntry(client, page))

package/src/core/sources/sanity.ts

@@ -140,7 +140,11 @@ export const sanitySource = (
       asString(getPath(doc, fields.slug ?? "slug.current")) ??
       asString(doc._id) ??
       "untitled";
-    const slug = slugify(slugValue) || "untitled";
+    // Fall back to the unique `_id` when a slug (e.g. a non-ASCII `slug.current`)
+    // slugifies to empty, so distinct documents don't all collapse to the same
+    // `untitled.md` ref and silently overwrite each other.
+    const slug =
+      slugify(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
     const data: Record<string, unknown> = {};
     const title = asString(getPath(doc, fields.title ?? "title"));

package/src/deploy/rss.ts

@@ -1,5 +1,6 @@
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { PageRecord } from "../core/types.ts";
+import { escapeXml } from "./xml.ts";
 
 /** A single feed entry derived from a content page. */
 export interface RssItem {
@@ -85,14 +86,6 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   return feeds;
 };
 
-const escapeXml = (value: string): string =>
-  value
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-
 const renderItem = (item: RssItem): string => {
   const parts = [
     `    <title>${escapeXml(item.title)}</title>`,

package/src/deploy/sitemap.ts

@@ -1,4 +1,16 @@
 import type { BlumeProject } from "../core/project-graph.ts";
+import { escapeXml } from "./xml.ts";
+
+/** A `<lastmod>` element (W3C date) when the page has a valid modified date. */
+const lastmodTag = (value: string | undefined): string => {
+  if (!value) {
+    return "";
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime())
+    ? ""
+    : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
+};
 
 /**
  * Build a sitemap.xml from the route manifest. Returns null when the sitemap is
@@ -17,7 +29,14 @@ export const buildSitemap = (project: BlumeProject): string | null => {
       (page) =>
         !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)
     )
-    .map((page) => `  <url><loc>${base}${page.route}</loc></url>`)
+    // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
+    // then escape XML metacharacters (notably `&`) so a route like
+    // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
+    // rejected.
+    .map(
+      (page) =>
+        `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`
+    )
     .toSorted();
 
   return `<?xml version="1.0" encoding="UTF-8"?>

package/src/deploy/xml.ts

@@ -0,0 +1,8 @@
+/** Escape a string for safe inclusion in XML text or attribute content. */
+export const escapeXml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");