blume 0.3.0 → 0.5.0

package/src/core/schema.ts

@@ -69,9 +69,30 @@ const changelogMetaSchema = z
   })
   .strict();
 
+/**
+ * A post author: a bare name/handle, or an object with a name plus optional
+ * avatar/URL. The object is passthrough so richer author metadata (social
+ * handles, roles) survives untouched — Blume doesn't render authors yet, so
+ * this exists to preserve the field (common on blog/changelog pages) rather
+ * than have a strict scan reject it.
+ */
+const authorSchema = z.union([
+  z.string(),
+  z
+    .object({
+      avatar: z.string().optional(),
+      image: z.string().optional(),
+      name: z.string(),
+      url: z.string().optional(),
+    })
+    .passthrough(),
+]);
+
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z
   .object({
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
     changelog: changelogMetaSchema.optional(),
     /** Publish date for feed-backed content like blog/changelog. */
     date: dateSchema.optional(),
@@ -365,6 +386,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}"]),
@@ -896,8 +924,8 @@ const markdownConfigSchema = z
   .strict();
 
 /**
- * A single spec rendered by the API reference (Scalar). `spec` is a local path
- * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
+ * A single spec rendered by the API reference. `spec` is a local path or an
+ * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 const openapiSourceSchema = z
   .object({
@@ -913,20 +941,28 @@ const openapiSourceSchema = z
 export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
 
 /**
- * OpenAPI reference, delegated wholesale to Scalar (`@scalar/astro`). The
- * reference is a self-contained embed on its own route — it does not weave into
- * Blume's sidebar, search, or llms. Set `enabled: true` to opt in.
+ * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
+ * Scalar's parser and renders its own UI: one real page per operation, grouped
+ * by tag in the sidebar and included in site search, llms.txt, and OG. Set
+ * `renderer: "scalar"` to fall back to the embedded Scalar SPA (a single
+ * self-contained route that doesn't weave into the sidebar or search).
  */
 const openapiConfigSchema = z
   .object({
+    /** Code-sample languages shown per operation (Blume renderer). */
+    codeSamples: z.array(z.string()).default(["curl", "js", "python"]),
     enabled: z.boolean().default(false),
+    /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+    expandSchemas: z.boolean().default(false),
+    /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+    renderer: z.enum(["blume", "scalar"]).default("blume"),
     /** Where the reference mounts. */
     route: z.string().default("/reference"),
     /** One or more specs; each renders on its own route by default. */
     sources: z.array(openapiSourceSchema).default([]),
     /** Shorthand for a single source: `sources: [{ spec }]`. */
     spec: z.string().optional(),
-    /** Scalar theme name; defaults to a Blume-derived accent override. */
+    /** Scalar theme name (Scalar renderer only). */
     theme: z.string().optional(),
   })
   .strict();
@@ -973,6 +1009,17 @@ const tocConfigSchema = z
     };
   });
 
+/**
+ * Which icon library bare `icon` names resolve against (mirrors Mintlify's
+ * `icons.library`). Names can always opt into a specific set with an explicit
+ * `prefix:name` (`lucide:rocket`, `fa6-brands:github`) regardless of this.
+ */
+const iconsConfigSchema = z
+  .object({
+    library: z.enum(["lucide", "fontawesome", "tabler"]).default("lucide"),
+  })
+  .strict();
+
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1001,6 +1048,7 @@ export const blumeConfigSchema = z
     feedback: z.boolean().default(true),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
+    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),

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/mintlify.ts

