explico 0.1.1 → 0.3.0

package/src/reference/keyed-float-validate.ts

@@ -0,0 +1,207 @@
+/**
+ * Keyed-float validation for `<Table>`/`<Figure>`, run inside
+ * `compileManifest()` — the same three checks `equations-validate.ts` runs
+ * for equations, parameterized over the float kind so the logic exists once:
+ *
+ * - `<prefix>-invalid-key` (error): an `id` must match the key grammar.
+ * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
+ * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
+ *   `[[slug#<prefix>-key]]` points at a `<Table>`/`<Figure>` with that `id`.
+ * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ *
+ * `tables-validate.ts` and `figures-validate.ts` are thin wrappers over this
+ * so callers import `validateTables` / `validateFigures` with their own
+ * narrow diagnostic-code types, while `equations-validate.ts` stays
+ * untouched — equations predate this and keep their own dedicated path.
+ */
+
+import {
+  KEYED_FLOAT_KEY_PATTERN,
+  parseKeyedFloatRef,
+  scanKeyedJsxFloats,
+} from './keyed-jsx-floats.mjs';
+
+export interface KeyedFloatKind {
+  /** The MDX component tag, e.g. `Table` or `Figure`. */
+  readonly tagName: string;
+  /** The `[[<prefix>-key]]` reference prefix, e.g. `tab` or `fig`. */
+  readonly prefix: string;
+  /** Lowercase noun used in diagnostic messages, e.g. `table` or `figure`. */
+  readonly noun: string;
+}
+
+export interface KeyedFloatLabelRecord {
+  readonly key: string;
+  readonly number: string;
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly section: number;
+  readonly indexInSection: number;
+}
+
+export interface KeyedFloatRefRecord {
+  readonly key: string;
+  readonly lessonId: string;
+  /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+  readonly targetSlug?: string;
+}
+
+export interface KeyedFloatDiagnostic {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export interface KeyedFloatValidation {
+  /** Every keyed float, sorted by lesson then appearance. */
+  readonly labels: readonly KeyedFloatLabelRecord[];
+  /** `slug -> { key -> number }` — the render path's cross-page lookup table. */
+  readonly numbersBySlug: Record<string, Record<string, string>>;
+  readonly diagnostics: readonly KeyedFloatDiagnostic[];
+}
+
+export interface KeyedFloatLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+  /**
+   * The lesson's 1-based ordinal in the course. When set, floats are numbered
+   * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   */
+  readonly chapter?: number;
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+function bodyFloatRefs(
+  lesson: KeyedFloatLessonInput,
+  prefix: string,
+): KeyedFloatRefRecord[] {
+  const refs: KeyedFloatRefRecord[] = [];
+  for (const match of stripCode(lesson.body).matchAll(BRACKET_REF)) {
+    const parsed = parseKeyedFloatRef((match[1] ?? '').trim(), { prefix });
+    if (!parsed) continue;
+    refs.push({
+      key: parsed.key,
+      lessonId: lesson.lessonId,
+      ...(parsed.lesson ? { targetSlug: parsed.lesson } : {}),
+    });
+  }
+  return refs;
+}
+
+export function validateKeyedFloats(
+  lessons: readonly KeyedFloatLessonInput[],
+  kind: KeyedFloatKind,
+): KeyedFloatValidation {
+  const { tagName, prefix, noun } = kind;
+  const labels: KeyedFloatLabelRecord[] = [];
+  const diagnostics: KeyedFloatDiagnostic[] = [];
+  const numbersBySlug: Record<string, Record<string, string>> = {};
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const seen = new Set<string>();
+    const table: Record<string, string> = {};
+    for (const raw of scanKeyedJsxFloats(lesson.body, {
+      tagName,
+      chapter: lesson.chapter,
+    }) as {
+      key: string | null;
+      number: string;
+      section: number;
+      indexInSection: number;
+    }[]) {
+      if (raw.key == null) continue;
+      if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {
+        diagnostics.push({
+          code: `${prefix}-invalid-key`,
+          severity: 'error',
+          message: `${lesson.lessonId} has a <${tagName} id="${raw.key}"> whose id is not a valid key — expected lowercase letters, digits, and hyphens only.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: raw.key,
+        });
+        continue;
+      }
+      if (seen.has(raw.key)) {
+        diagnostics.push({
+          code: `${prefix}-duplicate-key`,
+          severity: 'error',
+          message: `${lesson.lessonId} has two <${tagName}> elements with id="${raw.key}"; an id is unique per lesson.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: raw.key,
+        });
+        continue;
+      }
+      seen.add(raw.key);
+      table[raw.key] = raw.number;
+      labels.push({
+        key: raw.key,
+        number: raw.number,
+        lessonId: lesson.lessonId,
+        slug: lesson.slug,
+        section: raw.section,
+        indexInSection: raw.indexInSection,
+      });
+    }
+    numbersBySlug[lesson.slug] = table;
+  }
+
+  const referenced = new Set<string>();
+  for (const lesson of lessons) {
+    const slug = lesson.slug;
+    for (const ref of bodyFloatRefs(lesson, prefix)) {
+      const targetSlug = ref.targetSlug ?? slug;
+      const number = numbersBySlug[targetSlug]?.[ref.key];
+      referenced.add(`${targetSlug}#${ref.key}`);
+      if (number === undefined) {
+        diagnostics.push({
+          code: `${prefix}-ref-resolves`,
+          severity: 'error',
+          message: ref.targetSlug
+            ? `${lesson.lessonId} references [[${ref.targetSlug}#${prefix}-${ref.key}]] but that lesson has no <${tagName} id="${ref.key}">`
+            : `${lesson.lessonId} references [[${prefix}-${ref.key}]] but no <${tagName}> on the page carries id="${ref.key}"`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: ref.key,
+        });
+      }
+    }
+  }
+
+  for (const label of labels) {
+    if (referenced.has(`${label.slug}#${label.key}`)) continue;
+    diagnostics.push({
+      code: `${prefix}-key-unused`,
+      severity: 'warning',
+      message: `${label.lessonId} has a ${noun} id="${label.key}" (${label.number}) but nothing references it with [[${prefix}-${label.key}]]`,
+      file: label.slug,
+      lessonId: label.lessonId,
+      key: label.key,
+    });
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? '') ||
+      (a.key ?? '').localeCompare(b.key ?? '') ||
+      a.message.localeCompare(b.message),
+  );
+
+  return { labels, numbersBySlug, diagnostics };
+}

