blume 2.1.3 → 2.2.1

package/src/core/meta.ts

@@ -90,17 +90,16 @@ const withinInclude = (
   );
 
 /**
- * The folder-meta files a filesystem source contributes: `patterns` (every
- * meta module name, shared `meta.$.*` included, by default) under the source's
- * root, minus its `exclude` globs, dependencies, and build output, and only in
- * folders its `include` globs reach. `blume translate` finds the meta files it
- * translates through this too, so it covers exactly the ones the scan reads.
+ * Every folder-meta file under a filesystem source's root: `patterns` (every
+ * meta module name, shared `meta.$.*` included, by default), minus the
+ * source's `exclude` globs, dependencies, and build output — whether or not
+ * its `include` globs reach the file's folder.
  */
-export const findFolderMetaFiles = async (
+const globFolderMetaFiles = (
   source: FolderMetaSource,
-  patterns: readonly string[] = META_FILES
-): Promise<string[]> => {
-  const found = await glob([...patterns], {
+  patterns: readonly string[]
+): Promise<string[]> =>
+  glob([...patterns], {
     absolute: true,
     cwd: source.root,
     // Never descend into dependencies or build output — relevant when the
@@ -116,9 +115,24 @@ export const findFolderMetaFiles = async (
     ],
     onlyFiles: true,
   });
-  return found.filter((file) =>
-    withinInclude(relative(source.root, dirname(file)), source.include)
-  );
+
+/** Whether the source's `include` globs reach a meta file's folder. */
+const isReadMetaFile = (source: FolderMetaSource, file: string): boolean =>
+  withinInclude(relative(source.root, dirname(file)), source.include);
+
+/**
+ * The folder-meta files a filesystem source contributes: `patterns` (every
+ * meta module name, shared `meta.$.*` included, by default) under the source's
+ * root, minus its `exclude` globs, dependencies, and build output, and only in
+ * folders its `include` globs reach. `blume translate` finds the meta files it
+ * translates through this too, so it covers exactly the ones the scan reads.
+ */
+export const findFolderMetaFiles = async (
+  source: FolderMetaSource,
+  patterns: readonly string[] = META_FILES
+): Promise<string[]> => {
+  const found = await globFolderMetaFiles(source, patterns);
+  return found.filter((file) => isReadMetaFile(source, file));
 };
 
 /**
@@ -135,6 +149,29 @@ const metaKeyFor = (prefix: string | undefined, dir: string): string => {
   return dir ? `${clean}/${dir}` : clean;
 };
 
+/** Folder meta by key: per-locale `meta.*` files, and shared `meta.$.*` ones. */
+export interface FolderMetaMaps {
+  meta: Map<string, FolderMeta>;
+  shared: Map<string, FolderMeta>;
+}
+
+/** A folder-meta file Blume found but doesn't read, and the key it would have. */
+export interface UnreadFolderMeta {
+  /** Its folder, relative to the source root. */
+  dir: string;
+  file: string;
+  key: string;
+}
+
+/** What {@link discoverFolderMeta} found across the sources. */
+export interface DiscoveredFolderMeta extends FolderMetaMaps {
+  diagnostics: Diagnostic[];
+  /** The file each meta in `meta` and `shared` was read from. */
+  files: Map<FolderMeta, string>;
+  /** Meta files under a source root that no source's `include` globs reach. */
+  unread: UnreadFolderMeta[];
+}
+
 /**
  * Discover `meta.{ts,js,mjs}` files across the given filesystem sources. Keys are
  * the source's route prefix joined with the directory relative to that source's
@@ -162,11 +199,7 @@ export const discoverFolderMeta = async (
     localeDirs?: readonly string[];
     versionDirs?: readonly string[];
   } = {}
-): Promise<{
-  meta: Map<string, FolderMeta>;
-  shared: Map<string, FolderMeta>;
-  diagnostics: Diagnostic[];
-}> => {
+): Promise<DiscoveredFolderMeta> => {
   const list: FolderMetaSource[] = Array.isArray(sources)
     ? sources
     : [{ root: sources }];
@@ -181,34 +214,67 @@ export const discoverFolderMeta = async (
   const load = createModuleLoader();
   const meta = new Map<string, FolderMeta>();
   const shared = new Map<string, FolderMeta>();
+  const files = new Map<FolderMeta, string>();
+  const unread: UnreadFolderMeta[] = [];
   const diagnostics: Diagnostic[] = [];
 
+  // A version snapshot dir is outermost, with a locale dir one level deeper;
+  // both are hoisted in front of the (prefixed) group path, in that order —
+  // the lookup key reads `version/locale/prefix/dir`.
+  const keyOf = (source: FolderMetaSource, file: string): string => {
+    const dir = relative(source.root, dirname(file));
+    const [head, ...tail] = dir.split("/");
+    const version = head && versionDirs.has(head) ? head : "";
+    const afterVersion = version ? tail : [head ?? "", ...tail];
+    const [localeHead, ...localeTail] = afterVersion;
+    const locale = localeHead
+      ? (localeDirs.get(localeHead.toLowerCase()) ?? "")
+      : "";
+    const rest = (locale ? localeTail : afterVersion).filter(Boolean).join("/");
+    return [version, locale, metaKeyFor(source.prefix, rest)]
+      .filter(Boolean)
+      .join("/");
+  };
+
   // Scan every source under its own root so a source rooted outside
   // `content.root` still contributes its folder meta.
   const perSource = await Promise.all(
     list.map(async (source) => {
-      const files = await findFolderMetaFiles(source);
+      const found = await globFolderMetaFiles(source, META_FILES);
+      // Files outside every `include` glob are never imported; they're kept
+      // by key so a scan that finds pages in their group can say so.
+      for (const file of found) {
+        if (!isReadMetaFile(source, file)) {
+          unread.push({
+            dir: relative(source.root, dirname(file)),
+            file,
+            key: keyOf(source, file),
+          });
+        }
+      }
       const loaded = await Promise.all(
-        files.map(
-          async (
-            file
-          ): Promise<
-            | { ok: true; file: string; value: unknown }
-            | { ok: false; file: string; error: Error }
-          > => {
-            try {
-              return {
-                file,
-                ok: true,
-                value: await resolveMeta(await load(file)),
-              };
-            } catch (error) {
-              // SAFETY: jiti surfaces load/evaluate failures as Error
-              // instances, and only `message` is read downstream.
-              return { error: error as Error, file, ok: false };
+        found
+          .filter((file) => isReadMetaFile(source, file))
+          .map(
+            async (
+              file
+            ): Promise<
+              | { ok: true; file: string; value: unknown }
+              | { ok: false; file: string; error: Error }
+            > => {
+              try {
+                return {
+                  file,
+                  ok: true,
+                  value: await resolveMeta(await load(file)),
+                };
+              } catch (error) {
+                // SAFETY: jiti surfaces load/evaluate failures as Error
+                // instances, and only `message` is read downstream.
+                return { error: error as Error, file, ok: false };
+              }
             }
-          }
-        )
+          )
       );
       return { loaded, source };
     })
@@ -216,23 +282,7 @@ export const discoverFolderMeta = async (
 
   for (const { loaded, source } of perSource) {
     for (const entry of loaded) {
-      const dir = relative(source.root, dirname(entry.file));
-      // A version snapshot dir is outermost, with a locale dir one level
-      // deeper; both are hoisted in front of the (prefixed) group path, in
-      // that order — the lookup key reads `version/locale/prefix/dir`.
-      const [head, ...tail] = dir.split("/");
-      const version = head && versionDirs.has(head) ? head : "";
-      const afterVersion = version ? tail : [head ?? "", ...tail];
-      const [localeHead, ...localeTail] = afterVersion;
-      const locale = localeHead
-        ? (localeDirs.get(localeHead.toLowerCase()) ?? "")
-        : "";
-      const rest = (locale ? localeTail : afterVersion)
-        .filter(Boolean)
-        .join("/");
-      const key = [version, locale, metaKeyFor(source.prefix, rest)]
-        .filter(Boolean)
-        .join("/");
+      const key = keyOf(source, entry.file);
 
       if (!entry.ok) {
         diagnostics.push({
@@ -250,6 +300,7 @@ export const discoverFolderMeta = async (
           ? shared
           : meta;
         target.set(key, result.data);
+        files.set(result.data, entry.file);
       } else {
         diagnostics.push(
           ...diagnosticsFromZod(result.error, {
@@ -261,5 +312,53 @@ export const discoverFolderMeta = async (
     }
   }
 
-  return { diagnostics, meta, shared };
+  // Sources sharing a root partition it with `include` globs, so a file one
+  // source skips may be another's: only a file no source reads is unread.
+  const read = new Set(
+    perSource.flatMap(({ loaded }) => loaded.map((entry) => entry.file))
+  );
+  return {
+    diagnostics,
+    files,
+    meta,
+    shared,
+    unread: unread.filter((entry) => !read.has(entry.file)),
+  };
+};
+
+/**
+ * Lay the folder meta content sources derive (the OpenAPI source's tag
+ * titles and order) beneath the user's `meta.ts` and `meta.$.ts` files, field
+ * by field: a user file's own keys win, and the generated ones fill the rest,
+ * so a `meta.ts` that only renames a tag group keeps its generated `order`.
+ * Generated meta is locale-agnostic, keyed like `meta.$.*`, so it also sits
+ * beneath a locale's own `meta.ts` (`fr/reference/pets` over
+ * `reference/pets`). It doesn't reach into an archived version's snapshot,
+ * whose groups read only meta keyed under the version.
+ */
+export const withGeneratedFolderMeta = (
+  user: FolderMetaMaps,
+  generated: Map<string, FolderMeta>,
+  localeDirs: readonly string[] = []
+): FolderMetaMaps => {
+  const locales = new Set(localeDirs);
+  const beneath = (key: string, meta: FolderMeta): FolderMeta => {
+    const [head, ...rest] = key.split("/");
+    const generatedMeta = generated.get(
+      head !== undefined && locales.has(head) ? rest.join("/") : key
+    );
+    return generatedMeta ? { ...generatedMeta, ...meta } : meta;
+  };
+  return {
+    meta: new Map(
+      [...user.meta].map(([key, meta]) => [key, beneath(key, meta)])
+    ),
+    shared: new Map([
+      ...generated,
+      ...[...user.shared].map(([key, meta]): [string, FolderMeta] => [
+        key,
+        { ...generated.get(key), ...meta },
+      ]),
+    ]),
+  };
 };

package/src/core/nav-diagnostics.ts

@@ -1,6 +1,9 @@
 import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
 import { isInternalPath } from "./base-path.ts";
+import { resolveLocalizable } from "./localizable.ts";
+import { isBuiltInMcpClient } from "./mcp-clients.ts";
+import type { McpClientEntry } from "./mcp-clients.ts";
 import { isPageRef, normalizeRef } from "./navigation.ts";
 import type { SidebarItemConfig } from "./schema.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
@@ -100,6 +103,28 @@ export const validateSearchPopularIcons = (
   return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
 };
 
+/**
+ * Warn about unknown icons on custom "Connect to MCP" clients
+ * (`agents.mcp.clients`), which live outside the navigation model too. A
+ * per-locale label is named in the default locale.
+ */
+export const validateMcpClientIcons = (
+  clients: readonly McpClientEntry[],
+  defaultLocale?: string
+): Diagnostic[] => {
+  const icons = clients.flatMap((client) =>
+    !isBuiltInMcpClient(client) && client.icon
+      ? [
+          {
+            icon: client.icon,
+            where: `MCP client "${resolveLocalizable(client.label, defaultLocale, defaultLocale)}"`,
+          },
+        ]
+      : []
+  );
+  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
+};
+
 /** Whether an internal path resolves to a page or a section that has pages. */
 const resolvesToPages = (routes: Set<string>, path: string): boolean =>
   routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
@@ -108,14 +133,25 @@ const resolvesToPages = (routes: Set<string>, path: string): boolean =>
  * Warn when a config-linked tab/selector target has no matching page. `routes`
  * must be the full set of servable routes — content, custom `.astro` pages, and
  * generated routes — so this runs where all three are known (`generateRuntime`),
- * not in the content-only graph build.
+ * not in the content-only graph build. `servesFile` answers for the files the
+ * site serves beside its pages — `public/` and the generated ones (see
+ * `staticFileResolver`) — so a featured link to `/spec.pdf` or `/llms.txt`
+ * resolves too.
+ *
+ * A tab is checked where it links: its `href` — the author's, or the
+ * section's first page that navigation resolved for a `path` with no page of
+ * its own — and its `path` only when it links there.
  */
 export const validateNavTargets = (
   navigation: Navigation,
-  routes: Set<string>
+  routes: Set<string>,
+  servesFile: (path: string) => boolean = () => false
 ): Diagnostic[] => {
   const targets: { label: string; path: string }[] = [
-    ...navigation.tabs.map((tab) => ({ label: tab.label, path: tab.path })),
+    ...navigation.tabs.map((tab) => ({
+      label: tab.label,
+      path: tab.href ?? tab.path,
+    })),
     ...navigation.selectors.flatMap((selector) =>
       selector.items.map((item) => ({ label: item.label, path: item.path }))
     ),
@@ -141,7 +177,8 @@ export const validateNavTargets = (
     }
     // A query or fragment (`/guides?tab=cli`) rides on the route; only the
     // path names a page.
-    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
+    const bare = path.split(/[?#]/u)[0] ?? path;
+    if (!(resolvesToPages(routes, bare) || servesFile(bare))) {
       seen.add(path);
       diagnostics.push({
         code: "BLUME_NAV_MISSING_PAGE",

package/src/core/navigation.ts

@@ -161,6 +161,40 @@ const stemOf = (filename: string): string =>
 const navStem = (navPath: string): string =>
   stemOf(navPath.split("/").at(-1) ?? navPath);
 
+/**
+ * A page's key in its folder meta `pages` list: its file name without the
+ * extension, ordering prefix, or parentheses (`01-quickstart.mdx` is
+ * `quickstart`).
+ */
+export const pageKey = (filename: string): string =>
+  segmentKey(stemOf(filename));
+
+/**
+ * The keys a folder meta `pages` list can name, by group path: each folder's
+ * pages and subfolders, keyed as `buildFileSystemSidebar` keys its nodes (the
+ * name without its extension, ordering prefix, or parentheses). Read off nav
+ * paths, so it covers pages the sidebar leaves out, like hidden ones.
+ */
+export const folderChildKeys = (
+  navPaths: Iterable<string>
+): Map<string, Set<string>> => {
+  const keys = new Map<string, Set<string>>();
+  const add = (group: string, key: string): void => {
+    const children = keys.get(group) ?? new Set<string>();
+    children.add(key);
+    keys.set(group, children);
+  };
+  for (const navPath of navPaths) {
+    const dirs = navPath.split("/");
+    const filename = dirs.pop() ?? navPath;
+    for (const [depth, dir] of dirs.entries()) {
+      add(dirs.slice(0, depth).join("/"), segmentKey(dir));
+    }
+    add(dirs.join("/"), pageKey(filename));
+  }
+  return keys;
+};
+
 interface MutablePage {
   kind: "page";
   key: string;
@@ -397,16 +431,21 @@ const applyFolderMeta = (
 
 /**
  * Warn when an index page's own frontmatter title diverges from its folder's
- * explicit `meta.title`. The sidebar label and the page's own `<title>`/heading
- * are resolved from two independent sources — under i18n, a translator can
- * update the folder's `meta.ts` and forget the index page's own frontmatter
- * (or vice versa), and a correct-looking sidebar hides the mismatch.
+ * explicit `meta.title`. The sidebar label and the page's own title (its
+ * heading, and its `<title>` unless `seo.title` replaces that) are resolved
+ * from two independent sources — under i18n, a translator can update the
+ * folder's `meta.ts` and forget the index page's own frontmatter (or vice
+ * versa), and a correct-looking sidebar hides the mismatch.
  *
  * Only fires when the index page's own sidebar row is hidden
  * (`sidebar.hidden`), so the linked group header is the only sidebar label the
  * page has. A visible index row shows the page's own label beneath the header,
  * so the sidebar already carries both titles and a divergence there is a
- * deliberate pairing ("CLI" over "Overview"), not drift.
+ * deliberate pairing ("CLI" over "Overview"), not drift. A hidden index keeps a
+ * different title on purpose the same way any page does: its `sidebar.label`
+ * names the folder title, so the label its own row would carry agrees with the
+ * header. The suggestion names only ways out that clear the warning:
+ * `validate --strict` fails on any warning, so leaving it is not one.
  *
  * Only fires when the page has an explicit frontmatter `title` of its own:
  * when it's absent, `page.title` is derived from the first heading or the
@@ -440,15 +479,19 @@ const indexTitleMismatchDiagnostic = (
   const meta =
     folderMeta.get(metaKey(folderPath, metaPrefix)) ??
     sharedMeta.get(metaKey(folderPath, sharedMetaPrefix));
-  if (!meta?.title || meta.title === page.title) {
+  if (
+    !meta?.title ||
+    meta.title === page.title ||
+    meta.title === page.meta.sidebar.label
+  ) {
     return undefined;
   }
   return {
     code: "BLUME_NAV_INDEX_TITLE_MISMATCH",
     file: page.sourcePath ?? page.id,
-    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}" — the sidebar shows the folder title while the page's own <title>/heading still say "${page.title}".`,
+    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}". The page hides its own sidebar row, so "${meta.title}" is the only sidebar label it has.`,
     severity: "warning",
-    suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`,
+    suggestion: `Change the page's title or the folder's meta.ts title so they match, set the page's sidebar.label to "${meta.title}" to keep its title on purpose, or remove sidebar.hidden so the sidebar also lists the page under its own label.`,
   };
 };
 
@@ -622,10 +665,16 @@ const hoistPages = (
  * group's *children*, not the tree root — so hoisting only the root leaves a
  * tab section's loose pages interleaved with its groups. Hoist the top level of
  * every group that owns a tab (matched on its URL path), mirroring the root.
+ *
+ * The section is the outermost group at the tab's path, the one render-time
+ * scoping shows (`sectionChildren`). A `(group)` folder inside it adds no
+ * route segment, so it shares that path, but it is a group in the section, not
+ * the section itself: below a matched group its path no longer matches, and
+ * the (group)'s own level hoists only by the `hoistPages` rules.
  */
 const hoistTabSections = (
   nodes: MutableNode[],
-  tabPaths: Set<string>,
+  tabPaths: ReadonlySet<string>,
   display: SidebarDisplay
 ): void => {
   for (const node of nodes) {
@@ -634,6 +683,10 @@ const hoistTabSections = (
     }
     if (node.routePath !== undefined && tabPaths.has(node.routePath)) {
       hoistPages(node.children, display, true);
+      const inner = new Set(tabPaths);
+      inner.delete(node.routePath);
+      hoistTabSections(node.children, inner, display);
+      continue;
     }
     hoistTabSections(node.children, tabPaths, display);
   }
@@ -1049,6 +1102,11 @@ const resolveTabHref = (
     return path;
   }
   const rest = pathUnder(path, roots.tabs);
+  // An archived tree's root tab links back to the current docs: its section
+  // is the whole current tree, no page of which this tree holds.
+  if (rest === "/" && roots.tree !== roots.tabs) {
+    return path;
+  }
   const section =
     rest === undefined || rest === "/" ? path : joinRoute(roots.tree, rest);
   let first: string | undefined;
@@ -1058,10 +1116,12 @@ const resolveTabHref = (
       if (route === section) {
         return true;
       }
+      // `isUnderPath`, not a `${section}/` prefix: a root tab's section is
+      // `/`, which every route sits under but none starts `//`.
       if (
         first === undefined &&
         route !== undefined &&
-        route.startsWith(`${section}/`)
+        isUnderPath(route, section)
       ) {
         first = route;
       }

package/src/core/ordering-prefix.ts

@@ -11,11 +11,21 @@ const ORDERING_PREFIX = /^(?<order>\d+)[-_.]/u;
  * (`2024-01-05`, `2024-01-05-first-post`), whose year would sort the sidebar
  * and leave only `01-05…` of the route.
  */
-const NOT_AN_ORDER = /^(?:\d+\.\d|\d{4}-\d{2}-\d{2}(?:[-_.]|$))/u;
+const VERSION_OR_ISO_DATE = /^(?:\d+\.\d|\d{4}-\d{2}-\d{2}(?:[-_.]|$))/u;
+
+/**
+ * The other dates a name can start with, kept whole the same way: day or
+ * month first with a four-digit year last (`12-05-2022`, `1-5-2022-launch`),
+ * and a year and month (`2024-01`, `2024-01-recap`). Blume once read their
+ * first number as an ordering prefix, so these names routed as `05-2022` and
+ * `01`; {@link formerRouteName} still knows those routes, so they redirect.
+ */
+const DATE_NAME =
+  /^(?:(?:0?[1-9]|[12]\d|3[01])-(?:0?[1-9]|[12]\d|3[01])-\d{4}|\d{4}-(?:0[1-9]|1[0-2]))(?:[-_.]|$)/u;
 
 /** The digits of `name`'s ordering prefix (`01` of `01-intro`), if it has one. */
 export const orderingPrefix = (name: string): string | undefined =>
-  NOT_AN_ORDER.test(name)
+  VERSION_OR_ISO_DATE.test(name) || DATE_NAME.test(name)
     ? undefined
     : name.match(ORDERING_PREFIX)?.groups?.order;
 
@@ -25,3 +35,13 @@ export const stripOrderingPrefix = (name: string): string => {
   // The prefix is the digits plus their one-character separator.
   return order === undefined ? name : name.slice(order.length + 1);
 };
+
+/**
+ * The name an earlier Blume routed `name` as, when it differs from today's:
+ * a {@link DATE_NAME} lost its first number as an ordering prefix
+ * (`12-05-2022` routed as `05-2022`, `2024-01` as `01`).
+ */
+export const formerRouteName = (name: string): string | undefined =>
+  DATE_NAME.test(name) && !VERSION_OR_ISO_DATE.test(name)
+    ? name.slice(name.indexOf("-") + 1)
+    : undefined;

package/src/core/pinned-ids.ts

@@ -0,0 +1,141 @@
+/**
+ * A pinned heading id (`## Heading [#a--b]`, `{#a--b}`) is used verbatim, but
+ * the parse that reads it applies smart punctuation (Astro's `smartypants`,
+ * on by default) to the whole heading first: `--` became `–`, `...` became
+ * `…`, and quotes curled, so the id rendered as `a–b` while every link
+ * written to it says `#a--b`. Smart punctuation leaves a backslash-escaped
+ * character alone, so before a source is parsed, the punctuation in each
+ * heading's trailing markers is escaped where the author wrote it, and the
+ * parse reads the id as typed. An id with a typed `–` keeps it.
+ *
+ * The page render, each `<include>` splice, and the scan-time heading reader
+ * all escape their source this way, so the rendered id and the anchor index
+ * `blume validate` checks against agree.
+ */
+
+import type { Heading, Nodes } from "mdast";
+import { markdownToMdast, mdxToMdast } from "satteri";
+import type { SourceFormat } from "satteri";
+
+import {
+  MARKDOWN_BODY_FEATURES,
+  MDX_BODY_FEATURES,
+} from "../markdown/features.ts";
+import { parseHeadingMarkers } from "./heading-markers.ts";
+
+/** What smart punctuation rewrites: dashes, an ellipsis, and quotes. */
+const SMART_INPUT = /--|\.\.\.|['"]/u;
+
+/**
+ * A run that opens a pinned id, up to whitespace or a closing bracket. The
+ * runs never overlap, so finding them all stays linear.
+ */
+const PIN_RUN = /[[{]#[^\s\]}]*/gu;
+
+/** A backslash escape (kept as is), or a character smart punctuation reads. */
+const PUNCTUATION = /\\[\s\S]|[-.'"]/gu;
+
+const escapePunctuation = (text: string): string =>
+  text.replaceAll(PUNCTUATION, (match) =>
+    match.length === 1 ? `\\${match}` : match
+  );
+
+/** Whether any pinned id in the source holds something smart punctuation rewrites. */
+const hasPunctuatedPin = (source: string): boolean => {
+  for (const [run] of source.matchAll(PIN_RUN)) {
+    if (SMART_INPUT.test(run)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/** One replacement in the source: `text` in place of `from`…`end`. */
+interface Edit {
+  end: number;
+  from: number;
+  text: string;
+}
+
+/**
+ * The escape a heading's trailing markers need, if any. Markers only count at
+ * the end of a heading's last text node (see `markdown/heading-anchors.ts`),
+ * and a heading that is nothing but markers keeps them as literal text, so
+ * neither is touched here either.
+ */
+const pinEdit = (heading: Heading, source: string): Edit | undefined => {
+  const last = heading.children.at(-1);
+  const start = last?.position?.start.offset;
+  const end = last?.position?.end.offset;
+  if (last?.type !== "text" || start === undefined || end === undefined) {
+    return undefined;
+  }
+  const parsed = parseHeadingMarkers(last.value);
+  if (
+    parsed.id === undefined ||
+    (parsed.text === "" && heading.children.length === 1)
+  ) {
+    return undefined;
+  }
+  // The same markers, read where the author wrote them.
+  const written = parseHeadingMarkers(source.slice(start, end));
+  const from = start + written.text.length;
+  const markers = source.slice(from, end);
+  if (written.id === undefined || !SMART_INPUT.test(markers)) {
+    return undefined;
+  }
+  return { end, from, text: escapePunctuation(markers) };
+};
+
+/** Collect the edits for every heading under `node`, in source order. */
+const collectEdits = (node: Nodes, source: string, edits: Edit[]): void => {
+  if (node.type === "heading") {
+    const edit = pinEdit(node, source);
+    if (edit) {
+      edits.push(edit);
+    }
+    return;
+  }
+  if ("children" in node) {
+    for (const child of node.children) {
+      collectEdits(child, source, edits);
+    }
+  }
+};
+
+const parse = (source: string, format: SourceFormat): Nodes | undefined => {
+  try {
+    return format === "mdx"
+      ? mdxToMdast(source, { features: MDX_BODY_FEATURES })
+      : markdownToMdast(source, { features: MARKDOWN_BODY_FEATURES });
+  } catch {
+    // A source MDX can't parse fails its own render, with its own error.
+    return undefined;
+  }
+};
+
+/**
+ * `source` with the smart-punctuation characters in each heading's pinned id
+ * backslash-escaped, so a parse with smart punctuation reads the id as
+ * written. `source` must be the whole text the parse will read, link
+ * definitions included: they decide which brackets are links. A source
+ * without such a pin is returned as is, unparsed.
+ */
+export const escapePinnedIds = (
+  source: string,
+  format: SourceFormat
+): string => {
+  const tree = hasPunctuatedPin(source) ? parse(source, format) : undefined;
+  if (!tree) {
+    return source;
+  }
+  const edits: Edit[] = [];
+  collectEdits(tree, source, edits);
+  let escaped = "";
+  let at = 0;
+  for (const edit of edits) {
+    escaped += source.slice(at, edit.from) + edit.text;
+    at = edit.end;
+  }
+  return escaped + source.slice(at);
+};