explico 0.3.0 → 0.5.0

package/dist/reference/rehype-table-header-labels.mjs

@@ -0,0 +1,152 @@
+/**
+ * Auto-generated accessible name for a table header cell that is 100%
+ * KaTeX-rendered math (N9: a unit is typeset in `$…$` too, so a header like
+ * `$t\ \text{(s)}$` has no plain DOM text at all). axe-core's
+ * `empty-table-header` rule does not read `<math>` content when computing a
+ * `<th>`'s accessible name, so a sighted or MathML-aware reader sees the
+ * symbol fine while a screen reader hears nothing.
+ *
+ * This was first tried with a plain `aria-label` — wrong, confirmed by
+ * reading axe-core's own rule (`node_modules/axe-core/axe.js`): unlike most
+ * name-checking rules, `empty-table-header` only runs the `has-visible-text`
+ * check (`any: ['has-visible-text']`, no `aria-label`/`aria-labelledby`
+ * alternative in that list), which calls `subtreeText` — it wants real
+ * *content*, not just an accessible name. So this instead inserts a real
+ * `<span class="sr-only">` text node as a child of the `<th>`, using
+ * Starlight's own `.sr-only` utility (`clip: rect(0,0,0,0)`, not
+ * `display:none` — invisible to sighted readers, present in the
+ * accessibility tree, satisfying `subtreeText` the same way any other
+ * visually-hidden accessible label on this site already does, e.g.
+ * `rehype-heading-anchors.mjs`'s anchor labels).
+ *
+ * The label text is composed straight from the notation metadata already
+ * authored for the bound symbol(s): every `\explain{key}{…}` in the header's
+ * LaTeX source names a key, and `remark-notation.mjs` has already resolved
+ * every key used anywhere on the page into `file.data.notationResolved`
+ * (`{key: {label, units, ...}}`) by the time this plugin runs — nothing here
+ * re-derives notation scope.
+ *
+ * Runs after `rehypeKatex` (needs its rendered spans, specifically the
+ * `<annotation encoding="application/x-tex">` KaTeX always embeds with the
+ * exact source it was given, `\explain{}` calls included — whether the
+ * author typed them or `remark-notation.mjs` auto-inserted them).
+ */
+
+// Mirrors `gloss.ts`'s exported `formulaExplainKeys` regex. Not imported:
+// this file is a plain `.mjs` reference module, copied verbatim into `dist/`
+// by `scripts/copy-assets.mjs`, never touched by the tsup build that
+// compiles `gloss.ts` — no existing `.mjs` in this directory imports a `.ts`
+// sibling's compiled output, so this one doesn't start.
+const EXPLAIN_KEY = /\\explain\s*\{\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\}/g;
+
+function isKatexRoot(node) {
+  return (
+    node.type === 'element' &&
+    node.tagName === 'span' &&
+    Array.isArray(node.properties?.className) &&
+    node.properties.className.includes('katex')
+  );
+}
+
+/**
+ * Whether `node` already has real, visible text a screen reader would read
+ * as this `<th>`'s accessible name — anything outside a `.katex` subtree. A
+ * `.katex` span is treated as opaque here on purpose: its `.katex-mathml`
+ * child holds the MathML `<math>` axe won't read, and its `.katex-html`
+ * child is `aria-hidden="true"`, so neither counts either way — a header
+ * that already carries a descriptive word (`Launch speed $\text{(m/s)}$`)
+ * sees that word as a normal text-node sibling and is left alone.
+ */
+export function hasVisibleText(node) {
+  if (!node || typeof node !== 'object') return false;
+  if (node.type === 'text') {
+    return typeof node.value === 'string' && node.value.trim().length > 0;
+  }
+  if (node.type !== 'element') return false;
+  if (isKatexRoot(node)) return false;
+  return (node.children ?? []).some(hasVisibleText);
+}
+
+/** Every `application/x-tex` annotation's raw source inside `node`, in order. */
+export function collectMathSource(node, out = []) {
+  if (!node || typeof node !== 'object') return out;
+  if (
+    node.type === 'element' &&
+    node.tagName === 'annotation' &&
+    node.properties?.encoding === 'application/x-tex'
+  ) {
+    out.push(
+      (node.children ?? [])
+        .filter((child) => child.type === 'text')
+        .map((child) => child.value)
+        .join(''),
+    );
+  }
+  for (const child of node.children ?? []) collectMathSource(child, out);
+  return out;
+}
+
+/** Every `\explain{key}{…}` key named across one or more LaTeX sources, in order, deduped. */
+export function explainKeysIn(sources) {
+  const seen = new Set();
+  const keys = [];
+  for (const source of sources) {
+    EXPLAIN_KEY.lastIndex = 0;
+    let match;
+    while ((match = EXPLAIN_KEY.exec(source))) {
+      const key = match[1];
+      if (seen.has(key)) continue;
+      seen.add(key);
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * `"Label (units)"` per key, joined with `" / "` for a header that binds
+ * more than one (a ratio like `\mathrm{KE}/m`, explain-wrapped on both
+ * sides). `undefined` when nothing resolved, so the caller leaves the
+ * header exactly as it was rather than inserting an empty/placeholder label.
+ */
+export function composeHeaderLabel(keys, notationResolved) {
+  const parts = keys
+    .map((key) => notationResolved[key])
+    .filter((entry) => entry && typeof entry.label === 'string')
+    .map((entry) => (entry.units ? `${entry.label} (${entry.units})` : entry.label));
+  return parts.length > 0 ? parts.join(' / ') : undefined;
+}
+
+/** A visually-hidden text node — see the module doc for why this, not `aria-label`. */
+function srOnlySpan(label) {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: { className: ['sr-only'] },
+    children: [{ type: 'text', value: label }],
+  };
+}
+
+function labelTableHeaders(node, notationResolved) {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.type === 'element' && node.tagName === 'th' && !hasVisibleText(node)) {
+    const keys = explainKeysIn(collectMathSource(node));
+    const label = composeHeaderLabel(keys, notationResolved);
+    if (label) {
+      node.children = [srOnlySpan(label), ...(node.children ?? [])];
+    }
+  }
+
+  for (const child of node.children ?? []) labelTableHeaders(child, notationResolved);
+}
+
+/**
+ * See the module doc above. No plugin options — everything it needs is
+ * already on `file.data.notationResolved` by the time it runs.
+ */
+export default function rehypeTableHeaderLabels() {
+  return function addTableHeaderLabels(tree, file) {
+    labelTableHeaders(tree, file?.data?.notationResolved ?? {});
+  };
+}

package/dist/reference/remark-abbreviations.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @param {{ abbreviations?: readonly object[] | (() => readonly object[]), base?: string }} [options]
+ */
+export default function remarkAbbreviations(options?: {
+    abbreviations?: readonly object[] | (() => readonly object[]);
+    base?: string;
+}): (tree: any) => void;

package/dist/reference/remark-abbreviations.mjs

@@ -0,0 +1,174 @@
+/**
+ * Remark adapter for the abbreviations table (rule N14).
+ *
+ * Unlike citations, this has no authoring syntax of its own — N14 already
+ * requires every abbreviation-shaped word in prose to either be universal or
+ * carry a `content/abbreviations/*.md` entry, so the literal written form
+ * (`abbr`, or one of its `aliases`) is itself the trigger. This plugin scans
+ * ordinary prose for that literal text and wraps the **first** occurrence per
+ * document in a real link (`/glossary/#abbr-<key>`, so it still navigates
+ * with no JS) carrying the `data-abbr-key` an island script reads to render a
+ * hover/click card, exactly the way `remarkCitation` wraps `[@id]` markers.
+ * Later occurrences of the same term on the same page stay plain text, so a
+ * common short word isn't turned into a link everywhere it appears.
+ *
+ * Matches only ever come from the known table by construction, so unlike
+ * citation's `[@id]` there is no "unknown id" failure path here.
+ *
+ * `abbreviations` is either the compiled manifest's `abbreviations` array
+ * (`{key, abbr, expansion, aliases, domain?}` records) or a loader that
+ * returns it, supplied by the Astro config — same shape citation's `sources`
+ * option accepts, re-evaluated for every document transform.
+ */
+
+const PROSE_SKIP_TYPES = new Set([
+  'code',
+  'definition',
+  'html',
+  'image',
+  'imageReference',
+  'inlineCode',
+  'link',
+  'linkReference',
+  'math',
+  'mdxFlowExpression',
+  'mdxTextExpression',
+  'mdxjsEsm',
+  'toml',
+  'yaml',
+]);
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// A dotted form (`w.r.t.`) ends in `.`, where a trailing `\b` is unreliable —
+// the same reason `gate-abbreviations.ts`'s own `DOTTED_ABBR` regex has no
+// trailing boundary either. Only add the trailing boundary when the form
+// actually ends in a word character.
+function endsWithWordChar(text) {
+  return /\w$/.test(text);
+}
+
+/**
+ * One case-sensitive alternation regex from every entry's `abbr` + `aliases`,
+ * longest-first so a shorter alias that is a prefix of a longer one (`e.g`
+ * vs. `e.g.`) never wins the match. Also returns the exact-text → key lookup
+ * the matched alternative resolves to.
+ */
+function buildMatcher(entries) {
+  const alternatives = [];
+  const keyByMatch = new Map();
+
+  for (const entry of entries) {
+    const key = entry?.key;
+    if (typeof key !== 'string' || key.length === 0) continue;
+
+    const forms = [entry.abbr, ...(Array.isArray(entry.aliases) ? entry.aliases : [])];
+    for (const form of forms) {
+      if (typeof form !== 'string' || form.length === 0) continue;
+      if (keyByMatch.has(form)) continue;
+      keyByMatch.set(form, key);
+      alternatives.push(form);
+    }
+  }
+
+  if (alternatives.length === 0) return { regex: null, keyByMatch };
+
+  alternatives.sort((a, b) => b.length - a.length);
+  const pattern = alternatives
+    .map(
+      (form) =>
+        `\\b${escapeRegExp(form)}${endsWithWordChar(form) ? '\\b' : ''}`,
+    )
+    .join('|');
+
+  return { regex: new RegExp(pattern, 'g'), keyByMatch };
+}
+
+function hrefFor(key, base) {
+  return `${base.replace(/\/$/, '')}/glossary/#abbr-${key}`;
+}
+
+function termNode(key, matchedText, base) {
+  return {
+    type: 'link',
+    url: hrefFor(key, base),
+    children: [{ type: 'text', value: matchedText }],
+    data: {
+      hProperties: {
+        className: ['abbreviation-term'],
+        'data-abbr-key': key,
+      },
+    },
+  };
+}
+
+/**
+ * @param {{ abbreviations?: readonly object[] | (() => readonly object[]), base?: string }} [options]
+ */
+export default function remarkAbbreviations(options = {}) {
+  return function transform(tree) {
+    const suppliedAbbreviations =
+      typeof options.abbreviations === 'function'
+        ? options.abbreviations()
+        : (options.abbreviations ?? []);
+    const base = options.base ?? '';
+
+    const { regex, keyByMatch } = buildMatcher(suppliedAbbreviations);
+    if (!regex) return;
+
+    // Fresh per file, same lifetime as citation's own `pairs` Map: only the
+    // first occurrence of a given key on this page gets wrapped.
+    const usedKeys = new Set();
+
+    const replaceText = (value) => {
+      regex.lastIndex = 0;
+      const output = [];
+      let cursor = 0;
+      let changed = false;
+      let match;
+
+      while ((match = regex.exec(value))) {
+        const key = keyByMatch.get(match[0]);
+        if (!key || usedKeys.has(key)) continue;
+
+        if (match.index > cursor) {
+          output.push({ type: 'text', value: value.slice(cursor, match.index) });
+        }
+        output.push(termNode(key, match[0], base));
+        usedKeys.add(key);
+        changed = true;
+        cursor = match.index + match[0].length;
+      }
+
+      if (!changed) return undefined;
+      if (cursor < value.length) {
+        output.push({ type: 'text', value: value.slice(cursor) });
+      }
+      return output;
+    };
+
+    const visit = (node, skipped) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      if (skipped || PROSE_SKIP_TYPES.has(node.type)) return;
+
+      for (let index = 0; index < node.children.length; index++) {
+        const child = node.children[index];
+        if (child?.type === 'text') {
+          const replacement = replaceText(String(child.value ?? ''));
+          if (replacement) {
+            node.children.splice(index, 1, ...replacement);
+            index += replacement.length - 1;
+          }
+          continue;
+        }
+        visit(child, false);
+      }
+    };
+
+    visit(tree, false);
+  };
+}

