blume 2.0.0 → 2.0.2

package/src/markdown/base-links.ts

@@ -1,5 +1,11 @@
-import { isInternalPath, withComposedBasePath } from "../core/base-path.ts";
+import {
+  isInternalPath,
+  withBasePath,
+  withComposedBasePath,
+} from "../core/base-path.ts";
+import { servesRoute } from "../core/locale-links.ts";
 import type { MdastNode } from "./mdast.ts";
+import { routeSnapshotReader } from "./route-snapshot.ts";
 
 interface UrlNode extends MdastNode {
   url?: string | null;
@@ -16,12 +22,12 @@ interface MdastUrlContext {
 
 /**
  * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
- * — treated as a public asset, which Blume serves from `public/` at the site
- * root and does *not* move under `basePath`. Bare page links (`/guide`) have no
- * extension. The rare dotted route (`/releases/v1.0`) is left un-based here; the
- * build-time link checker still resolves it against the route set.
+ * — a public asset, which Blume serves from `public/` at the site root and
+ * does *not* move under `basePath`, unless a page is served there: a dotted
+ * route (`/releases/v1.2`) is based like any other page link, the same
+ * served-route test the link checker and the locale rewrite apply.
  */
-const ASSET_PATH = /\.[a-z0-9]+$/iu;
+const DOTTED_PATH = /\.[a-z0-9]+$/iu;
 
 /** Strip any `#fragment`/`?query` so only the path is extension-tested. */
 const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
@@ -30,6 +36,14 @@ const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 const isUrl = (url: string | null | undefined): url is string =>
   typeof url === "string";
 
+export interface BaseLinksPluginOptions {
+  /**
+   * The `blume:data` JSON file, for an ejected app: with no CLI in the process
+   * to publish the snapshot, the plugin reads the file eject writes instead.
+   */
+  dataFile?: string;
+}
+
 /**
  * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
  * layered over the site-wide `basePath` — to root-relative internal page links
@@ -39,10 +53,43 @@ const isUrl = (url: string | null | undefined): url is string =>
  * relative paths, images, and asset links. Only constructed when a base is set
  * (see `markdown/index.ts`).
  */
-export const baseLinksPlugin = (deployBase: string, basePath: string) => {
+export const baseLinksPlugin = (
+  deployBase: string,
+  basePath: string,
+  options: BaseLinksPluginOptions = {}
+) => {
+  const readSnapshot = routeSnapshotReader(options.dataFile);
+  // Parsed once per published snapshot, like the relative-links index.
+  let cached: { routes: Set<string>; text: string } | undefined;
+
+  /** Every route the site serves (base-prefixed), from the route snapshot. */
+  const servedRoutes = (): ReadonlySet<string> => {
+    const text = readSnapshot();
+    if (text === undefined) {
+      return new Set();
+    }
+    if (cached?.text !== text) {
+      const data: { routes: { path: string }[] } = JSON.parse(text);
+      cached = {
+        routes: new Set(data.routes.map((route) => route.path)),
+        text,
+      };
+    }
+    return cached.routes;
+  };
+
+  /** Whether an internal `url` links a page rather than a public asset. */
+  const isPageLink = (url: string): boolean => {
+    const path = pathOf(url);
+    return (
+      !DOTTED_PATH.test(path) ||
+      servesRoute(servedRoutes(), withBasePath(basePath, path))
+    );
+  };
+
   const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
     const { url } = node;
-    if (isUrl(url) && isInternalPath(url) && !ASSET_PATH.test(pathOf(url))) {
+    if (isUrl(url) && isInternalPath(url) && isPageLink(url)) {
       const next = withComposedBasePath(deployBase, basePath, url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);

package/src/markdown/index.ts

@@ -286,8 +286,9 @@ export interface BlumeMarkdownOptions {
   contentRoot?: string;
   /**
    * The `blume:data` snapshot file an ejected app aliases. Relative page links
-   * resolve through the snapshot the CLI publishes; with no CLI in the
-   * process, they read this file instead.
+   * (and the base-path rewrite of dotted page routes) resolve through the
+   * snapshot the CLI publishes; with no CLI in the process, they read this
+   * file instead.
    */
   dataFile?: string;
 }
@@ -310,7 +311,9 @@ const blumeSharedMdastPlugins = (
   ...(options.basePath || options.deployBase
     ? [
         asMdastPlugin(
-          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
+          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "", {
+            dataFile: options.dataFile,
+          })
         ),
       ]
     : []),

package/src/markdown/relative-links.ts

@@ -1,12 +1,11 @@
-import { readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 import { dirname, normalize, relative, resolve } from "pathe";
 
-import { readRuntimeModule } from "../astro/runtime-modules.ts";
 import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
+import { routeSnapshotReader } from "./route-snapshot.ts";
 
 interface UrlNode extends MdastNode {
   url?: string | null;
@@ -156,34 +155,15 @@ export const relativeLinksPlugin = (
   const contentRoot = options.contentRoot
     ? resolve(options.contentRoot)
     : undefined;
-  const dataFile = options.dataFile ? resolve(options.dataFile) : undefined;
+  const readSnapshot = routeSnapshotReader(options.dataFile);
 
   // Parsed once per published snapshot: the CLI republishes on regeneration,
   // and an unchanged snapshot is the same string, so every page compiled
   // between regenerations reuses one index.
   let cached: { index: RouteIndex; text: string } | undefined;
-  let fileStamp: number | undefined;
-  let fileText: string | undefined;
-
-  /** The ejected snapshot file's text, re-read only when it changes. */
-  const readDataFile = (path: string): string | undefined => {
-    let stamp: number;
-    try {
-      stamp = statSync(path).mtimeMs;
-    } catch {
-      return undefined;
-    }
-    if (stamp !== fileStamp) {
-      fileStamp = stamp;
-      fileText = readFileSync(path, "utf-8");
-    }
-    return fileText;
-  };
 
   const routeIndex = (): RouteIndex | undefined => {
-    const text =
-      readRuntimeModule("blume:data") ??
-      (dataFile ? readDataFile(dataFile) : undefined);
+    const text = readSnapshot();
     if (text === undefined) {
       return undefined;
     }

package/src/markdown/route-snapshot.ts

@@ -0,0 +1,37 @@
+import { readFileSync, statSync } from "node:fs";
+
+import { resolve } from "pathe";
+
+import { readRuntimeModule } from "../astro/runtime-modules.ts";
+
+/**
+ * A reader for the `blume:data` snapshot the Markdown link plugins consult for
+ * the site's routes: the text the CLI publishes, or — in an ejected app, with
+ * no CLI in the process — the snapshot file eject writes (`dataFile`), re-read
+ * only when it changes. Resolves to `undefined` when neither is available.
+ */
+export const routeSnapshotReader = (
+  dataFile?: string
+): (() => string | undefined) => {
+  const file = dataFile ? resolve(dataFile) : undefined;
+  let fileStamp: number | undefined;
+  let fileText: string | undefined;
+
+  /** The ejected snapshot file's text, re-read only when it changes. */
+  const readDataFile = (path: string): string | undefined => {
+    let stamp: number;
+    try {
+      stamp = statSync(path).mtimeMs;
+    } catch {
+      return undefined;
+    }
+    if (stamp !== fileStamp) {
+      fileStamp = stamp;
+      fileText = readFileSync(path, "utf-8");
+    }
+    return fileText;
+  };
+
+  return () =>
+    readRuntimeModule("blume:data") ?? (file ? readDataFile(file) : undefined);
+};

package/src/og/card.ts

@@ -261,11 +261,23 @@ const logoMark = (svg: string, foreground: string): Node => {
 };
 
 // Fallback mark when no SVG logo is configured: an accent tile with the brand's
-// initial, matching the docs favicon aesthetic.
-const initialMark = (accent: string, initial: string): Node =>
+// initial, matching the docs favicon aesthetic. The initial takes the headline's
+// family, so it matches the title rather than whichever loaded font comes first.
+const initialMark = (
+  accent: string,
+  initial: string,
+  family: { fontFamily?: string }
+): Node =>
   container({
     children: initial
-      ? [text(initial, { color: "#ffffff", fontSize: 32, fontWeight: 600 })]
+      ? [
+          text(initial, {
+            color: "#ffffff",
+            fontSize: 32,
+            fontWeight: 600,
+            ...family,
+          }),
+        ]
       : [],
     style: {
       alignItems: "center",
@@ -319,7 +331,11 @@ export const renderOgImage = async (
     if (logo === false) {
       return [];
     }
-    return [logo ? logoMark(logo, foreground) : initialMark(accent, initial)];
+    return [
+      logo
+        ? logoMark(logo, foreground)
+        : initialMark(accent, initial, titleFamily),
+    ];
   };
   const header = container({
     children: mark(),

package/src/og/derive.ts

@@ -2,7 +2,9 @@
  * Bridges `theme.fonts` into the OG card renderer. A site that explicitly
  * picks its typefaces gets matching cards (and non-Latin coverage) without
  * configuring `seo.og.fonts`; untouched defaults derive nothing, so plain
- * sites keep Takumi's built-in font and gain no build-time font fetch.
+ * sites keep Takumi's built-in font and gain no build-time font fetch. Locales
+ * in scripts that font can't draw (Japanese, Hindi, Russian, …) add a Noto
+ * fallback for their script either way.
  */
 
 import { existsSync } from "node:fs";
@@ -14,7 +16,7 @@ import type {
   FontValue,
   LocalFontConfig,
 } from "../theme/fonts.ts";
-import { GOOGLE_FONTS, isFontSlug } from "../theme/fonts.ts";
+import { GOOGLE_FONTS, isFontSlug, localeFontSubsets } from "../theme/fonts.ts";
 import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
 
 /** Fonts plus per-role families for the generated OG endpoint. */
@@ -160,6 +162,140 @@ export const deriveOgFonts = (
   return result;
 };
 
+/**
+ * The family Takumi renders a card in when no font is loaded: its embedded
+ * Geist, which covers Latin only. Naming it keeps a card's Latin text in that
+ * face once locale fallbacks are loaded, since Takumi otherwise tries loaded
+ * fonts first; a glyph Geist lacks still falls back to them. Were Takumi to
+ * rename it, the name would resolve to nothing and cards would fall back to
+ * the loaded fonts, never to tofu.
+ */
+const BUILT_IN_FAMILY = "Geist";
+
+/**
+ * The Google Noto family that draws each language's script, keyed by BCP 47
+ * language subtag, for scripts beyond the Latin, Cyrillic, Greek, and
+ * Vietnamese that `Noto Sans` covers (see {@link localeOgFonts}). Keep keys
+ * alphabetical.
+ */
+const SCRIPT_FAMILIES = {
+  am: "Noto Sans Ethiopic",
+  ar: "Noto Sans Arabic",
+  as: "Noto Sans Bengali",
+  bn: "Noto Sans Bengali",
+  ckb: "Noto Sans Arabic",
+  fa: "Noto Sans Arabic",
+  gu: "Noto Sans Gujarati",
+  he: "Noto Sans Hebrew",
+  hi: "Noto Sans Devanagari",
+  hy: "Noto Sans Armenian",
+  ja: "Noto Sans JP",
+  ka: "Noto Sans Georgian",
+  km: "Noto Sans Khmer",
+  kn: "Noto Sans Kannada",
+  ko: "Noto Sans KR",
+  lo: "Noto Sans Lao",
+  ml: "Noto Sans Malayalam",
+  mr: "Noto Sans Devanagari",
+  my: "Noto Sans Myanmar",
+  ne: "Noto Sans Devanagari",
+  or: "Noto Sans Oriya",
+  pa: "Noto Sans Gurmukhi",
+  ps: "Noto Sans Arabic",
+  sa: "Noto Sans Devanagari",
+  si: "Noto Sans Sinhala",
+  ta: "Noto Sans Tamil",
+  te: "Noto Sans Telugu",
+  th: "Noto Sans Thai",
+  ti: "Noto Sans Ethiopic",
+  ur: "Noto Sans Arabic",
+  yi: "Noto Sans Hebrew",
+  zh: "Noto Sans SC",
+} satisfies Record<string, string>;
+
+/** Type guard: does `language` have an entry in the script table? */
+const isScriptLanguage = (
+  language: string
+): language is keyof typeof SCRIPT_FAMILIES =>
+  Object.hasOwn(SCRIPT_FAMILIES, language);
+
+/** A locale fallback: a Google family at the weights the card renders. */
+export interface LocaleOgFont {
+  name: string;
+  weight: number[];
+}
+
+/** Subtags that write Chinese in traditional characters (`zh-Hant`, `zh-TW`). */
+const TRADITIONAL_CHINESE = new Set(["hant", "hk", "mo", "tw"]);
+
+/** The Noto family for one locale's script, or null when Geist covers it. */
+const localeFamily = (locale: string): string | null => {
+  const [language = "", ...subtags] = locale.toLowerCase().split("-");
+  if (
+    language === "zh" &&
+    subtags.some((tag) => TRADITIONAL_CHINESE.has(tag))
+  ) {
+    return "Noto Sans TC";
+  }
+  if (isScriptLanguage(language)) {
+    return SCRIPT_FAMILIES[language];
+  }
+  // Anything past plain `latin` in the theme's subset table (Polish, Russian,
+  // Greek, Vietnamese, …) needs glyphs Geist lacks and `Noto Sans` has.
+  return localeFontSubsets([locale]).length > 1 ? "Noto Sans" : null;
+};
+
+/**
+ * The fallback card fonts the configured locales' scripts need, at the card's
+ * weights. Takumi's built-in font covers only basic Latin, so without these a
+ * Japanese or Hindi page's card renders every glyph as tofu. The renderer
+ * fetches only the glyph subsets a card's text uses, so an English card on
+ * the same site pulls nothing extra.
+ */
+export const localeOgFonts = (locales: string[]): LocaleOgFont[] => {
+  const names = new Set<string>();
+  for (const locale of locales) {
+    const family = localeFamily(locale);
+    if (family) {
+      names.add(family);
+    }
+  }
+  return [...names].map((name) => ({ name, weight: CARD_WEIGHTS }));
+};
+
+/** A bare Google family name entry (as opposed to the object forms). */
+const isGoogleFamilyName = (font: OgFont): font is string =>
+  typeof font === "string";
+
+/** The family an OG font entry registers under. */
+const ogFontName = (font: OgFont): string =>
+  isGoogleFamilyName(font) ? font : font.name;
+
+/**
+ * `derived` plus the locale fallbacks it doesn't already load. A card that
+ * names no family is pinned to {@link BUILT_IN_FAMILY}, so its Latin text
+ * keeps the face it had before any fallback was loaded.
+ */
+const withLocaleFonts = (
+  derived: DerivedOgFonts,
+  locales: string[]
+): DerivedOgFonts => {
+  const loaded = new Set(derived.fonts.map(ogFontName));
+  const fallbacks = localeOgFonts(locales).filter(
+    (font) => !loaded.has(ogFontName(font))
+  );
+  if (fallbacks.length === 0) {
+    return derived;
+  }
+  return {
+    families: derived.families ?? {
+      body: BUILT_IN_FAMILY,
+      title: BUILT_IN_FAMILY,
+    },
+    fonts: [...derived.fonts, ...fallbacks],
+  };
+};
+
 /** Explicit `seo.og.fonts` with local `src` paths resolved to absolute. */
 export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
   fonts.map((font) =>
@@ -170,10 +306,14 @@ export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
  * The fonts baked into the generated OG endpoint. An explicit `seo.og.fonts`
  * always wins (including `[]` to opt out, keeping the card's role styling
  * untouched); otherwise a site that explicitly set `theme.fonts` gets its
- * display/body fonts derived so cards match the site without extra config.
+ * display/body fonts derived so cards match the site without extra config,
+ * and either way the configured locales add a fallback for each script the
+ * built-in font can't draw.
  */
 export const resolveOgFonts = (
   options: {
+    /** The site's configured locale codes (none without `i18n`). */
+    locales?: string[];
     /** Explicit `seo.og.fonts`, or undefined when unset. */
     ogFonts: OgFont[] | undefined;
     themeFonts: FontsConfig;
@@ -185,9 +325,10 @@ export const resolveOgFonts = (
   if (options.ogFonts) {
     return { fonts: resolveOgFontSources(options.ogFonts, root) };
   }
-  return options.themeFontsConfigured
+  const derived = options.themeFontsConfigured
     ? deriveOgFonts(options.themeFonts, root)
     : { fonts: [] };
+  return withLocaleFonts(derived, options.locales ?? []);
 };
 
 /**

package/src/openapi/graphql-build.ts

@@ -1,4 +1,5 @@
 import type {
+  DocumentNode,
   GraphQLArgument,
   GraphQLEnumType,
   GraphQLField,
@@ -12,8 +13,8 @@ import type {
   GraphQLUnionType,
 } from "graphql";
 import {
+  buildASTSchema,
   buildClientSchema,
-  buildSchema,
   getNamedType,
   isEnumType,
   isInputObjectType,
@@ -21,7 +22,11 @@ import {
   isObjectType,
   isSpecifiedScalarType,
   isUnionType,
+  Kind,
+  parse,
   print,
+  specifiedDirectives,
+  visit,
 } from "graphql";
 
 import type {
@@ -259,6 +264,27 @@ const introspectionOf = <Value>(parsed: Value): object | undefined => {
     : undefined;
 };
 
+/**
+ * SDL with every use of an undeclared directive removed. Subgraph and platform
+ * schemas lean on directives their server defines out of band — Apollo
+ * Federation's `@key` and `@link`, AppSync's `@aws_*` — and strict SDL
+ * validation rejects each one as `Unknown directive`. The reference renders
+ * none of them, so they are dropped rather than declared; every other check
+ * (syntax, unknown types, duplicates) still runs.
+ */
+const withoutUnknownDirectives = (document: DocumentNode): DocumentNode => {
+  const known = new Set(specifiedDirectives.map((directive) => directive.name));
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.DIRECTIVE_DEFINITION) {
+      known.add(definition.name.value);
+    }
+  }
+  return visit(document, {
+    // `null` deletes the node; `undefined` leaves it in place.
+    Directive: (node) => (known.has(node.name.value) ? undefined : null),
+  });
+};
+
 /**
  * Build the document from schema text: an introspection JSON result (the raw
  * `{ __schema }` shape or a `{ data: { __schema } }` response envelope) or
@@ -289,5 +315,5 @@ export const buildGraphqlDocument = (text: string): GraphqlDocument => {
       )
     );
   }
-  return documentOf(buildSchema(text));
+  return documentOf(buildASTSchema(withoutUnknownDirectives(parse(text))));
 };

package/src/openapi/model.ts

@@ -1,6 +1,10 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
 
-import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+import type {
+  AsyncApiAction,
+  AsyncApiDocument,
+  AsyncApiSpecValue,
+} from "./asyncapi.ts";
 // Type-only, so the import can't cycle at runtime (graphql.ts imports the
 // collector from here).
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
@@ -99,7 +103,10 @@ export interface ApiOperationRef {
   channelId?: string;
 }
 
-/** A tag/section, in first-seen order. */
+/**
+ * A tag/section: the spec's declared tags in their declared order, then any
+ * undeclared tag an operation uses, in first-seen order.
+ */
 export interface ApiTagRef {
   slug: string;
   name: string;
@@ -212,6 +219,40 @@ export const specAddresses = (spec: ApiSpecData): SpecAddresses => {
   return { addresses, label: "Base URL" };
 };
 
+const SERVER_VARIABLE = /\{(?<name>[^{}]+)\}/gu;
+
+const isDocumentObject = (
+  value: AsyncApiSpecValue
+): value is Record<string, AsyncApiSpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+// YAML reads an unquoted `default: 8443` as a number; it is still the port.
+const isVariableDefault = (
+  value: AsyncApiSpecValue
+): value is string | number =>
+  typeof value === "string" || typeof value === "number";
+
+/**
+ * A server URL template — an OpenAPI `servers[].url`, an AsyncAPI server's
+ * `host` or `pathname` — with each `{variable}` replaced by the `default` its
+ * `variables` map declares. Code samples, the playground's Send, and the
+ * proxy allowlist all need a real address, and
+ * `https://{region}.api.example.com` is not one. A variable the map doesn't
+ * define with a default (invalid per both specs) stays templated.
+ */
+export const withServerDefaults = (
+  template: string,
+  variables: AsyncApiSpecValue
+): string =>
+  template.replaceAll(SERVER_VARIABLE, (match, name: string) => {
+    const variable =
+      isDocumentObject(variables) && Object.hasOwn(variables, name)
+        ? variables[name]
+        : undefined;
+    const value = isDocumentObject(variable) ? variable.default : undefined;
+    return isVariableDefault(value) ? String(value) : match;
+  });
+
 // The runtime object check stands guard because the document was parsed from
 // arbitrary YAML/JSON: a spec can put a scalar where the type promises an
 // operation object.
@@ -276,9 +317,10 @@ export interface ExtractedOperations extends CollectedOperations {
 
 /**
  * The collector behind both extractors (OpenAPI here, AsyncAPI in
- * `asyncapi.ts`): first-seen tag ordering, key de-duplication (a repeated key
- * gains its method/action as a suffix), and the shared route template — so
- * URL shape and slug rules can never drift between the two spec kinds.
+ * `asyncapi.ts`): declared-then-first-seen tag ordering, key de-duplication
+ * (a repeated key gains its method/action as a suffix), and the shared route
+ * template — so URL shape and slug rules can never drift between the two spec
+ * kinds.
  */
 export const operationCollector = (
   baseRoute: string,
@@ -310,15 +352,27 @@ export const operationCollector = (
     });
   };
 
+  // Declared tags in the order the spec's `tags` list gives them, then any
+  // tag an operation uses without declaring it, in first-use order. The
+  // declared order is the author's section order, not an accident of which
+  // path happens to come first.
+  const declared = [...tagMeta.keys()];
+  const rank = (name: string): number => {
+    const index = declared.indexOf(name);
+    return index === -1 ? declared.length : index;
+  };
+
   const finish = (): CollectedOperations => ({
     operations,
-    tags: tagOrder.map((name) => ({
-      description: tagMeta.get(name) ?? "",
-      name,
-      // The same slugger instance, so every tag resolves to the slug its
-      // operations were routed under.
-      slug: slugForTag(name),
-    })),
+    tags: tagOrder
+      .toSorted((a, b) => rank(a) - rank(b))
+      .map((name) => ({
+        description: tagMeta.get(name) ?? "",
+        name,
+        // The same slugger instance, so every tag resolves to the slug its
+        // operations were routed under.
+        slug: slugForTag(name),
+      })),
   });
 
   return { add, finish };
@@ -328,7 +382,8 @@ export const operationCollector = (
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
  * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item), so missing operations aren't silent.
+ * anything skipped (a `$ref` path item, webhooks), so missing operations
+ * aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
@@ -371,6 +426,15 @@ export const extractOperations = (
     }
   }
 
+  // OpenAPI 3.1 webhooks (requests the API sends, not ones it serves) have no
+  // page renderer; say so rather than dropping them silently.
+  const webhooks = Object.keys(document.webhooks ?? {});
+  if (webhooks.length > 0) {
+    warnings.push(
+      `The spec declares ${webhooks.length === 1 ? "a webhook" : `${webhooks.length} webhooks`} under "webhooks" (${webhooks.join(", ")}); webhooks aren't rendered, so they are missing from the reference.`
+    );
+  }
+
   return { ...collector.finish(), warnings };
 };
 

package/src/openapi/render-mdx.ts

@@ -90,6 +90,9 @@ const codeSpans = (text: string, tree: Root): [number, number][] => {
   return spans;
 };
 
+/** Stands in for `<` when locating code spans (see `mdxSafe`). */
+const HTML_MASK = "";
+
 /**
  * Escape MDX-special syntax in prose while leaving code verbatim. A spec is
  * someone else's content, so a link whose destination isn't a web, mail, or
@@ -101,8 +104,14 @@ const mdxSafe = (text: string): string => {
   const unsafe = unsafeLinkSpans(tree);
   const insideUnsafe = (offset: number): boolean =>
     unsafe.some((span) => offset >= span.start && offset < span.end);
+  // Code spans come from a parse with every `<` masked. The emitted MDX
+  // escapes each `<` outside code to `&lt;`, so no line of it is an HTML
+  // block — but CommonMark reads `<div>` as one and never looks for the code
+  // spans inside it, which would leave their braces to be escaped and shown
+  // as a literal `&#123;`. The mask is one code unit, so offsets line up.
+  const masked = text.replaceAll("<", HTML_MASK);
   const segments = [
-    ...codeSpans(text, tree)
+    ...codeSpans(masked, fromMarkdown(masked))
       .filter(([start]) => !insideUnsafe(start))
       .map(([start, end]) => ({ end, start, text: text.slice(start, end) })),
     ...unsafe,