blume 0.5.1 → 0.5.3

package/src/core/sources/filesystem.ts

@@ -7,6 +7,11 @@ import { glob } from "tinyglobby";
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
+import {
+  BLUME_WATCH_IGNORE_DIRS,
+  excludeDirSegments,
+  ignoringWatchListener,
+} from "./watch.ts";
 
 /** Options for the built-in filesystem source. */
 export interface FilesystemSourceOptions {
@@ -75,13 +80,26 @@ export const filesystemSource = (
     }
   };
 
+  // When `content.root` is the project root (a migrated `.`-rooted project),
+  // the recursive dev watcher would otherwise see Blume's own `.blume/` output
+  // and loop; skip it, VCS/dependency trees, and every excluded dir so the
+  // watcher stays in sync with what `load()` globs. See {@link ignoringWatchListener}.
+  const watchIgnoreDirs = new Set([
+    ...BLUME_WATCH_IGNORE_DIRS,
+    ...excludeDirSegments(options.exclude),
+  ]);
+
   const watch = (onChange: () => void): (() => void) => {
     if (!existsSync(contentRoot)) {
       return () => {
         // Nothing to dispose when the root doesn't exist yet.
       };
     }
-    const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
+    const watcher = fsWatch(
+      contentRoot,
+      { recursive: true },
+      ignoringWatchListener(onChange, watchIgnoreDirs)
+    );
     return () => watcher.close();
   };
 

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

@@ -91,9 +91,23 @@ interface RemoteRef {
   editUrl?: string;
 }
 
