blume 2.0.3 → 2.1.1

package/src/eval/report.ts

@@ -10,27 +10,40 @@ import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
+/** How a question reads in the report: its status, or `warn` for a warned miss. */
+type ShownStatus = QuestionStatus | "warn";
+
 const GLYPH = {
   error: "!",
   fail: "✖",
   pass: "✔",
   skip: "⊘",
-} satisfies Record<QuestionStatus, string>;
+  warn: "⚠",
+} satisfies Record<ShownStatus, string>;
 
 const STATUS_COLOR = {
   error: colors.yellow,
   fail: colors.red,
   pass: colors.green,
   skip: colors.dim,
-} satisfies Record<QuestionStatus, ColorFunction>;
+  warn: colors.yellow,
+} satisfies Record<ShownStatus, ColorFunction>;
+
+/**
+ * A failed `severity: warning` question: its miss never counts against the
+ * gate, so the report shows and counts it as a warning, not a failure.
+ */
+const warned = (result: QuestionResult): boolean =>
+  result.status === "fail" && result.severity === "warning";
 
 /** Longest id gets the room; everything shorter aligns to it. */
 const ID_PAD = 28;
 
 /** One question's progress/report line: glyph, id, status, score, time, cost. */
 export const questionLine = (result: QuestionResult): string => {
-  const color = STATUS_COLOR[result.status];
-  const glyph = color(GLYPH[result.status]);
+  const shown: ShownStatus = warned(result) ? "warn" : result.status;
+  const color = STATUS_COLOR[shown];
+  const glyph = color(GLYPH[shown]);
   const id = result.id.padEnd(ID_PAD);
   if (result.status === "skip") {
     return `  ${glyph} ${id} ${colors.dim("skipped")}`;
@@ -38,7 +51,7 @@ export const questionLine = (result: QuestionResult): string => {
   const score = result.score === undefined ? "" : result.score.toFixed(2);
   const cost = money(result.costUsd);
   const cells = [
-    color(result.status),
+    color(shown),
     score,
     colors.dim(seconds(result.durationMs)),
     cost === "" ? "" : colors.dim(cost),
@@ -75,9 +88,12 @@ export const questionDetails = (
 /** The one-line totals: `9 passed · 2 failed · 1 skipped · 1m 42s · $0.71`. */
 export const summaryLine = (result: EvalResult): string => {
   const { counts } = result;
+  const warnings = result.results.filter(warned).length;
+  const failures = counts.fail - warnings;
   const parts = [
     `${counts.pass} passed`,
-    counts.fail > 0 ? `${counts.fail} failed` : "",
+    failures > 0 ? `${failures} failed` : "",
+    warnings > 0 ? `${warnings} warned` : "",
     counts.error > 0 ? `${counts.error} errored` : "",
     counts.skip > 0 ? `${counts.skip} skipped` : "",
     duration(result.durationMs),
@@ -98,10 +114,11 @@ export const startLine = (id: string, index: number, total: number): string =>
  * `fix:` pointers for failed questions, naming the file that resolves each. A
  * question whose agent run errored gets a `run failed:` line pointing at the
  * question instead: the run never graded the docs, so there's no page to fix.
+ * A `severity: warning` question's miss is a warning line instead.
  */
 export const fixLines = (result: EvalResult, root: string): string[] =>
   result.diagnostics
-    .filter((diagnostic) => diagnostic.code !== "BLUME_EVAL_ROUTE_UNKNOWN")
+    .filter((diagnostic) => diagnostic.severity !== "warning")
     .map((finding) => {
       const site = finding.file
         ? `${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
@@ -113,10 +130,13 @@ export const fixLines = (result: EvalResult, root: string): string[] =>
       return `  ${label} ${site} ${colors.dim(finding.message)}`;
     });
 
-/** Dim warnings for route hints that no longer match a page. */
+/**
+ * Dim warnings: route hints that no longer match a page, and the misses of
+ * `severity: warning` questions.
+ */
 export const warningLines = (result: EvalResult, root: string): string[] =>
   result.diagnostics
-    .filter((diagnostic) => diagnostic.code === "BLUME_EVAL_ROUTE_UNKNOWN")
+    .filter((diagnostic) => diagnostic.severity === "warning")
     .map((finding) => {
       const site = finding.file
         ? ` ${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
@@ -140,10 +160,11 @@ export const formatEvalReport = (
   }
   lines.push("");
 
-  // The finding tells the author which file fixes which failure.
-  const failures = fixLines(result, root);
-  lines.push(...failures);
-  if (failures.length > 0) {
+  // The finding tells the author which file fixes which failure, warnings
+  // first, as the command prints them.
+  const findings = [...warningLines(result, root), ...fixLines(result, root)];
+  lines.push(...findings);
+  if (findings.length > 0) {
     lines.push("");
   }
 

package/src/eval/run.ts

@@ -40,6 +40,8 @@ export interface QuestionResult {
   question: string;
   routes: string[];
   score?: number;
+  /** The question's severity: a `warning` miss is reported as a warning. */
+  severity?: EvalQuestion["severity"];
   status: QuestionStatus;
 }
 
@@ -99,6 +101,7 @@ const errored = (
   missing: [],
   question: question.question,
   routes: question.routes,
+  severity: question.severity,
   status: "error",
 });
 
@@ -177,6 +180,7 @@ const runQuestion = async (
     question: question.question,
     routes: question.routes,
     score: verdict.score,
+    severity: question.severity,
     status: verdict.pass ? "pass" : "fail",
   };
 };
@@ -250,6 +254,7 @@ export const runEval = async (options: EvalRunOptions): Promise<EvalResult> => {
         missing: [],
         question: question.question,
         routes: question.routes,
+        severity: question.severity,
         status: "skip",
       });
       continue;

package/src/markdown/api-rail.ts

@@ -0,0 +1,259 @@
+import type { EvaluatedValue } from "../ai/component-markdown.ts";
+import { readStaticExpression } from "../ai/static-expression.ts";
+import { PARAM_LOCATIONS } from "../components/content/api-field.ts";
+import type { FieldValue } from "../components/content/api-field.ts";
+import {
+  AUTH_METHODS,
+  PLAYGROUND_MODES,
+  parseApiEndpoint,
+} from "../components/content/api-page.ts";
+import type {
+  EndpointField,
+  EndpointSpec,
+} from "../components/content/api-page.ts";
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+/**
+ * The right-hand column of a hand-written API page, as Mintlify renders one.
+ * Top-level `<RequestExample>` and `<ResponseExample>` move into an
+ * `<ApiRail>` at the end of the document, request examples first, and the
+ * render is flagged so the layout makes room for the column (see
+ * `ApiRail.astro`). Below `xl` the rail follows the page's content, and the
+ * examples are ordinary code groups there. An example nested in another
+ * component stays where it is written.
+ *
+ * A page with `api` frontmatter (`POST /v1/users`) also gets its endpoint: the
+ * method and path at the top of the page (`<ApiEndpoint>`), and at the head of
+ * the rail a Try it panel and request samples (`<ApiPlayground>`) built from
+ * the page's `<ParamField>`s, which the plugin collects here, nested body
+ * fields included (see `components/content/api-page.ts`).
+ */
+
+/** The render-frontmatter key that tells the layout a page has a rail. */
+export const API_RAIL_KEY = "blumeApiRail";
+
+/** The components that move to the rail, in the order they stack there. */
+const RAIL_COMPONENTS = ["RequestExample", "ResponseExample"];
+
+/** The root, as the plugin's `after` hook receives it. */
+interface RailRoot {
+  children: MdastNode[];
+}
+
+/** The slice of Satteri's visitor context the plugin uses. */
+export interface ApiRailContext {
+  appendChild: (node: RailRoot, child: MdastNode) => void;
+  data?: { astro?: { frontmatter?: Record<string, EvaluatedValue> } };
+  insertChildAt: (node: RailRoot, index: number, child: MdastNode) => void;
+  removeNode: (node: MdastNode) => void;
+}
+
+/**
+ * A detached copy of a node Satteri materialized lazily: its own fields,
+ * children included, without the arena handles that tie it to its old place.
+ * Appending the original instead would move an empty shell.
+ */
+const detach = (node: MdastNode): MdastNode =>
+  JSON.parse(
+    JSON.stringify(node, (key: string, value: MdastValue) =>
+      key === "_id" || key === "_resolver" ? undefined : value
+    )
+  );
+
+const isName = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+const railIndex = (node: MdastNode): number =>
+  node.type === "mdxJsxFlowElement" && isName(node.name)
+    ? RAIL_COMPONENTS.indexOf(node.name)
+    : -1;
+
+/** An element's name, when it is a JSX element. */
+const elementName = (node: MdastNode): string | undefined =>
+  node.type === "mdxJsxFlowElement" && isName(node.name)
+    ? node.name
+    : undefined;
+
+const isNode = (value: MdastValue): value is MdastNode =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A node's children, when it has any. */
+const childrenOf = (node: MdastNode): MdastNode[] =>
+  Array.isArray(node.children) ? node.children.filter(isNode) : [];
+
+/** One JSX attribute, as the parser leaves it. */
+interface JsxAttribute {
+  name?: string;
+  type: string;
+  value?: string | { value: string } | null;
+}
+
+const isAttribute = (value: MdastValue): value is JsxAttribute & MdastNode =>
+  isNode(value) && value.type === "mdxJsxAttribute";
+
+/** An element's attributes, name to value. */
+interface AttributeValues {
+  [name: string]: EvaluatedValue;
+}
+
+/**
+ * An element's attributes as values: text, shorthand flags as `true`, and
+ * expressions read as literal data (see `ai/static-expression.ts`); one that
+ * isn't literal is left out.
+ */
+const attributeValues = (
+  node: MdastNode,
+  frontmatter: Record<string, EvaluatedValue> | undefined
+): AttributeValues => {
+  const values: AttributeValues = {};
+  const attributes = Array.isArray(node.attributes) ? node.attributes : [];
+  for (const attribute of attributes.filter(isAttribute)) {
+    const { name, value } = attribute;
+    if (!name) {
+      continue;
+    }
+    if (value === null || value === undefined) {
+      values[name] = true;
+    } else if (isName(value)) {
+      values[name] = value;
+    } else {
+      const read = readStaticExpression(value.value, frontmatter);
+      if (read.ok) {
+        values[name] = read.value;
+      }
+    }
+  }
+  return values;
+};
+
+const isFlag = (value: EvaluatedValue): boolean =>
+  value === true || value === "true";
+
+/** A `<ParamField>`'s values as an endpoint field, or `null` with no location. */
+const endpointField = (values: AttributeValues): EndpointField | null => {
+  const location = PARAM_LOCATIONS.find((key) => isName(values[key]));
+  const name = location ? values[location] : undefined;
+  if (!(location && isName(name))) {
+    return null;
+  }
+  const field: EndpointField = { location, name };
+  if (isName(values.type)) {
+    field.type = values.type;
+  }
+  if (isName(values.placeholder)) {
+    field.placeholder = values.placeholder;
+  }
+  if (isFlag(values.required)) {
+    field.required = true;
+  }
+  if (isFlag(values.deprecated)) {
+    field.deprecated = true;
+  }
+  if (values.default !== undefined) {
+    // SAFETY: an attribute's literal data is JSON-shaped; a frontmatter
+    // date only arrives through `frontmatter.*`, which a default never reads.
+    field.default = values.default as FieldValue;
+  }
+  return field;
+};
+
+/**
+ * The `<ParamField>`s under `nodes`, in document order. A field's own nested
+ * fields (in its `<Expandable>`) become its `fields`, the properties of the
+ * object it describes.
+ */
+const collectFields = (
+  nodes: MdastNode[],
+  frontmatter: Record<string, EvaluatedValue> | undefined
+): EndpointField[] =>
+  nodes.flatMap((node) => {
+    const nested = collectFields(childrenOf(node), frontmatter);
+    if (elementName(node) !== "ParamField") {
+      return nested;
+    }
+    const field = endpointField(attributeValues(node, frontmatter));
+    if (!field) {
+      return nested;
+    }
+    return nested.length > 0 ? [{ ...field, fields: nested }] : [field];
+  });
+
+/** The page's endpoint, when its `api` frontmatter names one. */
+const endpointSpec = (
+  root: RailRoot,
+  frontmatter: Record<string, EvaluatedValue> | undefined,
+  requestExample: boolean
+): EndpointSpec | null => {
+  const api = frontmatter?.api;
+  const endpoint = isName(api) ? parseApiEndpoint(api) : null;
+  if (!endpoint) {
+    return null;
+  }
+  const spec: EndpointSpec = {
+    fields: collectFields(root.children, frontmatter),
+    method: endpoint.method,
+    requestExample,
+    target: endpoint.target,
+  };
+  const authMethod = AUTH_METHODS.find(
+    (method) => method === frontmatter?.authMethod
+  );
+  if (authMethod) {
+    spec.authMethod = authMethod;
+  }
+  const playground = PLAYGROUND_MODES.find(
+    (mode) => mode === frontmatter?.playground
+  );
+  if (playground) {
+    spec.playground = playground;
+  }
+  return spec;
+};
+
+/** Where the endpoint header goes: after a front matter block, if any. */
+const headerIndex = (root: RailRoot): number =>
+  root.children.findIndex(
+    (node) => node.type !== "yaml" && node.type !== "toml"
+  );
+
+export const apiRailPlugin = () => ({
+  after(root: RailRoot, ctx: ApiRailContext) {
+    const frontmatter = ctx.data?.astro?.frontmatter;
+    const examples = root.children.filter((node) => railIndex(node) !== -1);
+    const spec = endpointSpec(
+      root,
+      frontmatter,
+      examples.some((node) => railIndex(node) === 0)
+    );
+    const specAttribute = spec
+      ? [jsxAttribute("spec", JSON.stringify(spec))]
+      : [];
+    const playground =
+      spec && spec.playground !== "none"
+        ? [jsxFlowElement("ApiPlayground", specAttribute, [])]
+        : [];
+    for (const example of examples) {
+      ctx.removeNode(example);
+    }
+    if (spec) {
+      ctx.insertChildAt(
+        root,
+        Math.max(headerIndex(root), 0),
+        jsxFlowElement("ApiEndpoint", specAttribute, [])
+      );
+    }
+    const rail = [
+      ...playground,
+      ...examples.toSorted((a, b) => railIndex(a) - railIndex(b)).map(detach),
+    ];
+    if (rail.length === 0) {
+      return;
+    }
+    ctx.appendChild(root, jsxFlowElement("ApiRail", [], rail));
+    if (frontmatter) {
+      frontmatter[API_RAIL_KEY] = true;
+    }
+  },
+  name: "blume-api-rail",
+});

package/src/markdown/code-title.ts

@@ -7,6 +7,12 @@
  *   language label.
  * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
+ * - the `wrap` keyword becomes `data-wrap`: this block's long lines wrap
+ *   instead of scrolling, as `markdown.code.wrap` does for every block.
+ * - the `expandable` keyword becomes `data-expandable` on a block of
+ *   {@link EXPANDABLE_MIN_LINES} lines or more: the theme shows its first
+ *   {@link EXPANDABLE_VISIBLE_LINES} lines, and the page script adds a toggle
+ *   that shows the rest in full. A shorter block renders as it is.
  */
 
 import {
@@ -16,9 +22,20 @@ import {
   RESERVED_META_KEYWORDS,
 } from "./fence-meta.ts";
 
+/** The lines a collapsed `expandable` block shows. */
+export const EXPANDABLE_VISIBLE_LINES = 10;
+
+/**
+ * The lines a block needs before `expandable` collapses it: a few more than it
+ * shows, so the toggle never hides a line or two behind a click.
+ */
+export const EXPANDABLE_MIN_LINES = 16;
+
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
   options: { meta?: { __raw?: string } };
+  /** The block's code, as highlighted. */
+  source?: string;
 }
 
 /** The `<pre>` hast node a Shiki `pre` hook receives. */
@@ -33,12 +50,6 @@ export interface CodeTitleTransformer {
 }
 
 const TITLE_ATTR = /(?:^|\s)title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
-const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
-
-// Quoted attrs are blanked before keyword/bare-token scans so a quoted value
-// can't leak tokens (`title="enable lineNumbers later"`).
-const withoutQuotedAttrs = (raw: string): string =>
-  raw.replace(QUOTED_ATTR, " ");
 
 // The first bare token is the title (```ts blume.config.ts): a non-empty token
 // that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
@@ -71,8 +82,14 @@ export const parseCodeTitle = (raw: string | undefined): string | undefined => {
   return metaTokens(raw).find(isTitleToken);
 };
 
-const hasLineNumbers = (raw: string | undefined): boolean =>
-  Boolean(raw && LINE_NUMBERS.test(withoutQuotedAttrs(raw)));
+// The shared tokenizer keeps a quoted attr whole, so a keyword inside a
+// quoted value (`title="enable lineNumbers later"`) is never a token of its own.
+const hasKeyword = (raw: string | undefined, keyword: string): boolean =>
+  metaTokens(raw).includes(keyword);
+
+/** How many lines a block's code runs to, a trailing newline aside. */
+export const lineCount = (source = ""): number =>
+  source === "" ? 0 : source.replace(/\r?\n$/u, "").split(/\r?\n/u).length;
 
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export const codeTitleTransformer = (): CodeTitleTransformer => ({
@@ -83,8 +100,17 @@ export const codeTitleTransformer = (): CodeTitleTransformer => ({
     if (title) {
       node.properties.dataTitle = title;
     }
-    if (hasLineNumbers(raw)) {
+    if (hasKeyword(raw, "lineNumbers")) {
       node.properties.dataLineNumbers = true;
     }
+    if (hasKeyword(raw, "wrap")) {
+      node.properties.dataWrap = true;
+    }
+    if (
+      hasKeyword(raw, "expandable") &&
+      lineCount(this.source) >= EXPANDABLE_MIN_LINES
+    ) {
+      node.properties.dataExpandable = true;
+    }
   },
 });

package/src/markdown/features.ts

@@ -11,8 +11,9 @@ export const MARKDOWN_FEATURES = {
 
 /**
  * The `.mdx` feature set: Markdown's plus `:::` directives (→ `<Callout>`) and
- * block-only math — `singleDollarTextMath: false` keeps a bare `$` (currency,
- * shell, code) as literal text and only parses `$$…$$`.
+ * math — `singleDollarTextMath: false` keeps a bare `$` (currency, shell,
+ * code) as literal text and only parses `$$…$$`, as a block on its own lines
+ * or inline within a sentence.
  */
 export const MDX_FEATURES = {
   ...MARKDOWN_FEATURES,

package/src/markdown/fence-meta.ts

@@ -41,9 +41,11 @@ export const metaTokens = (meta: string | null | undefined): string[] =>
  * a block title.
  */
 export const RESERVED_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "expandable",
   "lineNumbers",
   "ts2js",
   "twoslash",
+  "wrap",
 ]);
 
 /** A Shiki `{1,3-5}` line-range token. */

package/src/markdown/include.ts

@@ -9,6 +9,8 @@ import {
   hasIncludeStatements,
   matchIncludeStatement,
 } from "../core/includes.ts";
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
 
 /**
@@ -83,6 +85,8 @@ const errorBlock = (message: string): string =>
 export interface IncludePluginOptions {
   /** The docs content root; bounds include resolution when set. */
   contentRoot?: string;
+  /** Content variables, substituted in each included file before it's parsed. */
+  variables?: ContentVariables;
 }
 
 /** A plain string attribute value; expression values don't carry a path. */
@@ -104,6 +108,10 @@ const statementFromJsx = (
     if (attr.name === "meta" && attr.value) {
       attributes.meta = attr.value;
     }
+    // Every other string attribute is a prop, as in the string-level parser.
+    if (attr.name && attr.name !== "lang" && attr.name !== "meta") {
+      attributes.props = { ...attributes.props, [attr.name]: attr.value };
+    }
   }
   return { attributes, target: ctx.textContent(node).trim() };
 };
@@ -147,7 +155,9 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
     for (const nested of expanded.errors) {
       ctx.report({ message: nested.message, node, severity: "warning" });
     }
-    return expanded.text;
+    // Substituted here, before the spliced text is parsed: in an MDX page it
+    // parses as MDX, where `{{name}}` would be a JavaScript expression.
+    return substituteVariables(expanded.text, options.variables);
   };
 
   /**

package/src/markdown/index.ts

@@ -9,6 +9,9 @@ import {
 import { escape as escapeHtml } from "html-escaper";
 import { codeToHtml } from "shiki";
 
+import { hasVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+import { apiRailPlugin } from "./api-rail.ts";
 import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
@@ -26,6 +29,8 @@ import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 import { ts2jsPlugin } from "./ts2js.ts";
+import { variablesPlugin } from "./variables.ts";
+import { viewsPlugin } from "./views.ts";
 
 export type { CodeTheme, CodeThemes } from "./themes.ts";
 
@@ -277,6 +282,12 @@ export interface BlumeMarkdownOptions {
    * `basePath` link isn't double-prefixed (see `withComposedBasePath`).
    */
   deployBase?: string;
+  /**
+   * `variables`: `{{name}}` references replaced in `.md` pages and in every
+   * included file (`.mdx` pages are substituted before parsing, by the
+   * `variablesVitePlugin`).
+   */
+  variables?: ContentVariables;
   /**
    * The docs content root, bounding `<include>` target resolution (and
    * anchoring `/`-leading include paths). When unset, relative includes still
@@ -326,7 +337,12 @@ const blumeSharedMdastPlugins = (
  * (callouts, mermaid, math, base links) like inline content.
  */
 const blumeIncludePlugin = (options: BlumeMarkdownOptions): MdastPlugin =>
-  asMdastPlugin(includePlugin({ contentRoot: options.contentRoot }));
+  asMdastPlugin(
+    includePlugin({
+      contentRoot: options.contentRoot,
+      variables: options.variables,
+    })
+  );
 
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
@@ -335,6 +351,9 @@ export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),
+      ...(hasVariables(options.variables)
+        ? [asMdastPlugin(variablesPlugin(options.variables))]
+        : []),
       ...blumeSharedMdastPlugins(options),
     ],
   });
@@ -345,13 +364,15 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, ` ```ts ts2js ` →
  * TypeScript/JavaScript tabs, `:::note` → `<Callout>`, ` ```mermaid ` → a
- * `<blume-mermaid>` element, and block math
- * (`$$…$$`) → the `<Math>` component. Used as the `processor` for
+ * `<blume-mermaid>` element, block math
+ * (`$$…$$`) → the `<Math>` component, and top-level `<RequestExample>` and
+ * `<ResponseExample>` → the page's `<ApiRail>`. Used as the `processor` for
  * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
  * {@link blumeMarkdownProcessor}).
  *
- * Math is always on but block-only: `singleDollarTextMath: false` keeps a bare
- * `$` (currency, shell, code) as literal text and only parses `$$…$$`. The
+ * Math is always on and written `$$…$$`, as a block or inline:
+ * `singleDollarTextMath: false` keeps a bare `$` (currency, shell, code) as
+ * literal text. The
  * generated runtime imports the `<Math>` component (and KaTeX's stylesheet) only
  * when content actually uses `$$`, so a math-free site ships no KaTeX CSS.
  *
@@ -370,5 +391,7 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
       asMdastPlugin(mermaidPlugin()),
       asMdastPlugin(mathPlugin()),
       ...blumeSharedMdastPlugins(options),
+      asMdastPlugin(apiRailPlugin()),
+      asMdastPlugin(viewsPlugin()),
     ],
   });