package/src/reference/keyed-jsx-floats.mjs

@@ -0,0 +1,167 @@
+/**
+ * Keyed-float identity for a JSX-wrapped table or figure, shared between
+ * `<Table>` and `<Figure>` (Step F-tables-figures).
+ *
+ * This mirrors `equations.mjs`, but the key comes from a plain `id` prop on
+ * the wrapper component rather than a `\label{eq:key}` embedded in shared
+ * LaTeX source — a `<Table>`/`<Figure>` is purpose-built, so there is no
+ * ambiguity an embedded marker would need to resolve. An author writes the
+ * bare key (`id="kinematics-summary"`); the rendered DOM id and the `[[…]]`
+ * reference prefix are computed the same way `\label{eq:key}` becomes
+ * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`.
+ *
+ * Only top-level occurrences count, exactly like `collectDisplayEquations`:
+ * a `<Table>` nested inside a `<CompactExample>` (or any other component) is
+ * illustrative, not part of the lesson's official sequence, so both the
+ * mdast walker and the raw-text scanner only look at the document's direct
+ * top-level blocks.
+ *
+ * `scanKeyedJsxFloats` (raw Markdown, for the manifest builder) and
+ * `collectKeyedJsxFloats` (mdast, for `remark-notation.mjs`) MUST agree —
+ * `tests/notation/keyed-floats.test.ts` checks that, the same contract
+ * `equations.test.ts` holds equations to.
+ */
+
+import { stripFencedCode, stripJsxComponents } from './equations.mjs';
+
+/** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
+export const KEYED_FLOAT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The visible number for the `index`-th float of one kind under `section`. */
+function floatNumber(section, index) {
+  return section > 0 ? `${section}.${index}` : String(index);
+}
+
+/**
+ * The visible number for one float. With `chapter` (the lesson's course
+ * ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings are
+ * ignored; without it, the legacy `##`-section scheme. Mirrors
+ * `displayEquationNumber` in `equations.mjs`.
+ */
+function keyedFloatNumber({ chapter, section, indexInSection, indexInLesson }) {
+  return chapter == null
+    ? floatNumber(section, indexInSection)
+    : `${chapter}.${indexInLesson}`;
+}
+
+/** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
+export function keyedFloatAnchorId({ key, number, prefix }) {
+  return key ? `${prefix}-${key}` : `${prefix}-${String(number).replace(/\./g, '-')}`;
+}
+
+/**
+ * A `[[ … ]]` payload that targets this kind of float: `<prefix>-<key>` on
+ * the current page, or `<lesson-slug>#<prefix>-<key>` across pages.
+ */
+export function parseKeyedFloatRef(raw, { prefix }) {
+  const pattern = new RegExp(
+    `^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?${prefix}-([a-z0-9]+(?:-[a-z0-9]+)*)$`,
+  );
+  const match = pattern.exec(String(raw).trim());
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/** The `id="…"` attribute value of a JSX opening tag's attribute source. */
+function readIdAttribute(attributesSource) {
+  const match = /\bid\s*=\s*(["'])([^"']*)\1/.exec(attributesSource);
+  return match ? match[2] : undefined;
+}
+
+/**
+ * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
+ * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
+ * With `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹n›`,
+ * `n` sequential over the whole lesson; without it, `##` headings advance a
+ * section counter. Other JSX components' bodies are blanked first so a
+ * `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like text
+ * inside an unrelated component) is never counted.
+ */
+export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
+  const text = stripJsxComponents(stripFencedCode(markdown), tagName);
+  const tokens = [];
+  const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
+  const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
+  for (const match of text.matchAll(heading)) {
+    tokens.push({ kind: 'section', index: match.index });
+  }
+  for (const match of text.matchAll(opening)) {
+    const key = readIdAttribute(match[1] ?? '');
+    tokens.push({ kind: 'float', index: match.index, key: key ?? null });
+  }
+  tokens.sort((a, b) => a.index - b.index);
+
+  const labels = [];
+  let section = 0;
+  let indexInSection = 0;
+  let indexInLesson = 0;
+  for (const token of tokens) {
+    if (token.kind === 'section') {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    indexInSection += 1;
+    indexInLesson += 1;
+    labels.push({
+      key: token.key,
+      number: keyedFloatNumber({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
+      section,
+      indexInSection,
+    });
+  }
+  return labels;
+}
+
+/**
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
+ * children in document order, advancing the section counter on every
+ * depth-2 heading and emitting a record for every `mdxJsxFlowElement` named
+ * `tagName` — keyed or not, exactly like `collectDisplayEquations`. `chapter`
+ * is threaded the same way as in `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
+  const floats = [];
+  let section = 0;
+  let indexInSection = 0;
+  let indexInLesson = 0;
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
+      indexInSection += 1;
+      indexInLesson += 1;
+      const idAttribute = (node.attributes ?? []).find(
+        (attribute) =>
+          attribute?.type === 'mdxJsxAttribute' && attribute.name === 'id',
+      );
+      const key =
+        typeof idAttribute?.value === 'string' ? idAttribute.value : undefined;
+      floats.push({
+        key: key ?? null,
+        number: keyedFloatNumber({
+          chapter,
+          section,
+          indexInSection,
+          indexInLesson,
+        }),
+        section,
+        indexInSection,
+        node,
+      });
+    }
+  }
+  return floats;
+}
+

package/src/reference/math-glyphs.mjs

@@ -828,3 +828,95 @@ export function resolveMathGlyphs(latex, definitions) {
     unresolved: unresolvedIdentifiers(latex, identifiers, bindings),
   };
 }
+
+// --- named operators ------------------------------------------------
+
+/**
+ * Every named operator in one KaTeX expression: a built-in `op` node
+ * (`\exp`, `\int`, `\sum`, …) or an author-declared `\operatorname{…}` /
+ * `\mathop{…}` (`Var`, `Cov`, …). The `name` is the KaTeX command without its
+ * backslash for a built-in, and the verbatim body for a declared one — the
+ * form `BASE_OPERATORS` and `course.config.ts` `operators` are keyed by.
+ *
+ * Pure read: unlike `resolveMathGlyphs`, nothing here rewrites the source.
+ * Used by the `operator-explained` consistency check (rule N8); the glyph
+ * resolver still skips operator bodies whole.
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
+ */
+export function collectOperators(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return [];
+
+  let tree;
+  try {
+    tree = parseMath(latex, 'operator scan');
+  } catch (error) {
+    // A span that will not parse is the math gate's problem, not this check's.
+    // A KaTeX version-pin failure is nobody's to swallow — let it through.
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return [];
+    }
+    throw error;
+  }
+
+  const seen = new Set();
+  const operators = [];
+  const add = (name, source) => {
+    const trimmed = typeof name === 'string' ? name.trim() : '';
+    if (trimmed === '') return;
+    const identity = `${source}:${trimmed}`;
+    if (seen.has(identity)) return;
+    seen.add(identity);
+    operators.push({ name: trimmed, source });
+  };
+
+  // The declared-operator name is its letters with any internal spacing
+  // dropped, so `\operatorname{arg\,max}` keys as `argmax` — `fontBodyText`
+  // alone bails on the `\,`.
+  const declaredName = (body) => {
+    const direct = fontBodyText(body);
+    if (typeof direct === 'string') return direct;
+    const letters = [];
+    const gather = (value) => {
+      if (Array.isArray(value)) {
+        value.forEach(gather);
+        return;
+      }
+      if (!isNode(value)) return;
+      if (value.type === 'mathord' || value.type === 'textord') {
+        letters.push(value.text ?? '');
+      }
+      if (value.type === 'ordgroup') gather(value.body);
+    };
+    gather(body);
+    return letters.join('');
+  };
+
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child);
+      return;
+    }
+    if (!isNode(value)) return;
+
+    if (value.type === 'operatorname') {
+      add(declaredName(value.body), 'operatorname');
+    } else if (value.type === 'op') {
+      if (typeof value.name === 'string' && value.name.length > 0) {
+        add(value.name.replace(/^\\/, ''), 'named');
+      } else if (value.body !== undefined) {
+        // `\mathop{Foo}` — a hand-rolled operator with no command name.
+        add(declaredName(value.body), 'operatorname');
+      }
+    }
+
+    for (const key of Object.keys(value)) {
+      if (key === 'loc') continue;
+      visit(value[key]);
+    }
+  };
+
+  visit(tree);
+  return operators;
+}

package/src/reference/registry.ts

@@ -58,6 +58,8 @@ export function buildNotationRegistry(
   );
   const availableDefinitionIds = new Set(definitions.keys());
 
+  validateGlossKeys(definitions, diagnostics);
+
   // `notation.uses` is retired (D1 decision): a lesson pulls a shared key into
   // scope by referencing it (`[[key]]`/`\explain`), and every reference resolves
   // directly against page-local then shared definitions.
@@ -411,6 +413,43 @@ function normalizeLocalDefinition(
   };
 }
 
