blume 0.7.0 → 1.0.0

package/src/components/layout/search/typesense.ts

@@ -31,7 +31,7 @@ export const createSearch = (opts: {
       },
     ],
   });
-  return async (query) => {
+  return async (query, options) => {
     const response = await client
       .collections<TypesenseRecord>(opts.collection)
       .documents()
@@ -40,6 +40,9 @@ export const createSearch = (opts: {
           per_page: SEARCH_LIMIT,
           q: query,
           query_by: "title,description,content",
+          // The sync marks `locale` as a facet so an i18n site can scope
+          // hosted results to the active language.
+          ...(options?.locale && { filter_by: `locale:=${options.locale}` }),
         },
         {}
       );

package/src/components/layout/toc-element.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the `<blume-toc>` custom element wrapping each "On this
+ * Client behavior for the `<blume-toc>` custom element wrapping each "On this
  * page" list. As the reader scrolls, it marks the link for the section currently
  * in view with `aria-current="location"` — styled via Tailwind `aria-[current]`
  * variants in RootLayout — giving the table of contents a live scrollspy.

package/src/components/openapi/ApiTagOperations.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { withBase } from "../islands/base-path.ts";
 import MethodBadge from "./MethodBadge.astro";
 
 // The operation-link list for one tag section of an API overview page. The
@@ -25,7 +26,7 @@ const operations = Object.values(specs[source]?.operations ?? {}).filter(
         <li>
           <a
             class="flex items-center gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
-            href={operation.route}
+            href={withBase(operation.route)}
           >
             <MethodBadge method={operation.method} />
             <span class="font-medium text-foreground text-sm">

package/src/components/openapi/Operation.astro

@@ -1,6 +1,11 @@
 ---
 import specs from "blume:openapi";
-import type { SchemaLike } from "./helpers.ts";
+import {
+  mergeParameters,
+  type ParameterLike,
+  resolveComponentRef,
+  type SchemaLike,
+} from "./helpers.ts";
 import { buildRequestSample, sampleLanguages } from "./snippets.ts";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
@@ -13,36 +18,31 @@ interface Props {
   id: string;
 }
 
-interface ParamLike {
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface RequestBodyLike {
   $ref?: string;
-  name?: string;
-  in?: string;
   description?: string;
   required?: boolean;
-  deprecated?: boolean;
-  schema?: SchemaLike;
-  example?: unknown;
+  content?: Record<string, MediaTypeLike>;
 }
 
-interface MediaTypeLike {
-  schema?: SchemaLike;
-  example?: unknown;
+interface ResponseLike {
+  $ref?: string;
+  description?: string;
+  content?: Record<string, MediaTypeLike>;
 }
 
 interface FullOperation {
   summary?: string;
   description?: string;
   deprecated?: boolean;
-  parameters?: ParamLike[];
-  requestBody?: {
-    description?: string;
-    required?: boolean;
-    content?: Record<string, MediaTypeLike>;
-  };
-  responses?: Record<
-    string,
-    { description?: string; content?: Record<string, MediaTypeLike> }
-  >;
+  parameters?: ParameterLike[];
+  requestBody?: RequestBodyLike;
+  responses?: Record<string, ResponseLike>;
 }
 
 const { source, id } = Astro.props;
@@ -50,10 +50,15 @@ const spec = specs[source];
 const ref = spec?.operations[id];
 
 const doc = (spec?.document ?? {}) as {
-  paths?: Record<string, Record<string, unknown> & { parameters?: ParamLike[] }>;
+  paths?: Record<
+    string,
+    Record<string, unknown> & { parameters?: ParameterLike[] }
+  >;
   components?: {
     schemas?: Record<string, SchemaLike>;
-    parameters?: Record<string, ParamLike>;
+    parameters?: Record<string, ParameterLike>;
+    requestBodies?: Record<string, RequestBodyLike>;
+    responses?: Record<string, ResponseLike>;
   };
   servers?: { url?: string }[];
 };
@@ -63,24 +68,26 @@ const operation = (
 ) as FullOperation | undefined;
 
 const schemas = doc.components?.schemas ?? {};
-const componentParams = doc.components?.parameters ?? {};
-const PARAM_REF = /#\/components\/parameters\/(?<name>[^/]+)$/u;
-const resolveParam = (param: ParamLike): ParamLike => {
-  if (typeof param.$ref === "string") {
-    const name = PARAM_REF.exec(param.$ref)?.groups?.name;
-    return (name && componentParams[name]) || param;
-  }
-  return param;
-};
-const params = [
-  ...(pathItem?.parameters ?? []),
-  ...(operation?.parameters ?? []),
-].map(resolveParam);
+const components = doc.components ?? {};
+const params = mergeParameters(
+  pathItem?.parameters,
+  operation?.parameters,
+  components
+);
+const requestBody = operation?.requestBody
+  ? resolveComponentRef(operation.requestBody, components, "requestBodies")
+  : undefined;
+const responses = Object.fromEntries(
+  Object.entries(operation?.responses ?? {}).map(([status, response]) => [
+    status,
+    resolveComponentRef(response, components, "responses"),
+  ])
+);
 
 const sample =
   ref && operation
     ? buildRequestSample(
-        { parameters: params, requestBody: operation.requestBody },
+        { parameters: params, requestBody },
         ref.method,
         ref.path,
         doc.servers ?? [],
@@ -109,17 +116,17 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
       <div class="grid grid-cols-1 items-start gap-x-10 gap-y-8 xl:grid-cols-[minmax(0,1fr)_minmax(0,28rem)]">
         <div>
           <ParametersTable parameters={params} schemas={schemas} />
-          {operation.requestBody && (
+          {requestBody && (
             <RequestBody
               expandAll={spec.expandSchemas}
-              requestBody={operation.requestBody}
+              requestBody={requestBody}
               schemas={schemas}
             />
           )}
           {operation.responses && (
             <Responses
               expandAll={spec.expandSchemas}
-              responses={operation.responses}
+              responses={responses}
               schemas={schemas}
             />
           )}
@@ -128,7 +135,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
           <div class="xl:sticky xl:top-24 xl:self-start">
             <RequestPanel
               languages={languages}
-              responses={operation.responses ?? {}}
+              responses={responses}
               sample={sample}
               schemas={schemas}
             />

package/src/components/openapi/RequestPanel.astro

@@ -24,7 +24,7 @@ interface Props {
 
 const { sample, languages, responses, schemas } = Astro.props;
 
-// A `.prose` wrapper gives Shiki its scoped token colours; the global style at
+// A `.prose` wrapper gives Shiki its scoped token colors; the global style at
 // the foot of this file strips the standalone code block's own box (border,
 // injected copy button, language label) so the code sits flush inside the one
 // panel border.

package/src/components/openapi/helpers.ts

@@ -39,8 +39,71 @@ export interface SchemaLike {
   [key: string]: unknown;
 }
 
+/** A permissive view of an operation parameter — only the fields we render. */
+export interface ParameterLike {
+  $ref?: string;
+  name?: string;
+  in?: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
 const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
 
+const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
+
+/**
+ * Resolve one level of `$ref` against a named `components` section
+ * (`parameters`, `requestBodies`, `responses`). Mirrors {@link resolveSchema}:
+ * an unknown ref — or one pointing into a different section — is returned
+ * as-is.
+ */
+export const resolveComponentRef = <T extends { $ref?: string }>(
+  node: T,
+  components: Record<string, unknown> | undefined,
+  section: string
+): T => {
+  if (typeof node.$ref !== "string") {
+    return node;
+  }
+  const groups = COMPONENT_REF.exec(node.$ref)?.groups;
+  if (groups?.section !== section) {
+    return node;
+  }
+  const table = components?.[section] as Record<string, T> | undefined;
+  return table?.[groups.name ?? ""] ?? node;
+};
+
+/**
+ * Path-level and operation-level parameters merged into one render list.
+ * `$ref`s resolve against `components.parameters` first; then an operation
+ * parameter overrides a path-level one with the same `name` + `in` (the
+ * OpenAPI override rule), so a re-declared parameter appears once.
+ */
+export const mergeParameters = (
+  pathParameters: ParameterLike[] | undefined,
+  operationParameters: ParameterLike[] | undefined,
+  components?: Record<string, unknown>
+): ParameterLike[] => {
+  const merged = new Map<string, ParameterLike>();
+  let position = 0;
+  for (const raw of [
+    ...(pathParameters ?? []),
+    ...(operationParameters ?? []),
+  ]) {
+    const param = resolveComponentRef(raw, components, "parameters");
+    // A nameless parameter is invalid per spec, but key it uniquely so it is
+    // still rendered rather than collapsing with other invalid entries.
+    const key = param.name ? `${param.in ?? ""}:${param.name}` : `#${position}`;
+    merged.set(key, param);
+    position += 1;
+  }
+  return [...merged.values()];
+};
+
 /** The display name of a `$ref`, e.g. `#/components/schemas/Pet` -> `Pet`. */
 export const refName = (ref: string): string =>
   REF_PATTERN.exec(ref)?.groups?.name ?? ref.split("/").at(-1) ?? ref;
@@ -166,7 +229,7 @@ export const objectProperties = (
 /** Sentinel: no explicit example is declared on a schema. */
 const NO_VALUE = Symbol("no-value");
 
-/** The declared example/default/enum for a schema, or {@link NO_VALUE}. */
+/** The declared example/const/default/enum for a schema, or {@link NO_VALUE}. */
 const explicitExample = (schema: SchemaLike): unknown => {
   if (schema.example !== undefined) {
     return schema.example;
@@ -174,6 +237,11 @@ const explicitExample = (schema: SchemaLike): unknown => {
   if (Array.isArray(schema.examples) && schema.examples.length > 0) {
     return schema.examples[0];
   }
+  // `const` is the schema's only valid value (the 3.1 discriminator idiom), so
+  // it outranks `default`/`enum` — either of those differing would be invalid.
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
   if (schema.default !== undefined) {
     return schema.default;
   }
@@ -202,8 +270,8 @@ const primitiveExample = (
 
 /**
  * Build a representative example value for a schema (honoring `example` /
- * `default` / `enum` first). A `seen` set of `$ref`s guards against the circular
- * schemas that keeping refs intact allows.
+ * `const` / `default` / `enum` first). A `seen` set of `$ref`s guards against
+ * the circular schemas that keeping refs intact allows.
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,

package/src/components/openapi/panel.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the OpenAPI request/response panels. `<blume-panel-tabs>`
+ * Client behavior for the OpenAPI request/response panels. `<blume-panel-tabs>`
  * switches the visible `[data-panel="key"]` region when a `[data-panel-tab="key"]`
  * button is clicked, and an optional `[data-panel-copy]` button copies the active
  * panel's text. Vanilla custom element — no framework, in keeping with the core

package/src/core/base-path.ts

@@ -51,6 +51,30 @@ export const withBasePath = (basePath: string, route: string): string => {
   return route === "/" ? basePath : `${basePath}${route}`;
 };
 
+/**
+ * {@link withBasePath} for the composed `deployment.base` + `basePath` stack
+ * (`/base` + `/docs` serves pages at `/base/docs/x`). The hand-written-base
+ * promise applies per layer: authors write `basePath` by hand (see
+ * `markdown/base-links.ts`), so a `/docs/x` link gains only the deployment base
+ * (`/base/docs/x`) rather than being double-prefixed to `/base/docs/docs/x`,
+ * and a route already under the full composite is returned unchanged.
+ */
+export const withComposedBasePath = (
+  deployBase: string,
+  basePath: string,
+  route: string
+): string => {
+  const composed = `${deployBase}${basePath}`;
+  if (
+    composed &&
+    isInternalPath(route) &&
+    (route === composed || route.startsWith(`${composed}/`))
+  ) {
+    return route;
+  }
+  return withBasePath(deployBase, withBasePath(basePath, route));
+};
+
 /**
  * Remove `basePath` from the front of a route (`/docs/guide` -> `/guide`,
  * `/docs` -> `/`). A route not under the base is returned unchanged. Inverse of

package/src/core/builtin-tags.ts

@@ -26,6 +26,8 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Frame",
   "GithubInfo",
   "Icon",
+  // Conditionally imported by the catch-all, but `detectUsesMath` matches any
+  // authored `<Math`, so it is always wired wherever it can appear.
   "Math",
   "Operation",
   "Panel",

package/src/core/config-input.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 
+import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
@@ -512,12 +513,46 @@ export interface AskConfig {
   suggestions?: AskSuggestion[];
 }
 
+/** What the `llms.txt`/`llms-full.txt` files include. */
+export interface LlmsTxtConfig {
+  /** Emit `llms.txt` and `llms-full.txt`. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Include the generated API reference pages (OpenAPI/AsyncAPI). Defaults to
+   * `true`; set `false` to keep a placeholder or example spec's pages out of
+   * the LLM-facing files.
+   */
+  openapi?: boolean;
+}
+
 /** AI-facing features: the Ask AI assistant and an `llms.txt` manifest. */
 export interface AiConfig {
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
-  /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`. */
-  llmsTxt?: boolean;
+  /**
+   * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
+   * The object form adds knobs for what the files include.
+   */
+  llmsTxt?: boolean | LlmsTxtConfig;
+  /**
+   * Markdown serializers for custom components in agent-facing output (the
+   * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
+   * receives the component's statically-evaluated `props` and downleveled
+   * `children` and returns replacement Markdown — or `null` to leave the JSX
+   * verbatim. A same-name entry replaces a built-in serializer.
+   *
+   * These live in `blume.config.ts` (which is executed at build time), not in
+   * `components.tsx` (which is only statically analyzed, never run).
+   *
+   * ```ts
+   * ai: {
+   *   markdownComponents: {
+   *     Chart: ({ props }) => `![${props.title}](/charts/${props.slug}.png)`,
+   *   },
+   * }
+   * ```
+   */
+  markdownComponents?: Record<string, ComponentMarkdown>;
 }
 
 // ---------------------------------------------------------------------------
@@ -701,6 +736,17 @@ export interface SeoConfig {
   sitemap?: boolean;
   /** Emit schema.org JSON-LD in each page's `<head>`. Defaults to `true`. */
   structuredData?: boolean;
+  /**
+   * X (Twitter) attribution for share cards. Handles may omit the `@`. The rest
+   * of the X card is read from the `og:*` tags, so these accounts are the only
+   * values X cannot infer.
+   */
+  x?: {
+    /** Author account (`twitter:creator`); a page can override it via `seo.x.creator` frontmatter. */
+    creator?: string;
+    /** The site's own account (`twitter:site`), e.g. `@blume`. */
+    handle?: string;
+  };
 }
 
 // ---------------------------------------------------------------------------

package/src/core/config.ts

@@ -73,8 +73,9 @@ import type { Diagnostic } from "./types.ts";
  * - `search` — search backend `provider` (`orama` by default; `pagefind`,
  *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
  *   credential block.
- * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model) and `llmsTxt`
- *   (emit `llms.txt`).
+ * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model), `llmsTxt`
+ *   (emit `llms.txt`), and `markdownComponents` (Markdown serializers for
+ *   custom components in agent-facing output).
  * - `mcp` — expose the docs as an MCP server for connecting agents.
  *
  * **SEO, feeds & analytics**

package/src/core/data.ts

@@ -93,6 +93,8 @@ export interface BlumeDataConfig {
     suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
+  /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */
+  basePath: string;
   /** `markdown.codeBlocks.theme`: light/dark Shiki themes for code surfaces. */
   codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
@@ -118,6 +120,8 @@ export interface BlumeDataConfig {
   title: string;
   /** Table-of-contents settings: whether to show it and the heading range. */
   toc: ResolvedConfig["toc"];
+  /** X (Twitter) attribution: the site's account, and a default creator. */
+  x: { creator?: string; handle?: string };
 }
 
 /**

package/src/core/frontmatter.ts

@@ -11,6 +11,7 @@ import { dump, load } from "js-yaml";
 
 type MatterInput = Parameters<typeof baseMatter>[0];
 type MatterOptions = Parameters<typeof baseMatter>[1];
+type ReadArgs = Parameters<typeof baseMatter.read>;
 type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 
 const yamlEngine = {
@@ -27,11 +28,17 @@ const withYamlEngine = <O>(options: O): O =>
     },
   }) as O;
 
+// Every helper that parses or emits YAML (`read`, `stringify`) must be
+// re-wrapped here — Object.assign copies gray-matter's own helpers, which use
+// its default `safeLoad` engine and would reintroduce the crash. `test` only
+// checks for a delimiter, so the copied original is safe.
 const matter = Object.assign(
   (input: MatterInput, options?: MatterOptions) =>
     baseMatter(input, withYamlEngine(options)),
   baseMatter,
   {
+    read: (filepath: ReadArgs[0], options?: ReadArgs[1]) =>
+      baseMatter.read(filepath, withYamlEngine(options)),
     stringify: (
       file: StringifyArgs[0],
       data: StringifyArgs[1],

package/src/core/graph.ts

@@ -87,13 +87,19 @@ const buildLocaleNavigation = (
   options: BuildContentGraphOptions,
   i18n: ResolvedI18nConfig
 ): Navigation => {
-  // Localize internal tab paths so a header tab points to its in-locale route
-  // (e.g. `/docs` -> `/fr/docs`); external paths pass through.
+  // Localize internal tab paths — the tab's own and its dropdown items' — so a
+  // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
+  // external paths pass through. Selectors are left alone: a language
+  // selector's items intentionally target specific locales.
+  const localizePath = (path: string): string =>
+    path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
   const tabs = options.navigation.tabs?.map((tab) => ({
     ...tab,
-    path: tab.path.startsWith("/")
-      ? localizeRoute(tab.path, code, i18n)
-      : tab.path,
+    items: tab.items?.map((item) => ({
+      ...item,
+      path: localizePath(item.path),
+    })),
+    path: localizePath(tab.path),
   }));
   const real = pages.filter((page) => page.locale === code);
   const localePages = localePagesFor(
@@ -109,6 +115,10 @@ const buildLocaleNavigation = (
     display: options.navigation.sidebar.display,
     featured: options.navigation.featured,
     folderMeta: options.folderMeta,
+    // The localized tree root ("/" for the hidden default, "/fr" otherwise):
+    // the tab pointing here spans the whole tree and must not be treated as a
+    // tab section.
+    localizedRoot: localizeRoute("/", code, i18n),
     // Meta files live in locale directories only under the `dir` parser
     // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
     // next to the originals and `guides/meta.ts` applies to every locale —

package/src/core/i18n-ui.ts

@@ -19,16 +19,22 @@ const uiStringsObject = z.object({
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
+      copyCode: z.string().default("Copy code"),
       copyCodex: z.string().default("Copy Codex command"),
       copyMarkdown: z.string().default("Copy as Markdown"),
       copyServerUrl: z.string().default("Copy server URL"),
       edit: z.string().default("Edit on GitHub"),
+      export: z.string().default("Export"),
+      exportEpub: z.string().default("Export to EPUB"),
+      exportPdf: z.string().default("Export to PDF"),
+      generating: z.string().default("Generating…"),
       openInChat: z.string().default("Open in chat"),
       scrollToTop: z.string().default("Scroll to top"),
     })
     .default({}),
   ask: z
     .object({
+      ai: z.string().default("AI"),
       clear: z.string().default("Clear conversation"),
       close: z.string().default("Close"),
       copy: z.string().default("Copy conversation"),
@@ -39,6 +45,29 @@ const uiStringsObject = z.object({
       send: z.string().default("Send"),
       tip: z.string().default("Tip: You can open and close chat with"),
       title: z.string().default("Ask AI"),
+      you: z.string().default("You"),
+    })
+    .default({}),
+  banner: z
+    .object({
+      dismiss: z.string().default("Dismiss announcement"),
+    })
+    .default({}),
+  changelog: z
+    .object({
+      description: z
+        .string()
+        .default(
+          "Product updates, new features, and fixes from every release."
+        ),
+      // `{version}` is replaced with the major line ("2.x") at render time.
+      showReleases: z.string().default("Show {version} releases"),
+      title: z.string().default("Changelog"),
+    })
+    .default({}),
+  content: z
+    .object({
+      diagramError: z.string().default("Could not render this diagram."),
     })
     .default({}),
   feedback: z
@@ -55,6 +84,21 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .default({}),
+  nav: z
+    .object({
+      back: z.string().default("Back"),
+      breadcrumb: z.string().default("Breadcrumb"),
+      closeNavigation: z.string().default("Close navigation"),
+      deprecated: z.string().default("deprecated"),
+      featured: z.string().default("Featured"),
+      githubRepository: z.string().default("GitHub repository"),
+      navigation: z.string().default("Navigation"),
+      primary: z.string().default("Primary"),
+      sections: z.string().default("Sections"),
+      toggleNavigation: z.string().default("Toggle navigation"),
+      toggleTheme: z.string().default("Toggle color theme"),
+    })
+    .default({}),
   notFound: z
     .object({
       description: z
@@ -68,20 +112,30 @@ const uiStringsObject = z.object({
     .object({
       lastUpdated: z.string().default("Last updated on"),
       next: z.string().default("Next"),
+      pagination: z.string().default("Pagination"),
       previous: z.string().default("Previous"),
       skipToContent: z.string().default("Skip to content"),
     })
     .default({}),
   search: z
     .object({
+      all: z.string().default("All"),
       allLanguages: z.string().default("All languages"),
+      askAi: z.string().default("Ask AI"),
+      askAiHint: z.string().default("Get an instant answer from AI"),
       button: z.string().default("Search"),
       devOnly: z
         .string()
         .default("Search is available in the production build."),
+      error: z.string().default("Something went wrong. Please try again."),
       label: z.string().default("Search docs"),
+      navigate: z.string().default("navigate"),
       noResults: z.string().default("No results found."),
+      open: z.string().default("open"),
       placeholder: z.string().default("Search documentation…"),
+      popular: z.string().default("Popular"),
+      preview: z.string().default("preview"),
+      results: z.string().default("Results"),
     })
     .default({}),
   toc: z