blume 2.0.3 → 2.1.0

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/variables.ts

@@ -0,0 +1,56 @@
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+/**
+ * The Markdown half of content variables (see `core/variables.ts`): a Sätteri
+ * MDAST plugin that replaces `{{name}}` in a plain `.md` page's text, code,
+ * raw HTML, and link and image destinations. A `.md` page has no expressions,
+ * so every reference survives parsing as text and can be replaced here; MDX
+ * pages are substituted before they're parsed instead (`astro/variables.ts`).
+ * Nodes change through `setProperty`, not by mutating the node object.
+ */
+
+interface VariableContext {
+  setProperty: (node: MdastNode, key: string, value: string) => void;
+}
+
+const isText = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+/** The node properties that can hold a reference, per node type. */
+const FIELDS = {
+  code: ["value"],
+  definition: ["url", "title"],
+  html: ["value"],
+  image: ["url", "title", "alt"],
+  inlineCode: ["value"],
+  link: ["url", "title"],
+  text: ["value"],
+} as const;
+
+export const variablesPlugin = (variables: ContentVariables) => {
+  const replaceIn =
+    (keys: readonly string[]) =>
+    (node: MdastNode, ctx: VariableContext): void => {
+      for (const key of keys) {
+        const value = node[key];
+        if (value !== undefined && isText(value)) {
+          const next = substituteVariables(value, variables);
+          if (next !== value) {
+            ctx.setProperty(node, key, next);
+          }
+        }
+      }
+    };
+  return {
+    code: replaceIn(FIELDS.code),
+    definition: replaceIn(FIELDS.definition),
+    html: replaceIn(FIELDS.html),
+    image: replaceIn(FIELDS.image),
+    inlineCode: replaceIn(FIELDS.inlineCode),
+    link: replaceIn(FIELDS.link),
+    name: "blume-variables",
+    text: replaceIn(FIELDS.text),
+  };
+};

package/src/markdown/views.ts

@@ -0,0 +1,82 @@
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+/**
+ * A page's views: the `<View title>` blocks it's written in, as Mintlify
+ * writes them. Each distinct title is one option of the page's view picker,
+ * in the order the page first uses it, and several blocks can share a title.
+ * The plugin reads them off the tree and hands the list to the page template
+ * through the render's frontmatter, so the picker renders with the page
+ * instead of after it (see `ViewSwitcher.astro`).
+ */
+
+/** The render-frontmatter key the page's views travel on. */
+export const VIEWS_KEY = "blumeViews";
+
+/** One option of the view picker. */
+export interface PageView {
+  icon?: string;
+  title: string;
+}
+
+/** The root, as the plugin's `after` hook receives it. */
+interface ViewsRoot {
+  children: MdastNode[];
+}
+
+/** The slice of Satteri's visitor context the plugin uses. */
+export interface ViewsContext {
+  data?: { astro?: { frontmatter?: Record<string, MdastValue> } };
+}
+
+const isNode = (value: MdastValue): value is MdastNode =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isText = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+/** A JSX element's literal string attribute, when it has one. */
+const stringAttribute = (node: MdastNode, name: string): string | undefined => {
+  const attributes = Array.isArray(node.attributes) ? node.attributes : [];
+  const value = attributes.find(
+    (attribute) => isNode(attribute) && attribute.name === name
+  );
+  return isNode(value) && isText(value.value) && value.value.trim() !== ""
+    ? value.value.trim()
+    : undefined;
+};
+
+/** Every `<View>` element under `nodes`, in document order. */
+const viewElements = (nodes: readonly MdastValue[]): MdastNode[] =>
+  nodes
+    .filter(isNode)
+    .flatMap((node) => [
+      ...(node.type === "mdxJsxFlowElement" && node.name === "View"
+        ? [node]
+        : []),
+      ...viewElements(Array.isArray(node.children) ? node.children : []),
+    ]);
+
+/** The page's views, one per distinct title, in first-use order. */
+export const pageViews = (nodes: readonly MdastValue[]): PageView[] => {
+  const views = new Map<string, PageView>();
+  for (const element of viewElements(nodes)) {
+    const title = stringAttribute(element, "title");
+    if (title !== undefined && !views.has(title)) {
+      const icon = stringAttribute(element, "icon");
+      views.set(title, icon === undefined ? { title } : { icon, title });
+    }
+  }
+  return [...views.values()];
+};
+
+export const viewsPlugin = () => ({
+  after(root: ViewsRoot, ctx: ViewsContext) {
+    const frontmatter = ctx.data?.astro?.frontmatter;
+    const views = pageViews(root.children);
+    // A page with one view has nothing to switch between.
+    if (frontmatter && views.length > 1) {
+      frontmatter[VIEWS_KEY] = views.map((view) => ({ ...view }));
+    }
+  },
+  name: "blume-views",
+});