+/**
+ * A gloss key is derived as `<card key>.<slug(name)>`, so it is entry-scoped
+ * and cannot clash with another card's glosses. It can still collide with a
+ * **card** whose own key happens to take that shape — and a colliding key
+ * would make the same string mean two things in the flat glyph table, which
+ * is exactly what the semantic-key design exists to prevent. Tier 1.
+ *
+ * This is also the promotion boundary: promoting a gloss means deleting the
+ * gloss line *and* adding the card. Leaving both in place fails here rather
+ * than resolving to whichever the table saw first.
+ */
+function validateGlossKeys(
+  definitions: ReadonlyMap<string, DefinitionCandidate>,
+  diagnostics: NotationDiagnostic[],
+): void {
+  const cardKeys = new Set(
+    [...definitions.values()].map((candidate) => candidate.input.key),
+  );
+
+  for (const candidate of definitions.values()) {
+    for (const gloss of candidate.input.glosses) {
+      if (!cardKeys.has(gloss.key)) continue;
+      diagnostics.push(
+        diagnostic({
+          code: 'gloss-collides-with-card',
+          message: `${candidate.id} glosses ${JSON.stringify(gloss.label)} as ${gloss.key}, which is also a notation card; delete the gloss or rename it`,
+          key: gloss.key,
+          lessonId:
+            candidate.kind === 'local' ? candidate.lesson.lessonId : undefined,
+          definitionId: candidate.id,
+          source: candidate.input.source,
+        }),
+      );
+    }
+  }
+}
+
 function validateReferenceKey(
   reference: NotationReferenceInput,
   owner: DefinitionCandidate,
@@ -503,6 +542,7 @@ function toDefinitionRecord(
       status: input.status,
       aiAssisted: input.aiAssisted,
       body: input.body,
+      glosses: input.glosses,
       source: input.source,
       resolvedReferences: candidate.resolvedReferences,
       ...(input.formula === undefined ? {} : { formula: input.formula }),
@@ -525,6 +565,7 @@ function toDefinitionRecord(
     seeAlso: input.seeAlso,
     alignment: input.alignment,
     status: candidate.lesson.status,
+    glosses: input.glosses,
     source: input.source,
     resolvedReferences: candidate.resolvedReferences,
     ...(input.formula === undefined ? {} : { formula: input.formula }),
@@ -570,6 +611,7 @@ function definitionFingerprint(candidate: DefinitionCandidate): string {
       status: input.status,
       aiAssisted: input.aiAssisted,
       body: normalizeText(input.body),
+      glosses: input.glosses,
       references,
     });
   }
@@ -586,6 +628,7 @@ function definitionFingerprint(candidate: DefinitionCandidate): string {
     sources: [...input.sources].sort(),
     seeAlso: [...input.seeAlso].sort(),
     alignment,
+    glosses: input.glosses,
     references,
   });
 }