-const githubHeaders = (): Record<string, string> => {
+// Hosts the GITHUB_TOKEN may be sent to. A configured `url` base can point at
+// any server, and leaking the token there would hand a repo credential to an
+// arbitrary third party.
+const GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
+
+const githubHeaders = (url: string): Record<string, string> => {
   const token = process.env.GITHUB_TOKEN;
-  return token ? { authorization: `Bearer ${token}` } : {};
+  if (!token) {
+    return {};
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    return {};
+  }
+  return GITHUB_HOSTS.has(host) ? { authorization: `Bearer ${token}` } : {};
 };
 
 interface GithubTreeEntry {
@@ -110,7 +124,7 @@ const enumerateGithub = async (
   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`;
-  const res = await doFetch(treeUrl, { headers: githubHeaders() });
+  const res = await doFetch(treeUrl, { headers: githubHeaders(treeUrl) });
   if (!res.ok) {
     throw new Error(`${treeUrl} -> ${res.status}`);
   }
@@ -172,7 +186,9 @@ export const mdxRemoteSource = (
   };
 
   const fetchEntry = async (item: RemoteRef): Promise<SourceEntry> => {
-    const res = await doFetch(item.fetchUrl, { headers: githubHeaders() });
+    const res = await doFetch(item.fetchUrl, {
+      headers: githubHeaders(item.fetchUrl),
+    });
     if (!res.ok) {
       throw new Error(`${item.fetchUrl} -> ${res.status}`);
     }

package/src/core/sources/mintlify.ts

@@ -1,4 +1,5 @@
 import { existsSync, watch as fsWatch } from "node:fs";
+import type { WatchListener } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import { isAbsolute, join, relative, resolve } from "pathe";
@@ -9,6 +10,7 @@ import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import type { Diagnostic } from "../types.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
+import { BLUME_WATCH_IGNORE_DIRS, ignoringWatchListener } from "./watch.ts";
 
 /** Options for the Mintlify bridge content source. */
 export interface MintlifySourceOptions {
@@ -42,6 +44,26 @@ const MINTLIFY_SOURCE_IGNORES = [
   "snippets/**",
 ];
 
+/**
+ * Directory names the recursive dev watcher must ignore, on top of the shared
+ * {@link BLUME_WATCH_IGNORE_DIRS} (Blume's own `.blume/` output, VCS,
+ * dependencies). Derived from {@link MINTLIFY_SOURCE_IGNORES} so bridge mode's
+ * watcher stays in sync with what its scan skips (snippets, build output, …).
+ */
+const WATCH_IGNORE_DIRS = [
+  ...BLUME_WATCH_IGNORE_DIRS,
+  ...MINTLIFY_SOURCE_IGNORES.map((pattern) => pattern.replace(/\/\*\*$/u, "")),
+];
+
+/**
+ * Build the recursive-watch listener for the bridge source: ignore events under
+ * {@link WATCH_IGNORE_DIRS} so the dev server's `.blume/` writes don't feed a
+ * regeneration loop. Exported for testing.
+ */
+export const mintlifyWatchListener = (
+  onChange: () => void
+): WatchListener<string> => ignoringWatchListener(onChange, WATCH_IGNORE_DIRS);
+
 /**
  * The Mintlify bridge content source. Reads an unconverted Mintlify project in
  * place and transforms each page to Blume MDX at scan time (callouts → `:::`
@@ -126,7 +148,14 @@ export const mintlifySource = (
   const watch = (onChange: () => void): (() => void) => {
     const disposers: (() => void)[] = [];
     if (existsSync(contentRoot)) {
-      const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
+      // Recursively watch the content root, but skip Blume's own output and
+      // other non-content trees so the dev server's `.blume/` writes don't feed
+      // a regeneration loop (`fs.watch` has no ignore option, so filter here).
+      const watcher = fsWatch(
+        contentRoot,
+        { recursive: true },
+        mintlifyWatchListener(onChange)
+      );
       disposers.push(() => watcher.close());
     }
     // Watch docs.json directly: it lives at the content root but a non-recursive

package/src/core/sources/normalize.ts

@@ -59,6 +59,11 @@ const mapRoute = (
   const groups: string[] = [];
 
   for (const part of rawParts) {
+    // A leading/trailing/double slash yields an empty part; keeping it would
+    // produce a malformed route (`//foo`, `/foo/`) that nothing can link to.
+    if (part === "") {
+      continue;
+    }
     const group = groupLabel(part);
     if (group !== null) {
       groups.push(group);
@@ -113,10 +118,11 @@ export const extractHeadings = (body: string): Heading[] => {
 };
 
 const MD_LINK = /\[[^\]]*\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)/gu;
+const INLINE_CODE = /`[^`]*`/gu;
 
 /**
  * Extract link targets from a markdown body for later validation, recording the
- * 1-based line/column of each target. Skips fenced code blocks.
+ * 1-based line/column of each target. Skips fenced code blocks and inline code.
  */
 export const extractLinks = (body: string): PageLink[] => {
   const links: PageLink[] = [];
@@ -132,7 +138,12 @@ export const extractLinks = (body: string): PageLink[] => {
     if (inFence) {
       continue;
     }
-    for (const match of line.matchAll(MD_LINK)) {
+    // Blank out inline code spans (`[label](/x)` shown as syntax, not a link)
+    // with same-length padding so recorded columns stay accurate.
+    const masked = line.replaceAll(INLINE_CODE, (span) =>
+      " ".repeat(span.length)
+    );
+    for (const match of masked.matchAll(MD_LINK)) {
       const target = match.groups?.target;
       if (target === undefined || match.index === undefined) {
         continue;
@@ -153,7 +164,6 @@ export const extractLinks = (body: string): PageLink[] => {
   return links;
 };
 
-const INLINE_CODE = /`[^`]*`/gu;
 // Double-quoted strings hold JSX attribute values and JSON in `{...}` props; a
 // `<Tag>` written inside prose there (e.g. an "Astro <Font> integration" note)
 // isn't a real usage. Single quotes are left alone so prose apostrophes don't
@@ -207,8 +217,14 @@ const deriveTitle = (
   return titleCase(stripNumericPrefix(base.replace(extname(base), "")));
 };
 
-const withPrefix = (prefix: string | undefined, path: string): string =>
-  prefix ? `${prefix}/${path}` : path;
+/** Strip habitual leading/trailing slashes (`/getting-started`, `guides/`). */
+const trimSlashes = (value: string): string =>
+  value.replaceAll(/^\/+|\/+$/gu, "");
+
+const withPrefix = (prefix: string | undefined, path: string): string => {
+  const clean = prefix ? trimSlashes(prefix) : "";
+  return clean ? `${clean}/${path}` : path;
+};
 
 /**
  * Normalize one source entry into per-locale `PageRecord`s. This is the single
@@ -254,9 +270,15 @@ export const normalizeEntry = (
     : { locales: [""], navPath: entry.ref };
 
   const navPath = withPrefix(ctx.source.prefix, rawNavPath);
+  // Frontmatter `slug` wins, then the adapter-supplied `entry.slug` (the typed
+  // SPI's "logical route input; defaults to ref if omitted"), then the ref.
+  // The extension is re-appended so mapRoute's extname strip can't eat a
+  // dotted slug segment (`v1.2`). A slug that trims to nothing falls back.
+  const slugInput = meta.slug ?? entry.slug;
+  const slug = slugInput ? trimSlashes(slugInput) : "";
   const routeInput = withPrefix(
     ctx.source.prefix,
-    meta.slug ? `${meta.slug}${ext}` : rawNavPath
+    slug ? `${slug}${ext}` : rawNavPath
   );
 
   const { segments, groups, route: logicalRoute } = mapRoute(routeInput);

package/src/core/sources/watch.ts

@@ -0,0 +1,44 @@
+import type { WatchListener } from "node:fs";
+
+/**
+ * Directory segments a recursive dev watcher must never react to. When a
+ * source's content root is the project root — a migrated `.`-rooted project or a
+ * Mintlify bridge — a naive recursive `fs.watch` also sees Blume's own `.blume/`
+ * output, which the dev server rewrites on every render (e.g.
+ * `.blume/.astro/data-store.json`). Left unfiltered, each such write re-triggers
+ * a rescan + runtime regeneration whose writes land back under `.blume/` and
+ * fire the watcher again: a self-sustaining loop that stalls page renders and
+ * floods the console (and, mid-render, corrupts Astro's dev module graph so
+ * `astro:server-app.js` fails to load). `.git`/`node_modules` are here for the
+ * same reason — churn that is never page content. `fs.watch` has no ignore
+ * option, so we filter by the changed path in the callback.
+ */
+export const BLUME_WATCH_IGNORE_DIRS = [".blume", ".git", "node_modules"];
+
+/** Extract single-segment ignore dirs (`foo`) from `foo/**`-style excludes. */
+export const excludeDirSegments = (patterns: readonly string[]): string[] =>
+  patterns
+    .map((pattern) => /^(?<dir>[^*/]+)\/\*\*$/u.exec(pattern)?.groups?.dir)
+    .filter((dir): dir is string => dir !== undefined);
+
+/**
+ * Build a recursive-watch listener that fires `onChange` for content changes but
+ * ignores events whose path crosses an ignored directory segment. A missing
+ * `filename` — rare; the platform couldn't name the changed path — falls through
+ * to `onChange` rather than silently dropping a real edit. Exported for testing.
+ */
+export const ignoringWatchListener = (
+  onChange: () => void,
+  ignoreDirs: Iterable<string> = BLUME_WATCH_IGNORE_DIRS
+): WatchListener<string> => {
+  const ignore = new Set(ignoreDirs);
+  return (_event, filename) => {
+    if (
+      typeof filename === "string" &&
+      filename.split(/[/\\]/u).some((segment) => ignore.has(segment))
+    ) {
+      return;
+    }
+    onChange();
+  };
+};

package/src/markdown/code-title.ts

@@ -25,7 +25,9 @@ export interface CodeTitleTransformer {
   pre: (this: CodeMetaContext, node: PreNode) => void;
 }
 
-const TITLE_ATTR = /title=(?<quote>["'])(?<title>[^"']*)\k<quote>/u;
+// The body excludes only the delimiting quote, so `title="foo's file.ts"`
+// (an apostrophe inside double quotes) still matches.
+const TITLE_ATTR = /title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
 const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
 
 const parseTitle = (raw: string | undefined): string | undefined => {
@@ -33,8 +35,9 @@ const parseTitle = (raw: string | undefined): string | undefined => {
     return undefined;
   }
   const explicit = raw.match(TITLE_ATTR);
-  if (explicit?.groups?.title) {
-    return explicit.groups.title;
+  const attrTitle = explicit?.groups?.dq ?? explicit?.groups?.sq;
+  if (attrTitle) {
+    return attrTitle;
   }
   // The first bare token is the title (```ts blume.config.ts), skipping Shiki
   // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`

package/src/markdown/package-install.ts

@@ -31,7 +31,9 @@ export const packageInstallPlugin = () => ({
       node,
       jsxFlowElement(
         "Tabs",
-        [],
+        // hash off: clicking "pnpm" in an install block must not rewrite the
+        // page hash (clobbering the heading anchor the reader arrived with).
+        [jsxAttribute("hash", "false")],
         PACKAGE_MANAGERS.map((manager) => tabNode(manager, commands[manager]))
       )
     );

package/src/migrate/fumadocs/content.ts

@@ -9,6 +9,7 @@ import {
   isInsideRoot,
   renameTag,
   rewriteCallouts,
+  stripImports,
 } from "../shared.ts";
 
 /**
@@ -29,11 +30,8 @@ const FUMADOCS_IMPORT =
  * injects its components globally, so these imports would fail to resolve once
  * the Fumadocs packages are gone.
  */
-export const stripFumadocsImports = (source: string): string => {
-  const stripped = source.replace(FUMADOCS_IMPORT, "");
-  // Collapse the blank gap a removed import block leaves behind.
-  return stripped === source ? source : stripped.replaceAll(/\n{3,}/gu, "\n\n");
-};
+export const stripFumadocsImports = (source: string): string =>
+  stripImports(source, FUMADOCS_IMPORT);
 
 // ---------------------------------------------------------------------------
 // Callouts

package/src/migrate/fumadocs/index.ts

@@ -114,22 +114,33 @@ const movePage = async (
   };
 };
 
-/** Write a `FolderMeta` to `dest` unless it already exists. */
+/**
+ * Write a `FolderMeta` to `dest` unless it already exists. `handled` tells the
+ * caller whether the source `meta.json` is safe to delete — a skipped write
+ * (target exists) must keep the source, or its title/ordering is lost with
+ * nowhere to recover it from.
+ */
 const writeMeta = async (
   dest: string,
   meta: FolderMeta,
   rel: string,
   warnings: string[]
-): Promise<string[]> => {
+): Promise<{ handled: boolean; warnings: string[] }> => {
   if (Object.keys(meta).length === 0) {
-    return warnings;
+    return { handled: true, warnings };
   }
   if (existsSync(dest)) {
-    return [...warnings, `Skipped ${rel} (target already exists)`];
+    return {
+      handled: false,
+      warnings: [
+        ...warnings,
+        `Skipped ${rel} (target already exists); the source file was kept — merge it into the existing meta.ts by hand.`,
+      ],
+    };
   }
   await mkdir(dirname(dest), { recursive: true });
   await writeFile(dest, renderMetaModule(meta), "utf-8");
-  return warnings;
+  return { handled: true, warnings };
 };
 
 /** Convert one `meta.json` into a typed `meta.ts`, or relocate it if unparseable. */
@@ -173,14 +184,18 @@ const convertMeta = async (
       ...self.warnings,
       ...reshape.warnings,
     ]);
-    await rm(abs, { force: true });
-    return result;
+    if (result.handled) {
+      await rm(abs, { force: true });
+    }
+    return result.warnings;
   }
 
   const { meta, warnings } = translateFumadocsMeta(parsed);
   const result = await writeMeta(dest, meta, rel, warnings);
-  await rm(abs, { force: true });
-  return result;
+  if (result.handled) {
+    await rm(abs, { force: true });
+  }
+  return result.warnings;
 };
 
 interface PageSummary {

package/src/migrate/mintlify/config.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 
-import { dirname, relative, resolve } from "pathe";
+import { dirname, resolve } from "pathe";
 
 import { BlumeError } from "../../core/diagnostics.ts";
 import type {
@@ -10,6 +10,7 @@ import type {
   SidebarItemConfig,
 } from "../../core/schema.ts";
 import { GOOGLE_FONTS } from "../../theme/fonts.ts";
+import { isInsideRoot } from "../shared.ts";
 
 type JsonObject = Record<string, unknown>;
 type NavigationSelectors = ResolvedConfig["navigation"]["selectors"];
@@ -72,11 +73,6 @@ const withoutUndefined = <T extends JsonObject>(value: T): T =>
 const hasOwn = (object: JsonObject, key: string): boolean =>
   Object.hasOwn(object, key);
 
-const isInsideRoot = (root: string, candidate: string): boolean => {
-  const rel = relative(root, candidate);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
-};
-
 const readJsonFile = async (file: string): Promise<unknown> => {
   try {
     return JSON.parse(await readFile(file, "utf-8"));

package/src/migrate/mintlify/index.ts

@@ -1,10 +1,12 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 
-import { dirname, join } from "pathe";
+import { dirname, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeConfig } from "../../core/schema.ts";
+import { ensurePackageJson } from "../shared.ts";
 import { assetSegments } from "./assets.ts";
 import { loadMintlifyConfig, partitionMintlifyRedirects } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
@@ -188,6 +190,56 @@ const applyRelocatedAssets = (
   }
 };
 
+/**
+ * Remove the foreign Mintlify config now that it's been translated into
+ * `blume.config.ts`. Leaving `docs.json`/`mint.json` on disk keeps the project a
+ * bridge-mode candidate: `detectMintlifyBridge` fires on any later run where a
+ * `blume.config.*` is absent (e.g. the config is deleted to re-run the
+ * migration), silently serving the *un-migrated* Mintlify project instead of the
+ * converted one. Removing it makes the conversion permanent — matching the
+ * migrator's promise and how it already deletes inlined snippets.
+ */
+const removeForeignConfig = async (
+  root: string,
+  warnings: string[]
+): Promise<void> => {
+  const removed: string[] = [];
+  for (const name of ["docs.json", "mint.json"]) {
+    const file = join(root, name);
+    if (existsSync(file)) {
+      // oxlint-disable-next-line no-await-in-loop -- sequential fs removes
+      await rm(file, { force: true });
+      removed.push(name);
+    }
+  }
+  if (removed.length > 0) {
+    warnings.push(
+      `Removed ${removed.join(", ")} (translated to blume.config.ts) so "blume dev" no longer falls back to Mintlify bridge mode.`
+    );
+  }
+};
+
+/**
+ * Scaffold the project files a config-only Mintlify repo lacks: a runnable
+ * `package.json` (it ships no npm manifest) and a `.gitignore` for Blume's
+ * generated `.blume/` runtime and `dist/` build output. Both are idempotent —
+ * an existing file is extended, not overwritten — and noted in the warnings.
+ */
+const scaffoldProjectFiles = async (
+  root: string,
+  warnings: string[]
+): Promise<void> => {
+  if (await ensurePackageJson(root)) {
+    warnings.push(
+      "Created a package.json with blume as a dependency; run `npm install`, then `npm run dev`."
+    );
+  }
+  const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+  if (ignored.length > 0) {
+    warnings.push(`Added ${ignored.join(", ")} to .gitignore.`);
+  }
+};
+
 /**
  * Delete the inlined markdown snippets. Component files (e.g. `.jsx`) are kept
  * because their imports were rewritten to resolve against `/snippets`.
@@ -222,6 +274,84 @@ const cleanupSnippets = async (
   }
 };
 
+// Root-absolute asset references in page content (`![…](/screenshots/a.png)`,
+// `src="/img/x.svg"`). Mintlify serves any top-level dir at the site root, so
+// dirs referenced only by content — not the config — must also be mounted.
+const CONTENT_ASSET_REF =
+  /(?:\]\(|src=["'])(?<path>\/[^\s"')]+\.(?:avif|bmp|gif|ico|jpe?g|mov|mp4|pdf|png|svg|webm|webp|zip))/giu;
+
+const contentAssetSegments = (content: string): string[] =>
+  [...content.matchAll(CONTENT_ASSET_REF)].flatMap((match) => {
+    const segment = match.groups?.path?.split("/")[1];
+    return segment ? [segment] : [];
+  });
+
+/**
+ * Rewrite every page to idiomatic Blume MDX in place, collecting what was
+ * dropped or kept for the migration summary. A page whose transform throws
+ * (a dangling snippet import, a snippet cycle) must not abort the whole
+ * migration mid-rewrite; it is left as-is with a warning.
+ */
+const rewritePagesInPlace = async (
+  files: string[],
+  options: {
+    root: string;
+    variables: Record<string, string>;
+    warnings: string[];
+  }
+): Promise<{
+  moved: number;
+  removedKeys: Set<string>;
+  unsupported: Set<string>;
+  keptComponents: Set<string>;
+  assetDirs: Set<string>;
+}> => {
+  const { root, variables, warnings } = options;
+  let moved = 0;
+  const removedKeys = new Set<string>();
+  const unsupported = new Set<string>();
+  const keptComponents = new Set<string>();
+  const assetDirs = new Set<string>();
+  for (const file of files) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+    const raw = await readFile(file, "utf-8");
+    let result: Awaited<ReturnType<typeof transformMintlifyContent>>;
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- sequential transforms
+      result = await transformMintlifyContent(raw, {
+        filePath: file,
+        root,
+        variables,
+      });
+    } catch (error) {
+      warnings.push(
+        `Skipped rewriting ${relative(root, file)}: ${(error as Error).message}. The page was left unconverted — fix it by hand.`
+      );
+      continue;
+    }
+    if (result.content !== raw) {
+      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+      await mkdir(dirname(file), { recursive: true });
+      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+      await writeFile(file, result.content, "utf-8");
+    }
+    for (const key of result.removed) {
+      removedKeys.add(key);
+    }
+    for (const name of result.unsupported) {
+      unsupported.add(name);
+    }
+    for (const name of result.components) {
+      keptComponents.add(name);
+    }
+    for (const segment of contentAssetSegments(result.content)) {
+      assetDirs.add(segment);
+    }
+    moved += 1;
+  }
+  return { assetDirs, keptComponents, moved, removedKeys, unsupported };
+};
+
 /**
  * Migrate a Mintlify project to Blume: translate `docs.json`/`mint.json` into
  * `blume.config.ts`, rewrite every page to idiomatic Blume MDX in place, and
@@ -285,38 +415,15 @@ export const migrateMintlifyProject = async (
     ],
   });
 
-  let moved = 0;
-  const removedKeys = new Set<string>();
-  const unsupported = new Set<string>();
-  const keptComponents = new Set<string>();
-  for (const file of files) {
-    // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
-    const raw = await readFile(file, "utf-8");
-    // oxlint-disable-next-line no-await-in-loop -- sequential transforms
-    const result = await transformMintlifyContent(raw, {
-      filePath: file,
-      root,
-      variables,
-    });
-    if (result.content !== raw) {
-      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
-      await mkdir(dirname(file), { recursive: true });
-      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
-      await writeFile(file, result.content, "utf-8");
-    }
-    for (const key of result.removed) {
-      removedKeys.add(key);
-    }
-    for (const name of result.unsupported) {
-      unsupported.add(name);
-    }
-    for (const name of result.components) {
-      keptComponents.add(name);
-    }
-    moved += 1;
-  }
+  const { moved, removedKeys, unsupported, keptComponents, assetDirs } =
+    await rewritePagesInPlace(files, { root, variables, warnings });
 
-  const assets = await relocateAssets(root, assetSegments(config));
+  // Config-referenced segments (logo/favicon/backgrounds + /images) plus dirs
+  // referenced only by page content — Mintlify serves every top-level dir at
+  // the site root, so both kinds must stay resolvable after migration.
+  const assets = await relocateAssets(root, [
+    ...new Set([...assetSegments(config), ...assetDirs]),
+  ]);
   await cleanupSnippets(root, keptComponents, warnings);
 
   if (config.content?.exclude) {
@@ -324,6 +431,10 @@ export const migrateMintlifyProject = async (
   }
   applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig(root, config);
+  // Drop the source config only after the Blume config is safely on disk, so a
+  // mid-migration failure never leaves the project with neither.
+  await removeForeignConfig(root, warnings);
+  await scaffoldProjectFiles(root, warnings);
 
   if (Object.keys(variables).length > 0) {
     warnings.push(