package/dist/reference/remark-memo.d.mts

@@ -0,0 +1,16 @@
+/** A same-page memo reference payload, e.g. `memo-full-derivation`. */
+export function parseMemoRef(raw: any): {
+    key: string;
+} | undefined;
+/**
+ * Turn otherwise-unparseable inline/block memo syntax into ordinary MDX while
+ * retaining author attributes and body source verbatim.
+ */
+export function preprocessMemos(source: any): string;
+/**
+ * Number memo blocks from one on every page and resolve same-page
+ * `[[memo-id]]` references. Numbering is intentionally page-local.
+ *
+ * @this {any}
+ */
+export default function remarkMemo(this: any): (tree: any, file: any) => void;

package/dist/reference/remark-memo.mjs

@@ -0,0 +1,339 @@
+/**
+ * Remark adapter for substantial, referenceable memo disclosures.
+ *
+ * Authors place a memo as a normal flow block and cite it from earlier prose:
+ *
+ *   The complete calculation is recorded in [[memo-derivation]].
+ *
+ *   <Memo id="derivation" title="Derivation" description="The algebra.">
+ *   Several paragraphs, equations, tables, or figures.
+ *
+ *   </Memo>
+ *
+ * MDX normally rejects this before remark transforms run: an inline JSX node
+ * cannot contain block Markdown. The attacher therefore wraps remark-parse's
+ * parser and tags each memo before parsing. Legacy inline placements are still
+ * split into a temporary marker plus a flow `<Memo>`; standalone blocks do not
+ * emit a marker at their authored location. The transformer resolves every
+ * `[[memo-id]]` to a numbered link and injects the memo's per-page number and
+ * anchor into the real component. Temporary attributes never reach output.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { KEYED_FLOAT_KEY_PATTERN } from './keyed-jsx-floats.mjs';
+import {
+  injectMdxStringAttributes,
+  mdxAttributesNamed,
+  removeMdxAttribute,
+} from './mdx-attributes.mjs';
+
+const BLOCK_ATTRIBUTE = 'data-explico-memo-block';
+const MARKER_URL_PREFIX = '#explico-internal-memo-marker-';
+const MEMO_REFERENCE_PATTERN =
+  /\[\[\s*memo-([a-z0-9]+(?:-[a-z0-9]+)*)\s*\]\]/g;
+
+/** A same-page memo reference payload, e.g. `memo-full-derivation`. */
+export function parseMemoRef(raw) {
+  const match = /^memo-([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(String(raw).trim());
+  return match ? { key: match[1] } : undefined;
+}
+
+// An MDX attribute may be a quoted string, a brace expression (including one
+// level of nested braces), or ordinary unquoted source. Required memo props are
+// validated as literal strings after parsing; this breadth is for preserving
+// unrelated props such as `rememberState={condition}` intact.
+const ATTRIBUTE_SOURCE = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const MEMO_PAIR = new RegExp(
+  String.raw`<Memo\b(${ATTRIBUTE_SOURCE})>([\s\S]*?)<\/Memo\s*>`,
+  'g',
+);
+
+function maskBlock(block) {
+  return block.replace(/[^\n]/g, ' ');
+}
+
+/** Protect examples/comments whose literal `<Memo>` text is not authoring. */
+function searchableMemoSource(source) {
+  return stripFencedCode(source)
+    .replace(/<!--[\s\S]*?-->/g, maskBlock)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, maskBlock);
+}
+
+function isStandaloneBlock(source, start, end) {
+  const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+  const followingNewline = source.indexOf('\n', end);
+  const lineEnd = followingNewline === -1 ? source.length : followingNewline;
+  return (
+    source.slice(lineStart, start).trim().length === 0 &&
+    source.slice(end, lineEnd).trim().length === 0
+  );
+}
+
+/**
+ * Turn otherwise-unparseable inline/block memo syntax into ordinary MDX while
+ * retaining author attributes and body source verbatim.
+ */
+export function preprocessMemos(source) {
+  const input = String(source);
+  const searchable = searchableMemoSource(input);
+  const matches = [...searchable.matchAll(MEMO_PAIR)];
+  if (matches.length === 0) return input;
+
+  let cursor = 0;
+  let output = '';
+  for (let index = 0; index < matches.length; index++) {
+    const match = matches[index];
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+
+    const whole = match[0];
+    const maskedAttributes = match[1] ?? '';
+    const openLength = '<Memo'.length + maskedAttributes.length + 1;
+    const closeOffset = whole.lastIndexOf('</Memo');
+    const bodyStart = start + openLength;
+    const closeStart = start + closeOffset;
+    const attributes = input.slice(start + '<Memo'.length, bodyStart - 1);
+    const body = input.slice(bodyStart, closeStart);
+    const searchableBody = searchable.slice(bodyStart, closeStart);
+    if (/<Memo\b/.test(searchableBody)) {
+      throw new Error('A <Memo> cannot be nested inside another <Memo>.');
+    }
+
+    const closingTag = input.slice(closeStart, start + whole.length);
+    const end = start + whole.length;
+    output += input.slice(cursor, start);
+    if (isStandaloneBlock(input, start, end)) {
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}`;
+    } else {
+      output += `[memo](${MARKER_URL_PREFIX}${index})\n\n`;
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}\n\n`;
+    }
+    cursor = end;
+  }
+  output += input.slice(cursor);
+  return output;
+}
+
+function fail(file, message, node) {
+  if (typeof file?.fail === 'function') file.fail(message, node);
+  const location = file?.path ? `${file.path}: ` : '';
+  throw new Error(`${location}${message}`);
+}
+
+function literalAttribute(node, name, file, { optional = false } = {}) {
+  const matches = mdxAttributesNamed(node, name);
+  if (matches.length > 1) {
+    fail(file, `<Memo> has more than one \`${name}\` prop.`, node);
+  }
+  if (matches.length === 0) {
+    if (optional) return undefined;
+    fail(file, `<Memo> requires a non-empty literal \`${name}\` prop.`, node);
+  }
+  const value = matches[0]?.value;
+  if (typeof value !== 'string' || !value.trim()) {
+    const qualifier = optional ? 'when provided' : '';
+    fail(
+      file,
+      `<Memo> \`${name}\` must be a non-empty literal string${qualifier ? ` ${qualifier}` : ''}; expressions are not supported for build-time memo markers.`,
+      matches[0] ?? node,
+    );
+  }
+  return value;
+}
+
+function markerNode(memo) {
+  const link = {
+    type: 'link',
+    url: `#${memo.anchorId}`,
+    children: [
+      {
+        type: 'text',
+        value: memo.label ?? `[${memo.number}]`,
+      },
+    ],
+    data: {
+      hProperties: {
+        className: ['memo-marker'],
+        'data-memo-key': memo.id,
+        'data-memo-number': memo.number,
+        'aria-controls': memo.anchorId,
+        'aria-expanded': 'false',
+        'aria-label': memo.label
+          ? `${memo.label}: ${memo.title}`
+          : `Memo ${memo.number}: ${memo.title}`,
+        title: memo.title,
+      },
+    },
+  };
+  if (memo.label) return link;
+  return {
+    type: 'emphasis',
+    children: [link],
+    data: {
+      hName: 'sup',
+      hProperties: { className: ['memo-marker-wrap'] },
+    },
+  };
+}
+
+function visit(node, callback, parent) {
+  if (!node || typeof node !== 'object') return;
+  callback(node, parent);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) visit(child, callback, node);
+}
+
+function rewriteMemoReferences(node, memos, file) {
+  if (!node || typeof node !== 'object' || !Array.isArray(node.children)) return;
+  if (node.type === 'link' || node.type === 'linkReference') return;
+
+  for (let index = 0; index < node.children.length; index++) {
+    const child = node.children[index];
+    if (child?.type !== 'text' || typeof child.value !== 'string') {
+      rewriteMemoReferences(child, memos, file);
+      continue;
+    }
+
+    const replacements = [];
+    let cursor = 0;
+    let match;
+    MEMO_REFERENCE_PATTERN.lastIndex = 0;
+    while ((match = MEMO_REFERENCE_PATTERN.exec(child.value))) {
+      if (match.index > cursor) {
+        replacements.push({ type: 'text', value: child.value.slice(cursor, match.index) });
+      }
+      const memo = memos.get(match[1]);
+      if (!memo) {
+        fail(
+          file,
+          `Unknown memo reference [[memo-${match[1]}]]: no <Memo> on this page carries id="${match[1]}".`,
+          child,
+        );
+      }
+      replacements.push(markerNode({ ...memo, label: undefined }));
+      cursor = match.index + match[0].length;
+    }
+    if (replacements.length === 0) continue;
+    if (cursor < child.value.length) {
+      replacements.push({ type: 'text', value: child.value.slice(cursor) });
+    }
+    node.children.splice(index, 1, ...replacements);
+    index += replacements.length - 1;
+  }
+}
+
+/**
+ * Number memo blocks from one on every page and resolve same-page
+ * `[[memo-id]]` references. Numbering is intentionally page-local.
+ *
+ * @this {any}
+ */
+export default function remarkMemo() {
+  const processor = this;
+  const parse = processor.parser;
+  if (typeof parse !== 'function') {
+    throw new Error(
+      'remarkMemo must be registered after the Markdown parser (and after remark-mdx when configured explicitly).',
+    );
+  }
+  Reflect.set(processor, 'parser', (document, file) =>
+    parse(preprocessMemos(document), file),
+  );
+
+  return function transform(tree, file) {
+    const blocks = new Map();
+    const markerLocations = new Map();
+    const unprocessed = [];
+
+    visit(tree, (node, parent) => {
+      if (
+        node.type === 'link' &&
+        typeof node.url === 'string' &&
+        node.url.startsWith(MARKER_URL_PREFIX)
+      ) {
+        const token = node.url.slice(MARKER_URL_PREFIX.length);
+        if (markerLocations.has(token)) {
+          fail(file, 'Internal memo marker collision.', node);
+        }
+        markerLocations.set(token, { node, parent });
+      }
+      if (node.name !== 'Memo') return;
+      const internal = mdxAttributesNamed(node, BLOCK_ATTRIBUTE);
+      if (internal.length === 0) {
+        unprocessed.push(node);
+        return;
+      }
+      const token = literalAttribute(node, BLOCK_ATTRIBUTE, file);
+      if (blocks.has(token)) fail(file, 'Internal memo block collision.', node);
+      blocks.set(token, node);
+    });
+
+    if (unprocessed.length > 0) {
+      fail(
+        file,
+        '<Memo> must use a paired opening and closing tag so remarkMemo can place its inline marker and block body.',
+        unprocessed[0],
+      );
+    }
+    for (const token of markerLocations.keys()) {
+      if (!blocks.has(token)) fail(file, 'Internal memo marker/block pairing failed.', tree);
+    }
+
+    const seenIds = new Set();
+    const memos = new Map();
+    let number = 0;
+    for (const [token, node] of blocks) {
+      const marker = markerLocations.get(token);
+      if (marker && (!marker.parent || !Array.isArray(marker.parent.children))) {
+        fail(file, 'Internal memo marker has no paragraph parent.', marker.node);
+      }
+      if (node.type !== 'mdxJsxFlowElement') {
+        fail(file, '<Memo> did not become a block-level MDX element.', node);
+      }
+
+      const id = literalAttribute(node, 'id', file);
+      const title = literalAttribute(node, 'title', file);
+      literalAttribute(node, 'description', file);
+      const label = literalAttribute(node, 'label', file, { optional: true });
+      if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
+        fail(
+          file,
+          `Invalid <Memo id="${id}">; use lowercase letters/numbers separated by single hyphens.`,
+          node,
+        );
+      }
+      if (seenIds.has(id)) {
+        fail(file, `Duplicate <Memo id="${id}"> on this page.`, node);
+      }
+      seenIds.add(id);
+
+      number += 1;
+      const anchorId = `memo-${id}`;
+      removeMdxAttribute(node, BLOCK_ATTRIBUTE);
+      injectMdxStringAttributes(node, {
+        number: String(number),
+        anchorId,
+      });
+
+      const memo = {
+        id,
+        title,
+        label,
+        number: String(number),
+        anchorId,
+      };
+      memos.set(id, memo);
+
+      if (marker) {
+        const markerIndex = marker.parent.children.indexOf(marker.node);
+        marker.parent.children[markerIndex] = markerNode(memo);
+      }
+    }
+
+    rewriteMemoReferences(tree, memos, file);
+  };
+}