package/src/reference/rehype-heading-anchors.mjs

@@ -0,0 +1,144 @@
+/**
+ * Deep-linkable content headings (Step F3).
+ *
+ * The lesson pipeline uses a custom Markdown `processor` (see `astro.config.mjs`),
+ * which bypasses Starlight's own heading-link rehype pass. This plugin restores
+ * it with the *same* markup Starlight emits, so its bundled `anchor-links.css`
+ * (shipped globally because `markdown.headingLinks` defaults on) styles it for
+ * free — including the hover/focus reveal of an otherwise invisible anchor:
+ *
+ *   <div class="sl-heading-wrapper level-h2">
+ *     <h2 id="slug">Heading</h2>
+ *     <a class="sl-anchor-link" href="#slug"> <icon> <sr-only label> </a>
+ *   </div>
+ *
+ * The `:target` flash, sticky-header scroll offset, and the JS niceties
+ * (re-trigger on repeat activation, smooth scroll, `history.pushState`, brief
+ * section highlight) live in `global.css` + `HeadingAnchorEnhancer.astro`, the
+ * same split the keyed-equation feature uses.
+ *
+ * `rehypeHeadingIds` from `@astrojs/markdown-remark` normally runs *after* the
+ * user rehype plugins, so heading `id`s do not exist yet when this runs. It is
+ * idempotent (only assigns a missing `id`, and rebuilds `file.data.astro.headings`
+ * from an unchanged document order), so this plugin runs it first and Astro's
+ * later pass becomes a no-op for these headings.
+ */
+
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+
+const HEADING_TAG = /^h([1-6])$/;
+
+// Starlight's `link-alt` icon (`components-internals/Icons.ts`), the same glyph
+// its own `rehypeAutolinkHeadings` uses.
+const LINK_ICON_PATH =
+  'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42';
+
+function headingText(node) {
+  let text = '';
+  const walk = (current) => {
+    if (!current || typeof current !== 'object') return;
+    if (current.type === 'text' || current.type === 'raw') {
+      text += String(current.value ?? '');
+      return;
+    }
+    if (Array.isArray(current.children)) current.children.forEach(walk);
+  };
+  walk(node);
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function isHeadingWrapper(node) {
+  const className = node?.properties?.className;
+  return (
+    node?.type === 'element' &&
+    Array.isArray(className) &&
+    className.includes('sl-heading-wrapper')
+  );
+}
+
+function anchorLink(id, label) {
+  return {
+    type: 'element',
+    tagName: 'a',
+    properties: { className: ['sl-anchor-link'], href: `#${id}` },
+    children: [
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { ariaHidden: 'true', className: ['sl-anchor-icon'] },
+        children: [
+          {
+            type: 'element',
+            tagName: 'svg',
+            properties: {
+              width: 16,
+              height: 16,
+              viewBox: '0 0 24 24',
+              fill: 'currentColor',
+            },
+            children: [
+              {
+                type: 'element',
+                tagName: 'path',
+                properties: { d: LINK_ICON_PATH },
+                children: [],
+              },
+            ],
+          },
+        ],
+      },
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { className: ['sr-only'], 'data-pagefind-ignore': 'true' },
+        children: [{ type: 'text', value: label }],
+      },
+    ],
+  };
+}
+
+export default function rehypeHeadingAnchors() {
+  const assignHeadingIds = rehypeHeadingIds();
+
+  return function transform(tree, file) {
+    assignHeadingIds(tree, file);
+
+    const walk = (node) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      if (isHeadingWrapper(node)) return; // already processed
+
+      for (let index = 0; index < node.children.length; index++) {
+        const child = node.children[index];
+        const tag =
+          child?.type === 'element' && typeof child.tagName === 'string'
+            ? HEADING_TAG.exec(child.tagName)
+            : null;
+
+        if (
+          tag &&
+          tag[1] !== '1' &&
+          typeof child.properties?.id === 'string' &&
+          child.properties.id.length > 0
+        ) {
+          const id = child.properties.id;
+          const label = `Section titled “${headingText(child)}”`;
+          node.children[index] = {
+            type: 'element',
+            tagName: 'div',
+            properties: {
+              className: ['sl-heading-wrapper', `level-${child.tagName}`],
+            },
+            children: [child, anchorLink(id, label)],
+          };
+          continue; // the heading is a leaf for our purposes
+        }
+
+        walk(child);
+      }
+    };
+
+    walk(tree);
+  };
+}