blume 1.6.3 → 1.6.4

package/src/components/layout/PageLayout.astro

@@ -35,6 +35,7 @@ import {
 import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
+import { searchLocaleFor } from "./search-locale.ts";
 import "blume:theme";
 import { ClientRouter } from "astro:transitions";
 import Analytics from "./Analytics.astro";
@@ -160,9 +161,10 @@ const strings = ui ?? EN_UI;
 // from a not-yet-regenerated snapshot) still renders instead of coming out
 // blank — the PageActions pattern.
 const navStrings = { ...EN_UI.nav, ...strings.nav };
-// Filter search to the active language only when the site is multi-locale.
-const searchLocale =
-  localeSwitch && localeSwitch.length > 1 ? locale : undefined;
+// Scope search to the active language on a multi-locale site. Read from the
+// i18n snapshot, not the switcher list, so pages rendered without one still
+// filter (see `searchLocaleFor`).
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 const pageTitle = page?.title ?? site.title;
 const description = page?.description ?? site.description;
 const route = page?.route ?? "/";

package/src/components/layout/ReferenceLayout.astro

@@ -1,5 +1,6 @@
 ---
 import "blume:theme";
+import data from "blume:data";
 import type { BlumeFavicon } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -16,6 +17,7 @@ import {
   THEME_INIT_SCRIPT,
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import { searchLocaleFor } from "./search-locale.ts";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
 // on top, then a full-height region the reference mounts into. Unlike RootLayout
@@ -91,6 +93,8 @@ const {
 } = Astro.props;
 
 const strings = ui ?? EN_UI;
+// Scope search to the reference page's language on a multi-locale site.
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 
 const bannerKey = banner?.dismissible ? banner.key : null;
 ---
@@ -126,6 +130,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       navigation={navigation}
       route={route}
       searchEnabled={searchEnabled}
+      searchLocale={searchLocale}
       site={site}
     />
     <div

package/src/components/layout/RootLayout.astro

@@ -58,6 +58,7 @@ import {
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
+import { searchLocaleFor } from "./search-locale.ts";
 import PageActions from "./PageActions.astro";
 import PageFeedback from "./PageFeedback.astro";
 import Pagination from "./Pagination.astro";
@@ -289,9 +290,10 @@ const strings = ui ?? EN_UI;
 const navStrings = { ...EN_UI.nav, ...strings.nav };
 const actionStrings = { ...EN_UI.actions, ...strings.actions };
 const contentStrings = { ...EN_UI.content, ...strings.content };
-// Filter search to the active language only when the site is multi-locale.
-const searchLocale =
-  localeSwitch && localeSwitch.length > 1 ? locale : undefined;
+// Scope search to the active language on a multi-locale site. Read from the
+// i18n snapshot, not the switcher list, so pages rendered without one still
+// filter (see `searchLocaleFor`).
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 // TOC entries: the configured heading range, or none when the TOC is disabled
 // (an empty list makes TableOfContents render nothing).
 // API operation pages own a two-column body (docs + request panel) and their own

package/src/components/layout/search-locale.ts

@@ -0,0 +1,13 @@
+/**
+ * The locale the search dialog should scope to, or `undefined` when scoping
+ * is pointless. Derived from the resolved i18n settings rather than from the
+ * header's language-switcher entries: the switcher list is only assembled by
+ * the content catch-all, so pages rendered without one (custom pages built on
+ * `PageLayout`, the changelog index, the 404 page, the API reference shell)
+ * would otherwise search every language while showing no "All languages"
+ * toggle. A single-locale site (or one without i18n) has nothing to scope.
+ */
+export const searchLocaleFor = (
+  i18n: { locales: { code: string }[] } | null,
+  locale: string
+): string | undefined => (i18n && i18n.locales.length > 1 ? locale : undefined);

package/src/components/openapi/ApiOverview.astro

@@ -1,54 +1,22 @@
 ---
 import specs from "blume:openapi";
 
-import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
+import { specAddresses, specOf } from "../../openapi/model.ts";
 
 // The spec-level metadata block (version + base URLs) at the top of an API
 // overview page. The tag sections that follow are emitted by `overviewMdx` as
 // markdown headings plus `<ApiTagOperations>` lists, so they land in the
-// table of contents.
+// table of contents. The agent surfaces downlevel this block from the same
+// `specAddresses`, so the `.md` page lists what this one shows.
 interface Props {
   source: string;
 }
 
 const { source } = Astro.props;
-const spec = specs[source];
-
-// OpenAPI declares `servers` as an array of URLs; AsyncAPI as a named map of
-// host/protocol/pathname; a GraphQL schema names no server, so its configured
-// live endpoint stands in. All flatten into one list of address chips.
-const addresses: string[] = [];
-if (spec?.kind === "graphql") {
-  if (spec.endpoint) {
-    addresses.push(spec.endpoint);
-  }
-} else if (spec?.kind === "asyncapi") {
-  const servers = (spec.document as AsyncApiDocument).servers ?? {};
-  for (const server of Object.values(servers)) {
-    if (server?.host) {
-      addresses.push(
-        `${server.protocol ? `${server.protocol}://` : ""}${server.host}${server.pathname ?? ""}`
-      );
-    }
-  }
-} else {
-  // Hand-written specs sometimes declare `servers` as a bare object; degrade
-  // to no address chips instead of throwing mid-build.
-  const declared = ((spec?.document ?? {}) as { servers?: { url?: string }[] })
-    .servers;
-  const servers = Array.isArray(declared) ? declared : [];
-  for (const server of servers) {
-    if (server.url) {
-      addresses.push(server.url);
-    }
-  }
-}
-let addressLabel = "Base URL";
-if (spec?.kind === "asyncapi") {
-  addressLabel = "Servers";
-} else if (spec?.kind === "graphql") {
-  addressLabel = "Endpoint";
-}
+const spec = specOf(specs, source);
+const { addresses, label: addressLabel } = spec
+  ? specAddresses(spec)
+  : { addresses: [], label: "" };
 ---
 
 {

package/src/components/openapi/ApiTagOperations.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { specOf } from "../../openapi/model.ts";
 import { withBase } from "../islands/base-path.ts";
 import MethodBadge from "./MethodBadge.astro";
 
@@ -14,7 +15,7 @@ interface Props {
 }
 
 const { source, tag } = Astro.props;
-const operations = Object.values(specs[source]?.operations ?? {}).filter(
+const operations = Object.values(specOf(specs, source)?.operations ?? {}).filter(
   (operation) => operation.tagSlug === tag
 );
 ---

package/src/components/openapi/AsyncApiOperation.astro

@@ -4,6 +4,7 @@ import specs from "blume:openapi";
 
 import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
 import { asyncApiOperationObject } from "../../openapi/asyncapi.ts";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import {
   asyncApiSecurityEntries,
@@ -47,8 +48,8 @@ interface Props {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 const document = (spec?.document ?? {}) as AsyncApiDocument;
 const operation = ref ? asyncApiOperationObject(document, ref) : undefined;
 const channel = ref?.channelId

package/src/components/openapi/GraphqlOperation.astro

@@ -10,6 +10,7 @@ import {
   graphqlRootField,
   isGraphqlOperationKind,
 } from "../../openapi/graphql.ts";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import { DEPRECATED_LABEL_CLASS } from "../colors.ts";
 import {
@@ -46,8 +47,8 @@ interface Props {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 const document = (spec?.document ?? { roots: {}, types: {} }) as GraphqlDocument;
 const isOperation = ref !== undefined && isGraphqlOperationKind(ref.method);
 const field = ref && isOperation ? graphqlRootField(document, ref) : undefined;

package/src/components/openapi/Operation.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import {
   mergeParameters,
   type ParameterLike,
@@ -61,8 +62,8 @@ interface FullOperation {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 // The AsyncAPI and GraphQL front-ends render their own bodies; the lookups
 // below are OpenAPI-shaped (paths, request/response) and resolve to nothing
 // for them.

package/src/core/i18n.ts

@@ -48,8 +48,19 @@ export const resolveFallbackLocale = (
   return i18n.fallbackLocale ?? i18n.defaultLocale;
 };
 
+/**
+ * The slice of the i18n settings URL routing reads. `ResolvedI18nConfig` and
+ * the `blume:data` runtime shape both satisfy it, so route helpers serve the
+ * Node-side graph and the rendered page alike.
+ */
+export interface LocaleRouting {
+  defaultLocale: string;
+  hideDefaultLocalePrefix: boolean;
+  locales: { code: string }[];
+}
+
 /** URL prefix for a locale: `""` for the hidden default, else `/<code>`. */
-export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
+export const localePrefix = (code: string, i18n: LocaleRouting): string =>
   code === i18n.defaultLocale && i18n.hideDefaultLocalePrefix ? "" : `/${code}`;
 
 /**
@@ -59,7 +70,7 @@ export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
 export const localizeRoute = (
   logicalRoute: string,
   code: string,
-  i18n: ResolvedI18nConfig
+  i18n: LocaleRouting
 ): string => {
   const prefix = localePrefix(code, i18n);
   if (!prefix) {

package/src/core/links.ts

@@ -7,6 +7,8 @@ import {
   isRelativeImageTarget,
   resolveRelativeImage,
 } from "./content-assets.ts";
+import type { LocaleRouting } from "./i18n.ts";
+import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
@@ -78,6 +80,8 @@ interface LinkContext {
   /** Servable routes outside the graph (custom pages, generated routes); their
    * headings are unknown, so anchors there are accepted unchecked. */
   extraRoutes: Set<string>;
+  /** Locale routing, when the site is multi-locale; drives served-route resolution. */
+  i18n: LocaleRouting | null;
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
@@ -189,6 +193,30 @@ const checkAnchor = (
   };
 };
 
+/**
+ * The route a link on `page` actually lands on. Rendered under a prefixed
+ * locale, a root-relative link moves into that locale when the localized route
+ * is served — a real translation (whose own headings then answer the anchor
+ * check) or a fallback page (accepted unchecked via `extraRoutes`) — exactly as
+ * `LocaleLinks.astro` rewrites it at render time. Otherwise the authored route
+ * stands.
+ */
+const servedRoute = (
+  authored: string,
+  page: PageRecord,
+  ctx: LinkContext
+): string =>
+  ctx.i18n
+    ? localizeLinkPath(authored, {
+        basePath: ctx.basePath,
+        i18n: ctx.i18n,
+        locale: page.locale,
+        routes: {
+          has: (route) => ctx.routes.has(route) || ctx.extraRoutes.has(route),
+        },
+      })
+    : authored;
+
 /** Validate a resolved internal path: asset, route, then optional anchor. */
 const checkPathLink = (
   resolved: string,
@@ -204,7 +232,8 @@ const checkPathLink = (
   // relative link already resolved against the based `page.route`). A real
   // route always wins over the asset-extension heuristic, so a dotted route
   // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
-  const route = toRoute(withBasePath(ctx.basePath, resolved));
+  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  const route = servedRoute(authoredRoute, page, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
   }
@@ -374,6 +403,8 @@ export const validateLinks = async (
      * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
      */
     extraRoutes?: string[];
+    /** Locale routing when i18n is on; links then resolve into the page's locale. */
+    i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
@@ -385,6 +416,7 @@ export const validateLinks = async (
     anchors: buildAnchorIndex(graph.pages),
     basePath,
     extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
+    i18n: options.i18n ?? null,
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>

package/src/core/locale-links.ts

@@ -0,0 +1,163 @@
+import {
+  isInternalPath,
+  normalizePath,
+  stripBasePath,
+  withBasePath,
+} from "./base-path.ts";
+import { localePrefix, localizeRoute } from "./i18n.ts";
+import type { LocaleRouting } from "./i18n.ts";
+
+/**
+ * Locale-aware resolution of content links.
+ *
+ * Authors write internal links as if mounted at the default locale's root
+ * (`[x](/guide)`, `<Card href="/guide">`), and translated pages are usually
+ * copies of the source with the same links — so read on `/fr/…`, a link would
+ * otherwise drop the reader back into the default language. These helpers move
+ * such a link to the reader's locale (`/fr/guide`) when that route is served
+ * (a real translation or a materialized fallback page), and leave it alone
+ * otherwise: an explicit cross-locale link (`/de/guide`), a custom `.astro`
+ * page or generated route that has no per-locale variant, or a missing
+ * translation on a site with fallbacks disabled all keep their authored
+ * target rather than pointing at a 404.
+ *
+ * The rewrite runs at render time (`components/layout/LocaleLinks.astro`)
+ * because content is compiled once per file but served per route: a fallback
+ * route renders the fallback locale's file under the missing locale's URL, and
+ * a shared `page.$.mdx` renders under every locale. The link checker applies
+ * the same resolution so anchors are validated against the page a reader lands
+ * on.
+ */
+
+/** A route set, as the runtime (`Set`) or the checker (a predicate) sees it. */
+export interface RouteSet {
+  has: (route: string) => boolean;
+}
+
+export interface LocalizeLinkOptions {
+  /** Site-wide route mount point (`""` or `/seg`); routes carry it. */
+  basePath: string;
+  i18n: LocaleRouting;
+  /** Locale of the page the link is rendered on. */
+  locale: string;
+  /** Every served route, base-prefixed like `path` (no `deployment.base`). */
+  routes: RouteSet;
+}
+
+/**
+ * Mirrors the asset heuristic in `markdown/base-links.ts`: a path whose final
+ * segment carries a file extension is a `public/` asset (or a raw `.md` twin),
+ * served at the site root and never localized.
+ */
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Decode a percent-encoded path for a route lookup; leave junk as-is. */
+const decodePercent = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/** Whether `path` (base-stripped) already sits under some locale's prefix. */
+const hasLocalePrefix = (path: string, i18n: LocaleRouting): boolean =>
+  i18n.locales.some((locale) => {
+    const prefix = localePrefix(locale.code, i18n);
+    return prefix !== "" && (path === prefix || path.startsWith(`${prefix}/`));
+  });
+
+/**
+ * Move a base-prefixed, fragment-less internal path into `locale` when that
+ * route is served, else return it unchanged. Idempotent: a path already under
+ * any configured locale prefix is never re-prefixed.
+ */
+export const localizeLinkPath = (
+  path: string,
+  options: LocalizeLinkOptions
+): string => {
+  const { basePath, i18n, locale, routes } = options;
+  if (localePrefix(locale, i18n) === "") {
+    return path;
+  }
+  const rest = normalizePath(stripBasePath(basePath, path));
+  if (hasLocalePrefix(rest, i18n)) {
+    return path;
+  }
+  const localized = withBasePath(basePath, localizeRoute(rest, locale, i18n));
+  // Routes are stored decoded; a browser-copied `/caf%C3%A9` must still find
+  // its translation, but the emitted href keeps the author's encoding.
+  return routes.has(localized) || routes.has(decodePercent(localized))
+    ? localized
+    : path;
+};
+
+export interface LocalizeHrefOptions extends LocalizeLinkOptions {
+  /** `deployment.base` (Astro's `BASE_URL`), layered over `basePath` in hrefs. */
+  deployBase: string;
+}
+
+/**
+ * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
+ * asset links pass through; a root-relative page link keeps its `?query` and
+ * `#fragment` and its `deployment.base` layer around the localized path.
+ */
+export const localizeHref = (
+  href: string,
+  options: LocalizeHrefOptions
+): string => {
+  if (!isInternalPath(href)) {
+    return href;
+  }
+  const suffixAt = href.search(/[#?]/u);
+  const path = suffixAt === -1 ? href : href.slice(0, suffixAt);
+  const suffix = suffixAt === -1 ? "" : href.slice(suffixAt);
+  if (ASSET_PATH.test(path)) {
+    return href;
+  }
+  const based = stripBasePath(options.deployBase, path);
+  const localized = localizeLinkPath(based, options);
+  if (localized === based) {
+    return href;
+  }
+  return `${withBasePath(options.deployBase, localized)}${suffix}`;
+};
+
+/** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */
+const ANCHOR_TAG = /<a\s[^>]*>/giu;
+/** The tag's `href` attribute, double- or single-quoted. */
+const HREF_ATTR = /(?<attr>\shref=)(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/iu;
+
+/**
+ * Rewrite every `<a href>` in rendered content HTML through `rewrite`. Code
+ * blocks are HTML-escaped (`&lt;a`), and island props live on
+ * `<astro-island>`, so neither is touched.
+ */
+export const localizeContentLinks = (
+  html: string,
+  rewrite: (href: string) => string
+): string =>
+  html.replace(ANCHOR_TAG, (tag) =>
+    tag.replace(HREF_ATTR, (_match, attr: string, dq?: string, sq?: string) => {
+      const quote = dq === undefined ? "'" : '"';
+      return `${attr}${quote}${rewrite(dq ?? sq ?? "")}${quote}`;
+    })
+  );
+
+/**
+ * The served route set for `blume:data`'s routes, built once per routes array
+ * (the virtual module is evaluated once, so every page render shares it).
+ */
+const routeSets = new WeakMap<readonly { path: string }[], Set<string>>();
+
+export const routeSetFor = (
+  routes: readonly { path: string }[]
+): Set<string> => {
+  const cached = routeSets.get(routes);
+  if (cached) {
+    return cached;
+  }
+  const built = new Set(routes.map((route) => route.path));
+  routeSets.set(routes, built);
+  return built;
+};

package/src/core/sources/normalize.ts

@@ -280,6 +280,8 @@ interface HeadingScanState {
   fence: FenceState;
   /** 1-based body line of the line being scanned. */
   line: number;
+  /** Where each heading in `headings` sits, index-aligned. */
+  sites: HeadingSite[];
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
   /** Body line of the first line in `paragraph`. */
@@ -399,23 +401,43 @@ const refDefinitionLabels = (lines: readonly string[]): Set<string> => {
  * regardless of TOC visibility. A heading that is nothing but markers keeps
  * them as literal text, mirroring the renderer.
  */
+/** A scanned heading plus whether its id came from an author pin. */
+interface ScannedHeading {
+  heading: Heading;
+  pinned: boolean;
+}
+
 const toHeading = (
   depth: number,
   raw: string,
   slugger: GithubSlugger,
   isRefDefined: (label: string) => boolean
-): Heading => {
+): ScannedHeading => {
   const unescaped = raw.replaceAll(ESCAPED_PUNCTUATION, "$<char>");
   const markers = parseHeadingMarkers(unescaped, isRefDefined);
   const text = markers.text.trim();
   if (text === "" && (markers.id !== undefined || markers.toc !== undefined)) {
-    return { depth, slug: slugger.slug(unescaped), text: unescaped };
+    return {
+      heading: { depth, slug: slugger.slug(unescaped), text: unescaped },
+      pinned: false,
+    };
   }
   if (markers.id !== undefined) {
     occupySlug(slugger, markers.id);
-    return { depth, slug: markers.id, text };
+    return { heading: { depth, slug: markers.id, text }, pinned: true };
   }
-  return { depth, slug: slugger.slug(text), text };
+  return { heading: { depth, slug: slugger.slug(text), text }, pinned: false };
+};
+
+/** Record a heading and where a trailing marker would be written for it. */
+const pushHeading = (
+  headings: Heading[],
+  state: HeadingScanState,
+  scanned: ScannedHeading,
+  line: number
+): void => {
+  headings.push(scanned.heading);
+  state.sites.push({ line, pinned: scanned.pinned });
 };
 
 /** Record a heading's unescaped trailing `{#id}` so `.mdx` pages can be warned. */
@@ -444,7 +466,12 @@ const scanContentLine = (
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
     const text = (atx.groups.text ?? "").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line
+    );
     noteCurlyMarker(text, state.line, state);
     state.paragraph = [];
     return;
@@ -455,7 +482,14 @@ const scanContentLine = (
     // a multi-line paragraph renders as one heading, soft breaks as spaces.
     const depth = setext.groups.marker?.startsWith("=") ? 1 : 2;
     const text = state.paragraph.join(" ").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    // A setext heading's markers trail its last text line, just above the
+    // underline — that is where a pin is appended.
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line - 1
+    );
     noteCurlyMarker(text, state.paragraphStart, state);
     state.paragraph = [];
     return;
@@ -515,6 +549,14 @@ const scanHeadingLine = (
   scanContentLine(line, state, slugger, headings, isRefDefined);
 };
 
+/** Where a heading's text ends in the scanned text, for appending a marker. */
+export interface HeadingSite {
+  /** 1-based line (of the text passed to `scanBody`) that any trailing marker ends. */
+  line: number;
+  /** True when the heading already pins its id with `[#id]`/`{#id}`. */
+  pinned: boolean;
+}
+
 /** Everything one walk over a body yields for the anchor index. */
 export interface BodyScan {
   /**
@@ -527,6 +569,8 @@ export interface BodyScan {
   /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
   curlyMarkers: CurlyMarker[];
   headings: Heading[];
+  /** Index-aligned with `headings`: where each one's markers would go. */
+  sites: HeadingSite[];
 }
 
 /**
@@ -546,6 +590,7 @@ export const scanBody = (body: string): BodyScan => {
     paragraphStart: 0,
     promptDepth: 0,
     promptTag: false,
+    sites: [],
   };
 
   const { lines, offset } = linesWithoutFrontMatter(body);
@@ -568,7 +613,12 @@ export const scanBody = (body: string): BodyScan => {
       anchors.add(id);
     }
   }
-  return { anchors: [...anchors], curlyMarkers: state.curlyMarkers, headings };
+  return {
+    anchors: [...anchors],
+    curlyMarkers: state.curlyMarkers,
+    headings,
+    sites: state.sites,
+  };
 };
 
 export const extractHeadings = (body: string): Heading[] =>