package/src/markdown/math.ts

@@ -7,10 +7,10 @@ interface MathNode extends MdastNode {
 
 /**
  * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
- * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
- * block element. Blume runs the parser block-only (`singleDollarTextMath:
- * false`), so a bare `$` stays literal and no `inlineMath` nodes are produced;
- * the `inlineMath` visitor remains as a harmless safety net.
+ * which renders them with KaTeX at build time. `$$…$$` on its own lines is
+ * block math and becomes a display element; `$$…$$` inside a sentence is
+ * inline math and stays inline. The parser runs with `singleDollarTextMath:
+ * false`, so a single `$` (currency, a shell variable) never opens math.
  */
 export const mathPlugin = () => ({
   inlineMath(node: MathNode, ctx: MdastVisitorContext) {

package/src/markdown/relative-links.ts

@@ -266,8 +266,9 @@ export const relativeLinksPlugin = (
 
   // A component's string `href` (`<Card href="./install">`) is the same kind
   // of link, and `blume validate` reads it as one. Lowercase elements are
-  // raw HTML in a `.md` page, which neither rewrites nor checks, so only
-  // components are rewritten; an expression-valued `href={…}` is left alone.
+  // raw HTML in a `.md` page, which isn't rewritten, so only components are
+  // rewritten (validate reads a raw `<a href>` as the browser does); an
+  // expression-valued `href={…}` is left alone.
   const rewriteHref = (node: JsxNode, ctx: RelativeLinksContext): void => {
     if (!node.name || !COMPONENT_NAME.test(node.name)) {
       return;