@@ -102,7 +102,7 @@ export const mintlifySource = (
         ? [
             {
               code: "BLUME_MINTLIFY_UNSUPPORTED",
-              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Use the OpenAPI reference for API parameters.`,
+              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
               severity: "warning",
             },
           ]

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/resolve.ts

@@ -1,5 +1,7 @@
 import { join } from "pathe";
 
+import { blumeReferences } from "../../openapi/references.ts";
+import { openApiSource } from "../../openapi/source.ts";
 import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
@@ -144,12 +146,8 @@ const baseName = (def: ContentSourceConfig): string => {
   return def.prefix ?? def.type;
 };
 
-/**
- * Build the ordered list of content sources for a project. With no
- * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
- * to a single implicit filesystem source, so existing projects are untouched.
- */
-export const resolveSources = (
+/** The content sources declared by config (implicit filesystem when none). */
+const contentSources = (
   config: ResolvedConfig,
   context: ProjectContext,
   runtime: SourceRuntime
@@ -172,3 +170,27 @@ export const resolveSources = (
     buildSource(def, nameFor(baseName(def)), context, runtime)
   );
 };
+
+/**
+ * Build the ordered list of content sources for a project. With no
+ * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
+ * to a single implicit filesystem source, so existing projects are untouched.
+ * A Blume-rendered OpenAPI reference contributes an internal staged source that
+ * lowers each operation into a real content page (routing/nav/search/OG).
+ */
+export const resolveSources = (
+  config: ResolvedConfig,
+  context: ProjectContext,
+  runtime: SourceRuntime
+): ContentSource[] => {
+  const sources = contentSources(config, context, runtime);
+
+  const references = blumeReferences(config);
+  if (references.length > 0) {
+    sources.push(
+      openApiSource(references, sourceContext(context, "openapi", runtime))
+    );
+  }
+
+  return sources;
+};

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/core/types.ts

@@ -54,6 +54,13 @@ export interface ProjectContext {
   pagesRoot: string | null;
   /** Absolute path to the generated runtime (`<root>/.blume`). */
   outDir: string;
+  /**
+   * Absolute path to the Astro build output. `<root>/dist` normally; for a
+   * relocated runtime (isolated verify build) it lives under the runtime dir so
+   * it never empties the real `dist/`. Optional so hand-built test contexts and
+   * older callers still typecheck; `resolveProjectContext` always sets it.
+   */
+  distDir?: string;
   /** Absolute path to the user `theme.css`, if present. */
   themeFile: string | null;
   /** Absolute path to the user `components.ts`/`.tsx`, if present. */

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;");

package/src/markdown/directives.ts

@@ -3,7 +3,8 @@ import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
 interface DirectiveNode extends MdastNode {
   attributes?: Record<string, string | null | undefined> | null;
-  children: MdastNode[];
+  // Satteri gives an empty container directive (`:::note\n:::`) `children: null`.
+  children?: MdastNode[] | null;
   name: string;
 }
 
@@ -38,11 +39,18 @@ interface TextNode extends MdastNode {
   value?: string;
 }
 
-/** Concatenate the plain text of a node's immediate phrasing children. */
-const textOf = (node: MdastNode): string =>
-  ((node.children as TextNode[] | undefined) ?? [])
-    .map((child) => child.value ?? "")
-    .join("");
+/**
+ * Concatenate the plain text of a node, recursing through phrasing children so
+ * formatted labels keep every word — `:::note[Read **this**]` yields
+ * `Read this`, not `Read ` (the bolded run dropped).
+ */
+const textOf = (node: MdastNode): string => {
+  const { children } = node as { children?: MdastNode[] };
+  if (children && children.length > 0) {
+    return children.map(textOf).join("");
+  }
+  return (node as TextNode).value ?? "";
+};
 
 /**
  * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
@@ -57,7 +65,7 @@ export const directiveToCalloutPlugin = () => ({
       return;
     }
 
-    const children = [...node.children];
+    const children = [...(node.children ?? [])];
     let title = node.attributes?.title ?? undefined;
 
     // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.

package/src/markdown/package-commands.ts

@@ -10,7 +10,14 @@ const WHITESPACE = /\s+/u;
 const WHITESPACE_RUN = /\s+/gu;
 const GLOBAL_FLAGS = new Set(["-g", "--global"]);
 
-type Operation = "add" | "create" | "exec" | "install" | "remove" | "run";
+type Operation =
+  | "add"
+  | "ci"
+  | "create"
+  | "exec"
+  | "install"
+  | "remove"
+  | "run";
 
 interface Intent {
   args: string[];
@@ -26,6 +33,9 @@ const normalizeVerb = (verb: string): Operation | null => {
     case "install": {
       return "add";
     }
+    case "ci": {
+      return "ci";
+    }
     case "create":
     case "init": {
       return "create";
@@ -125,10 +135,22 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
       }
       return `${manager} dlx ${args}`;
     }
-    case "remove": {
+    case "ci": {
+      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere.
       return manager === "npm"
-        ? `npm uninstall ${args}`
-        : `${manager} remove ${args}`;
+        ? "npm ci"
+        : `${manager} install --frozen-lockfile`;
+    }
+    case "remove": {
+      if (manager === "npm") {
+        return `npm uninstall ${args}`;
+      }
+      // Yarn Classic has no `remove -g`; the global form is `yarn global remove`.
+      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
+        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
+        return `yarn global remove ${pkgs}`;
+      }
+      return `${manager} remove ${args}`;
     }
     case "run": {
       return `${manager} run ${args}`;

package/src/migrate/fumadocs/content.ts

@@ -4,7 +4,12 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { dirname, resolve } from "pathe";
 
 import matter from "../../core/frontmatter.ts";
-import { findOpenTagEnd, renameTag, rewriteCallouts } from "../shared.ts";
+import {
+  findOpenTagEnd,
+  isInsideRoot,
+  renameTag,
+  rewriteCallouts,
+} from "../shared.ts";
 
 /**
  * Source-to-source rewrites that turn Fumadocs-only MDX into idiomatic Blume
@@ -291,6 +296,8 @@ const INCLUDE = /<include\b[^>]*>(?<path>[\s\S]*?)<\/include>/gu;
 interface IncludeOptions {
   filePath: string;
   readFile?: (file: string) => Promise<string>;
+  /** Docs root the include must stay within; targets escaping it are skipped. */
+  root: string;
   seen?: Set<string>;
 }
 
@@ -321,6 +328,12 @@ export const inlineFumadocsIncludes = async (
       continue;
     }
     const target = resolve(dirname(options.filePath), rawPath);
+    if (!isInsideRoot(options.root, target)) {
+      warnings.push(
+        `<include> target "${rawPath}" is outside the docs tree — left as-is.`
+      );
+      continue;
+    }
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;

package/src/migrate/fumadocs/groups.ts

@@ -3,6 +3,7 @@ import { mkdir, rename, writeFile } from "node:fs/promises";
 
 import { basename, join } from "pathe";
 
+import { isInsideRoot } from "../shared.ts";
 import { renderMetaModule } from "./meta.ts";
 import type {
   FumadocsPageItem,
@@ -47,6 +48,12 @@ const isDirectory = (path: string): boolean => {
 
 /** Resolve a `pages` name to its on-disk page file or folder under `docsDir`. */
 const resolveEntry = (docsDir: string, name: string): ResolvedEntry | null => {
+  // A `pages` entry is author-controlled; reject any that escapes `docsDir`
+  // (e.g. `"../../victim"`) so the later `rename` can't move a file out of the
+  // docs tree.
+  if (!isInsideRoot(docsDir, join(docsDir, name))) {
+    return null;
+  }
   for (const ext of PAGE_EXTS) {
     const file = join(docsDir, `${name}${ext}`);
     if (existsSync(file)) {

package/src/migrate/fumadocs/index.ts

@@ -5,9 +5,9 @@ import { dirname, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import matter from "../../core/frontmatter.ts";
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { FolderMeta } from "../../core/schema.ts";
 import {
-  ensureGitignore,
   leftoverFiles,
   rewriteFrameworkScripts,
   writeBlumeConfig,
@@ -85,7 +85,10 @@ const movePage = async (
   }
 
   const raw = await readFile(abs, "utf-8");
-  const included = await inlineFumadocsIncludes(raw, { filePath: abs });
+  const included = await inlineFumadocsIncludes(raw, {
+    filePath: abs,
+    root: base,
+  });
   let text = stripFumadocsImports(included.content);
   text = rewriteFumadocsCallouts(text);
   text = rewriteFumadocsContainers(text);