blume 0.5.2 → 0.5.3

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,7 +1,7 @@
 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";
@@ -190,6 +190,35 @@ 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
@@ -245,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
@@ -308,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) {
@@ -347,6 +431,9 @@ 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) {

package/src/migrate/mintlify/snippets.ts

@@ -3,6 +3,7 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { dirname, relative, resolve } from "pathe";
 
 import matter from "../../core/frontmatter.ts";
+import { isInsideRoot, stripImports } from "../shared.ts";
 
 const MARKDOWN_SNIPPET_IMPORT =
   /^import\s+(?<name>[$A-Z_a-z][$\w]*)\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
@@ -37,11 +38,6 @@ interface SnippetTransformOptions {
   trail?: string[];
 }
 
-const isInsideRoot = (root: string, candidate: string): boolean => {
-  const rel = relative(root, candidate);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
-};
-
 const escapeRegExp = (value: string): string =>
   value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 
@@ -151,7 +147,9 @@ const interpolateProps = (
   source.replaceAll(PLACEHOLDER, (value, name: string) => props[name] ?? value);
 
 const stripImport = (source: string, importText: string): string =>
-  source.replace(importText, "").replaceAll(/\n{3,}/gu, "\n\n");
+  // Seam-targeted removal: a whole-document `\n{3,}` collapse would rewrite
+  // real double blank lines inside the page's code fences.
+  stripImports(source, new RegExp(escapeRegExp(importText), "gu"));
 
 const replacePlaceholder = (
   source: string,
@@ -189,9 +187,20 @@ export const rewriteMintlifyMarkdownSnippets = async (
       );
     }
     seen.add(file);
-    const readFile = options.readFile ?? readFileFromDisk;
+    const readFile =
+      options.readFile ??
+      ((path: string): Promise<string> => readFileFromDisk(path, "utf-8"));
     try {
-      const raw = await readFile(file);
+      let raw: string;
+      try {
+        raw = await readFile(file);
+      } catch {
+        // A dangling import must fail with a message that names both ends —
+        // the caller downgrades it to a per-page warning and moves on.
+        throw new Error(
+          `snippet ${rootRelativePath(options.root, file)} (imported by ${rootRelativePath(options.root, options.filePath)}) does not exist`
+        );
+      }
       const content = matter(raw).content.trim();
       const transformed = await rewriteMintlifyMarkdownSnippets(content, {
         ...options,

package/src/migrate/nextra/index.ts

@@ -5,8 +5,9 @@ import { basename, dirname, extname, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import matter from "../../core/frontmatter.ts";
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeConfig, FolderMeta } from "../../core/schema.ts";
-import { writeBlumeConfig } from "../shared.ts";
+import { rewriteFrameworkScripts, writeBlumeConfig } from "../shared.ts";
 import {
   rewriteNextraCallouts,
   stripNextraImports,
@@ -353,11 +354,25 @@ export const migrateNextraProject = async (
   );
   await writeBlumeConfig(root, buildConfig(plan.tabs));
 
+  // Tear down the Next scaffolding like the Fumadocs migrator does — without
+  // this, `npm run dev` still launches Next against the gutted content tree.
+  const scriptsRewritten = await rewriteFrameworkScripts(
+    root,
+    /\bnext\b/u,
+    /\bnextra\b/u
+  );
+  await ensureGitignore(root, [".blume/", "dist/"]);
+
   const warnings = [
     ...plan.warnings,
     ...pages.skipped.map((rel) => `Skipped ${rel} (target already exists)`),
     ...relocateWarnings,
   ];
+  if (scriptsRewritten) {
+    warnings.push(
+      "Repointed package.json scripts at Blume (dev/build/preview); remove the leftover Next/Nextra dependencies and next.config/theme.config by hand."
+    );
+  }
   if (pages.removedKeys.length > 0) {
     warnings.push(
       `Dropped unsupported page frontmatter keys: ${pages.removedKeys.join(", ")}.`

package/src/migrate/shared.ts

@@ -125,6 +125,27 @@ export const ensurePackageJson = async (root: string): Promise<boolean> => {
   return true;
 };
 
+// A marker no markdown document contains, planted where an import was removed
+// so the blank-gap collapse can target the seams alone.
+const IMPORT_SEAM = "\u0000blume-import-seam\u0000";
+
+/**
+ * Remove every match of an import pattern, collapsing the blank gap each
+ * removal leaves behind — without touching blank runs elsewhere in the
+ * document (double blank lines inside code fences are real content that a
+ * whole-document `\n{3,}` collapse used to corrupt).
+ */
+export const stripImports = (source: string, pattern: RegExp): string => {
+  const marked = source.replaceAll(pattern, IMPORT_SEAM);
+  if (marked === source) {
+    return source;
+  }
+  return marked
+    .replaceAll(new RegExp(String.raw`\n*(?:${IMPORT_SEAM})+\n*`, "gu"), "\n\n")
+    .replace(/^\n+/u, "")
+    .replace(/\n+$/u, "\n");
+};
+
 // ---------------------------------------------------------------------------
 // Callout components -> Blume `:::` directives
 // ---------------------------------------------------------------------------
@@ -161,14 +182,30 @@ const dedent = (value: string): string => {
   return lines.map((line) => line.slice(common)).join("\n");
 };
 
+/**
+ * A colon fence one longer than any directive fence in the body — nested
+ * container directives require the outer fence to be longer than the inner
+ * ones, or the inner `:::` closes the outer block.
+ */
+const fenceOver = (body: string): string => {
+  let max = 2;
+  for (const match of body.matchAll(/^ {0,3}(?<colons>:{3,})/gmu)) {
+    max = Math.max(max, match.groups?.colons?.length ?? 0);
+  }
+  return ":".repeat(Math.max(3, max + 1));
+};
+
 const directiveBlock = (
   directive: string,
   title: string | undefined,
   inner: string
 ): string => {
-  const head = title ? `:::${directive}[${title}]` : `:::${directive}`;
   const body = dedent(inner);
-  return `${head}\n${body}\n:::`;
+  const fence = fenceOver(body);
+  const head = title
+    ? `${fence}${directive}[${title}]`
+    : `${fence}${directive}`;
+  return `${head}\n${body}\n${fence}`;
 };
 
 /**
@@ -200,6 +237,40 @@ export const findOpenTagEnd = (source: string, from: number): number => {
   return -1;
 };
 
+/**
+ * Find the close tag matching an open tag, honoring same-tag nesting
+ * (`<Note>a<Note>b</Note>c</Note>` must close at the *outer* `</Note>`).
+ * Returns the index of the matching `</Tag>`, or -1 when unterminated.
+ */
+const findMatchingClose = (
+  source: string,
+  tag: string,
+  from: number
+): number => {
+  const scanner = new RegExp(`<(?<closing>/)?${tag}(?=[\\s/>])`, "gu");
+  scanner.lastIndex = from;
+  let depth = 0;
+  for (let match = scanner.exec(source); match; match = scanner.exec(source)) {
+    if (match.groups?.closing) {
+      if (depth === 0) {
+        return match.index;
+      }
+      depth -= 1;
+      continue;
+    }
+    // A nested open tag: skip its attributes; self-closing ones don't nest.
+    const end = findOpenTagEnd(source, match.index + tag.length + 1);
+    if (end === -1) {
+      return -1;
+    }
+    if (source[end - 1] !== "/") {
+      depth += 1;
+    }
+    scanner.lastIndex = end + 1;
+  }
+  return -1;
+};
+
 const directiveFor = (
   tag: string,
   attrs: string,
@@ -256,7 +327,7 @@ export const rewriteCallouts = (
     const selfClosing = attrs.trimEnd().endsWith("/");
     const closeIndex = selfClosing
       ? openEnd
-      : source.indexOf(closeTag, openEnd + 1);
+      : findMatchingClose(source, tag, openEnd + 1);
 
     if (!directive || (!selfClosing && closeIndex === -1)) {
       output += source.slice(cursor, openEnd + 1);
@@ -272,10 +343,12 @@ export const rewriteCallouts = (
         : `:::${directive}\n:::`;
       cursor = openEnd + 1;
     } else {
+      // Recurse so nested callouts (of any tag) convert too — they'd
+      // otherwise survive as components Blume doesn't ship.
       output += directiveBlock(
         directive,
         title,
-        source.slice(openEnd + 1, closeIndex)
+        rewriteCallouts(source.slice(openEnd + 1, closeIndex), options)
       );
       cursor = closeIndex + closeTag.length;
     }