blume 2.0.3 → 2.1.0

package/src/deploy/platforms/vercel.ts

@@ -29,8 +29,15 @@ import {
   blumeDependencyNames,
   functionBundleVerdict,
 } from "../function-bundle.ts";
-import { buildVercelConfig } from "../redirects.ts";
-import { injectNegotiationRoutes } from "../vercel-negotiation.ts";
+import {
+  buildVercelConfig,
+  platformRedirects,
+  vercelPatternRoutes,
+} from "../redirects.ts";
+import {
+  injectNegotiationRoutes,
+  injectRedirectRoutes,
+} from "../vercel-negotiation.ts";
 import { adapterRoot, toSiteUrl } from "./paths.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 
@@ -141,6 +148,33 @@ export const emitVercelNegotiation = async (
   );
 };
 
+/**
+ * Route the pattern redirects (`/beta/:slug*`) in the adapter's Build Output
+ * config: Astro's `redirects` carry only the exact ones, since it can't
+ * prerender a pattern's pages, so the adapter never sees these.
+ */
+export const emitVercelPatternRedirects = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const routes = vercelPatternRoutes(platformRedirects(project));
+  const configPath = join(buildOutputDir(project.context), "config.json");
+  if (routes.length === 0 || !existsSync(configPath)) {
+    return;
+  }
+  const injected = injectRedirectRoutes(
+    await readFile(configPath, "utf-8"),
+    routes
+  );
+  if (injected === null) {
+    log.warn(
+      "Could not route the pattern redirects in .vercel/output/config.json, so paths they cover answer 404."
+    );
+    return;
+  }
+  await writeFile(configPath, injected, "utf-8");
+};
+
 /**
  * Vercel. A server build's Build Output tree lands at `.vercel/output` — at
  * the project root, because the adapter is handed that root up front: its
@@ -180,6 +214,7 @@ export const vercelPlatform: DeployPlatform = {
     // config is a deploy artifact and stays untouched.
     if (!isolated) {
       await emitVercelNegotiation(project, log);
+      await emitVercelPatternRedirects(project, log);
     }
     return true;
   },

package/src/deploy/redirects.ts

@@ -7,16 +7,28 @@ import {
 import { routeSetFor, servesRoute } from "../core/locale-links.ts";
 import type { RouteSet } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import {
+  compileRedirects,
+  exactFirst,
+  expandRedirect,
+  underscoreRedirect,
+  vercelRedirect,
+} from "../core/redirect-patterns.ts";
+import type { RedirectRule } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { escapeVercelSource } from "./headers.ts";
 import type { VercelHeader } from "./headers.ts";
+import type { VercelRoute } from "./vercel-negotiation.ts";
 
 /**
  * Platform redirect files for a static build. Astro already emits redirect HTML
  * (meta-refresh) pages for static output, but that's a soft client redirect.
  * These give the host a real HTTP 3xx: Netlify/Cloudflare read `_redirects`,
  * Vercel reads `vercel.json`, and `blume-redirects.json` is a structured
- * manifest for anything else (Apache/nginx rules, an edge worker).
+ * manifest for anything else (Apache/nginx rules, an edge worker). A pattern
+ * redirect (`/beta/:slug*`) gets no redirect page, since Astro can't
+ * prerender one for paths it doesn't know; each host file carries it in that
+ * host's syntax (see `core/redirect-patterns.ts`).
  */
 
 type Redirect = ResolvedConfig["redirects"][number];