package/src/narration/build.ts

@@ -0,0 +1,412 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import {
+  copyFile,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+
+import { createGateway, generateSpeech } from "ai";
+import { HTMLElement, parse, TextNode } from "node-html-parser";
+import type { Node } from "node-html-parser";
+import { dirname, join } from "pathe";
+
+import { normalizeBasePath } from "../core/base-path.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ProjectContext } from "../core/types.ts";
+import type { NarrationProvider } from "./provider.ts";
+import {
+  extractNarration,
+  isNarratable,
+  isNarrationCues,
+  segmentNarration,
+} from "./script.ts";
+import type {
+  NarrationCues,
+  NarrationManifest,
+  NarrationSegment,
+  NarrationTree,
+} from "./script.ts";
+
+/**
+ * Generated narration: after Astro writes the HTML, read every page that
+ * carries the player exactly as the browser will (same walker, same blocks),
+ * split it into sentences, and give each sentence a clip from the configured
+ * speech model. Clips are cached by what decides their sound (text, language,
+ * model, voice, instructions, provider options), so a rebuild only pays for
+ * sentences that changed, and one sentence shared by many pages is generated
+ * once. Each page gets a manifest listing its clips; the player plays them in
+ * order and falls back to browser voices wherever a manifest is missing.
+ */
+
+/** How the build logs: the integration's Astro logger. */
+export interface NarrationLogger {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+}
+
+/** Speak `text` in `lang`, returning MP3 bytes. */
+export type Speak = (text: string, lang: string) => Promise<Uint8Array>;
+
+/** What a narration build did, for the log line and tests. */
+export interface NarrationBuildResult {
+  /** Clips that failed to generate; their pages get no manifest. */
+  failed: number;
+  /** Clips generated by the speech model on this build. */
+  generated: number;
+  /** Pages that got a manifest. */
+  pages: number;
+  /** Clips read back from the cache. */
+  reused: number;
+}
+
+// Bump to regenerate every clip: part of every cache key.
+const CLIP_FORMAT = 1;
+
+// Parallel speech requests. Low enough to stay inside provider rate limits on
+// a first build of a large site, where every sentence is new.
+const CONCURRENCY = 4;
+
+/**
+ * The clip cache directory: `node_modules/.cache/blume/narration`, next to the
+ * OG card cache and restored by the same host build caches (see `ogCacheDir`).
+ */
+export const narrationCacheDir = (
+  context: Pick<ProjectContext, "outDir" | "root">
+): string =>
+  existsSync(join(context.root, "node_modules"))
+    ? join(context.root, "node_modules", ".cache", "blume", "narration")
+    : join(context.outDir, ".cache", "narration");
+
+/** The walker's view of a node-html-parser tree. */
+export const htmlTree: NarrationTree<Node> = {
+  attr: (node, name) =>
+    node instanceof HTMLElement ? (node.getAttribute(name) ?? null) : null,
+  children: (node) => node.childNodes,
+  tag: (node) =>
+    node instanceof HTMLElement && node.tagName
+      ? node.tagName.toLowerCase()
+      : null,
+  text: (node) => (node instanceof TextNode ? node.text : null),
+};
+
+/** The player's settings on a built page, and the article it reads. */
+interface PlayerPage {
+  article: HTMLElement;
+  audioBase: string;
+  cues: NarrationCues;
+  lang: string;
+  manifest: string;
+}
+
+const parseCues = (json: string | undefined): NarrationCues | null => {
+  try {
+    const value: unknown = JSON.parse(json ?? "");
+    return isNarrationCues(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The generated player on a built page, or `null` when the page has none (or
+ * a player without generated audio, which reads with browser voices).
+ */
+export const readPlayerPage = (html: string): PlayerPage | null => {
+  const root = parse(html);
+  const player = root.querySelector("[data-blume-narration-player]");
+  // node-html-parser has no `dataset`; `attributes` is its decoded map.
+  const data = player?.attributes ?? {};
+  const manifest = data["data-manifest"];
+  const audioBase = data["data-audio-base"];
+  const article = player?.parentNode;
+  const cues = parseCues(data["data-cues"]);
+  if (
+    !(player && manifest && audioBase && cues) ||
+    !(article instanceof HTMLElement)
+  ) {
+    return null;
+  }
+  return {
+    article,
+    audioBase,
+    cues,
+    lang: data["data-lang"] ?? "en",
+    manifest,
+  };
+};
+
+/** The language code a speech model takes (`pt-BR` -> `pt`). */
+const speechLanguage = (lang: string): string =>
+  lang.toLowerCase().replaceAll("_", "-").split("-")[0] ?? lang;
+
+/**
+ * A clip's cache key: a digest of everything that decides how it sounds. The
+ * Blume version is deliberately left out, unlike the OG card's: an upgrade
+ * shouldn't pay to regenerate audio that would sound the same.
+ */
+export const clipKey = (
+  provider: NarrationProvider,
+  lang: string,
+  text: string
+): string => {
+  const { instructions, model, providerOptions, voice } = provider.options;
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        format: CLIP_FORMAT,
+        instructions,
+        lang: speechLanguage(lang),
+        model,
+        providerOptions,
+        text,
+        voice,
+      })
+    )
+    .digest("hex")
+    .slice(0, 32);
+};
+
+/** Speak through the Vercel AI Gateway with the provider's model and voice. */
+export const gatewaySpeaker = (provider: NarrationProvider): Speak => {
+  const { apiKeyEnv, headers, instructions, model, providerOptions, voice } =
+    provider.options;
+  const gateway = createGateway({ apiKey: process.env[apiKeyEnv], headers });
+  return async (text, lang) => {
+    const { audio } = await generateSpeech({
+      instructions,
+      language: speechLanguage(lang),
+      model: gateway.speechModel(model),
+      outputFormat: "mp3",
+      providerOptions,
+      text,
+      voice,
+    });
+    return audio.uint8Array;
+  };
+};
+
+/** Every `.html` file under `dir`. */
+const listHtml = async (dir: string): Promise<string[]> => {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".html"))
+    .map((entry) => join(entry.parentPath, entry.name))
+    .toSorted();
+};
+
+/** Run `task` over `items`, at most `limit` at a time. */
+const eachLimited = async <T>(
+  items: readonly T[],
+  limit: number,
+  task: (item: T) => Promise<void>
+): Promise<void> => {
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const item = items[next];
+      next += 1;
+      if (item !== undefined) {
+        // Workers pull one item at a time on purpose: that is the limit.
+        // oxlint-disable-next-line no-await-in-loop
+        await task(item);
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, worker)
+  );
+};
+
+// Written to a sibling temp file and renamed into place, so a crashed build
+// never leaves a truncated clip for the next one to reuse.
+const storeClip = async (file: string, bytes: Uint8Array): Promise<void> => {
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tmp, bytes);
+  await rename(tmp, file);
+};
+
+/** Remove cached clips this build didn't use, and stray temp files. */
+const pruneClips = async (dir: string, used: Set<string>): Promise<void> => {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  const stale = entries.filter(
+    (name) =>
+      name.endsWith(".tmp") ||
+      (name.endsWith(".mp3") && !used.has(name.slice(0, -".mp3".length)))
+  );
+  await Promise.all(stale.map((name) => rm(join(dir, name), { force: true })));
+};
+
+/** A site URL path, minus the deployment base, as a path inside `distDir`. */
+const distPath = (distDir: string, base: string, url: string): string => {
+  const path = decodeURI(url);
+  const local =
+    base && path.startsWith(`${base}/`) ? path.slice(base.length) : path;
+  return join(distDir, local);
+};
+
+/** One page's plan: where its manifest goes and what it says. */
+interface PagePlan {
+  blocks: string[];
+  keys: string[];
+  manifestFile: string;
+  segments: NarrationSegment[];
+}
+
+const manifestFor = (plan: PagePlan): NarrationManifest => ({
+  blocks: plan.blocks,
+  segments: plan.segments.map((segment, index) => {
+    const audio = `${plan.keys[index] ?? ""}.mp3`;
+    return segment.block === null
+      ? { audio, text: segment.text }
+      : { audio, block: segment.block, end: segment.end, start: segment.start };
+  }),
+  version: 1,
+});
+
+/**
+ * Generate the narration for a built site in `distDir`: a clip per sentence
+ * and a manifest per page. Does nothing unless `narration.provider` is set,
+ * and warns instead of generating when the provider's key is missing (the
+ * pages then read with browser voices). `speak` replaces the gateway call.
+ */
+export const buildNarration = async (
+  project: BlumeProject,
+  distDir: string,
+  logger: NarrationLogger,
+  speak?: Speak
+): Promise<NarrationBuildResult | null> => {
+  const { narration } = project.config;
+  const { provider } = narration;
+  if (!(narration.enabled && provider)) {
+    return null;
+  }
+  const env = provider.options.apiKeyEnv;
+  if (!(speak || process.env[env] || process.env.VERCEL_OIDC_TOKEN)) {
+    logger.warn(
+      `Narration audio was not generated: ${env} is not set, so pages will be read with browser voices.`
+    );
+    return null;
+  }
+  const say = speak ?? gatewaySpeaker(provider);
+  const base = normalizeBasePath(project.config.deployment.options.base);
+
+  // Read every page first, so the log can say what generation will cost
+  // before any of it is spent.
+  const plans: PagePlan[] = [];
+  const texts = new Map<string, { lang: string; text: string }>();
+  let audioDir: string | null = null;
+  for (const file of await listHtml(distDir)) {
+    // oxlint-disable-next-line no-await-in-loop -- one page in memory at a time
+    const html = await readFile(file, "utf-8");
+    const page = html.includes("data-blume-narration-player")
+      ? readPlayerPage(html)
+      : null;
+    if (!page) {
+      continue;
+    }
+    const extract = extractNarration(page.article, htmlTree, page.cues);
+    if (!isNarratable(extract)) {
+      continue;
+    }
+    audioDir ??= distPath(distDir, base, page.audioBase);
+    const segments = segmentNarration(extract, page.lang);
+    const keys = segments.map((segment) => {
+      const key = clipKey(provider, page.lang, segment.text);
+      texts.set(key, { lang: page.lang, text: segment.text });
+      return key;
+    });
+    plans.push({
+      blocks: extract.blocks.map((block) => block.text),
+      keys,
+      manifestFile: distPath(distDir, base, page.manifest),
+      segments,
+    });
+  }
+  if (!audioDir || plans.length === 0) {
+    return { failed: 0, generated: 0, pages: 0, reused: 0 };
+  }
+
+  const cacheDir = narrationCacheDir(project.context);
+  const cached = (key: string) => join(cacheDir, `${key}.mp3`);
+  const missing = [...texts.keys()].filter((key) => !existsSync(cached(key)));
+  const reused = texts.size - missing.length;
+  if (missing.length > 0) {
+    const chars = missing.reduce(
+      (total, key) => total + (texts.get(key)?.text.length ?? 0),
+      0
+    );
+    logger.info(
+      `Generating narration: ${missing.length} new clip(s), ${chars.toLocaleString("en-US")} characters, with ${provider.options.model}`
+    );
+  }
+
+  // The AI SDK already retries a transient failure, so one that gets through
+  // (a bad key, an unknown model, a spent quota) would fail every clip after
+  // it too: stop generating at the first, and keep what's already cached.
+  const failures = new Set<string>();
+  let firstError: string | null = null;
+  await eachLimited(missing, CONCURRENCY, async (key) => {
+    const entry = texts.get(key);
+    if (!entry || firstError !== null) {
+      failures.add(key);
+      return;
+    }
+    try {
+      await storeClip(cached(key), await say(entry.text, entry.lang));
+    } catch (error) {
+      failures.add(key);
+      firstError ??= error instanceof Error ? error.message : String(error);
+    }
+  });
+  if (firstError !== null) {
+    logger.warn(
+      `Narration stopped generating after a clip failed (${firstError}). Pages missing clips will be read with browser voices.`
+    );
+  }
+
+  const target = audioDir;
+  await mkdir(target, { recursive: true });
+  const shipped = new Set<string>();
+  let pages = 0;
+  for (const plan of plans) {
+    if (plan.keys.some((key) => failures.has(key))) {
+      continue;
+    }
+    for (const key of plan.keys) {
+      if (!shipped.has(key)) {
+        shipped.add(key);
+        // oxlint-disable-next-line no-await-in-loop -- bounded by unique clips
+        await copyFile(cached(key), join(target, `${key}.mp3`));
+      }
+    }
+    // oxlint-disable-next-line no-await-in-loop -- one manifest per page
+    await mkdir(dirname(plan.manifestFile), { recursive: true });
+    // oxlint-disable-next-line no-await-in-loop
+    await writeFile(
+      plan.manifestFile,
+      `${JSON.stringify(manifestFor(plan))}\n`,
+      "utf-8"
+    );
+    pages += 1;
+  }
+
+  // Only clips for text no longer on the site go; the current site's stay,
+  // whether or not this run generated all of them.
+  await pruneClips(cacheDir, new Set(texts.keys()));
+  const generated = missing.length - failures.size;
+  logger.info(
+    `Narration: ${pages} page(s), ${generated} clip(s) generated, ${reused} reused from the cache`
+  );
+  return { failed: failures.size, generated, pages, reused };
+};