@@ -99,37 +111,57 @@ export const applyBaseToPlatformRedirects = (
 
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}. The one basing every consumer must
- * share: the emitted redirect files and the Cloudflare worker-first redirect
- * exemptions both compare these paths against real served URLs.
+ * {@link applyBaseToPlatformRedirects}, exact paths ahead of patterns: hosts
+ * try rules in order, and an exact redirect wins over a pattern that also
+ * covers its path. The one basing every consumer must share: the emitted
+ * redirect files and the server wrappers all compare these paths against
+ * real served URLs.
  */
 export const platformRedirects = (project: {
   config: ResolvedConfig;
   manifest: Pick<BlumeProject["manifest"], "routes">;
 }): Redirect[] => {
   const { config } = project;
-  return applyBaseToPlatformRedirects(
-    config.redirects,
-    config.basePath,
-    config.deployment.options.base ?? "",
-    routeSetFor(project.manifest.routes)
+  return exactFirst(
+    applyBaseToPlatformRedirects(
+      config.redirects,
+      config.basePath,
+      config.deployment.options.base ?? "",
+      routeSetFor(project.manifest.routes)
+    )
   );
 };
 
 /**
- * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
- * `force` appends Netlify's `!` to each status (`301!`), so the rule wins over
- * the redirect page Astro writes at `from`; Cloudflare, which always applies
- * its rules first, rejects a line carrying it.
+ * A redirect as the entries a host file lists: itself when its path is
+ * exact, else the rules its pattern expands to, in the host's syntax.
+ */
+const hostEntries = <Entry>(
+  redirect: Redirect,
+  exact: (redirect: Redirect) => Entry,
+  pattern: (rule: RedirectRule) => Entry
+): Entry[] => {
+  const rules = expandRedirect(redirect);
+  return rules.length > 0 ? rules.map(pattern) : [exact(redirect)];
+};
+
+/**
+ * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line,
+ * a pattern as `:placeholder`s and a `*` splat the destination reads as
+ * `:splat`. `force` appends Netlify's `!` to each status (`301!`), so the rule
+ * wins over the redirect page Astro writes at `from`; Cloudflare, which always
+ * applies its rules first, rejects a line carrying it.
  */
 export const buildNetlifyRedirects = (
   redirects: Redirect[],
   force = false
 ): string =>
   `${redirects
-    .map(
-      (redirect) =>
-        `${redirect.from} ${redirect.to} ${redirect.status}${force ? "!" : ""}`
+    .flatMap((redirect) =>
+      hostEntries(redirect, (exact) => exact, underscoreRedirect).map(
+        (entry) =>
+          `${entry.from} ${entry.to} ${redirect.status}${force ? "!" : ""}`
+      )
     )
     .join("\n")}\n`;
 
@@ -145,19 +177,25 @@ interface VercelConfig {
  * alternative to the boolean `permanent`) so the configured code ships exactly:
  * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
  * from the `_redirects` file, which preserves exact codes. A `source` is a
- * `path-to-regexp` pattern, so each exact `from` path is escaped: unescaped,
- * `/c++-guide` fails the whole config and `/faq(old)` never matches.
+ * `path-to-regexp` pattern, so each literal run of a `from` path is escaped:
+ * unescaped, `/c++-guide` fails the whole config and `/faq(old)` never
+ * matches. A pattern's captures are `path-to-regexp` params.
  */
 export const buildVercelConfig = (
   redirects: Redirect[],
   headers: readonly VercelHeader[] = []
 ): string => {
   const config: VercelConfig = {
-    redirects: redirects.map((redirect) => ({
-      destination: redirect.to,
-      source: escapeVercelSource(redirect.from),
-      statusCode: redirect.status,
-    })),
+    redirects: redirects.flatMap((redirect) =>
+      hostEntries(
+        redirect,
+        (exact) => ({
+          destination: exact.to,
+          source: escapeVercelSource(exact.from),
+        }),
+        (rule) => vercelRedirect(rule, escapeVercelSource)
+      ).map((entry) => ({ ...entry, statusCode: redirect.status }))
+    ),
   };
   if (headers.length > 0) {
     config.headers = headers;
@@ -165,7 +203,36 @@ export const buildVercelConfig = (
   return `${JSON.stringify(config, null, 2)}\n`;
 };
 
-/** Structured manifest for hosts that need manual wiring. */
+/**
+ * The pattern redirects as `_redirects` entries, for the `redirects` of a
+ * Netlify server build's Frameworks API config (see
+ * {@link buildNetlifyRedirects} for the syntax).
+ */
+export const netlifyPatternRedirects = (
+  redirects: Redirect[]
+): { from: string; status: number; to: string }[] =>
+  redirects.flatMap(expandRedirect).map((rule) => ({
+    ...underscoreRedirect(rule),
+    status: rule.status,
+  }));
+
+/**
+ * The pattern redirects as Build Output API routes, for a Vercel server
+ * build: the adapter routes only the exact redirects Astro's config carries.
+ * Each matches the served path, a trailing slash optional, and fills its
+ * `Location` from numbered captures, as the adapter's own redirect routes do.
+ */
+export const vercelPatternRoutes = (redirects: Redirect[]): VercelRoute[] =>
+  compileRedirects(redirects).map(([src, location, status]) => ({
+    headers: { Location: location },
+    src,
+    status,
+  }));
+
+/**
+ * Structured manifest for hosts that need manual wiring. A pattern stays as
+ * configured (`/beta/:slug*`), for the rule it becomes to be written by hand.
+ */
 export const buildRedirectManifest = (redirects: Redirect[]): string =>
   `${JSON.stringify(
     redirects.map((redirect) => ({

package/src/deploy/vercel-negotiation.ts

@@ -399,3 +399,39 @@ export const injectNegotiationRoutes = (
   config.routes = routes;
   return `${JSON.stringify(config, null, "\t")}\n`;
 };
+
+/**
+ * Splice routes for the pattern redirects (see `vercelPatternRoutes`) into a
+ * Build Output `config.json`, in the main phase just ahead of
+ * `handle: "filesystem"`: after the exact redirects the adapter puts first,
+ * so an exact path still wins. A second pass replaces its own routes. Returns
+ * the updated JSON text, or `null` when there is nowhere safe to splice: an
+ * unparsable config, no `routes` array, or no `handle: "filesystem"` marker.
+ */
+export const injectRedirectRoutes = (
+  configText: string,
+  redirectRoutes: readonly VercelRoute[]
+): string | null => {
+  let config: { routes?: VercelRoute[] };
+  try {
+    config = JSON.parse(configText);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(config.routes)) {
+    return null;
+  }
+  const ours = new Set(redirectRoutes.map((route) => route.src));
+  const routes = config.routes.filter(
+    (route) => !(ours.has(route.src) && isString(route.headers?.Location))
+  );
+  const filesystemIndex = routes.findIndex(
+    (route) => route.handle === "filesystem"
+  );
+  if (filesystemIndex === -1) {
+    return null;
+  }
+  routes.splice(filesystemIndex, 0, ...redirectRoutes);
+  config.routes = routes;
+  return `${JSON.stringify(config, null, "\t")}\n`;
+};

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);
   };
 
   /**