blume 1.7.0 → 1.7.1

package/dist/cli/{chunk-n0nyat6g.js → chunk-ywn7t0pb.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-wd27zjcz.js";
 import {
   needsPlaygroundProxy
-} from "./chunk-xv91q4nm.js";
+} from "./chunk-r99hynxh.js";
 
 // src/core/server-features.ts
 var serverFeatures = (config) => {
@@ -27,4 +27,4 @@ var serverFeatures = (config) => {
 export { serverFeatures };
 
 //# debugId=0DFA9D31AEDBECCC64756E2164756E21
-//# sourceMappingURL=chunk-n0nyat6g.js.map
+//# sourceMappingURL=chunk-ywn7t0pb.js.map

package/dist/cli/index.js

@@ -57,20 +57,20 @@ var main = defineCommand({
   },
   subCommands: {
     add: lazyCommand(commandMeta.add, () => import("./chunk-4trphnvy.js"), "addCommand"),
-    audit: lazyCommand(commandMeta.audit, () => import("./chunk-cfw6x4rm.js"), "auditCommand"),
-    build: lazyCommand(commandMeta.build, () => import("./chunk-v2ymm99c.js"), "buildCommand"),
-    check: lazyCommand(commandMeta.check, () => import("./chunk-18tjv4f7.js"), "checkCommand"),
-    dev: lazyCommand(commandMeta.dev, () => import("./chunk-9qs6acpw.js"), "devCommand"),
-    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-tnskyrej.js"), "doctorCommand"),
-    eject: lazyCommand(commandMeta.eject, () => import("./chunk-jxkxjsc1.js"), "ejectCommand"),
-    eval: lazyCommand(commandMeta.eval, () => import("./chunk-y3g15rvv.js"), "evalCommand"),
-    init: lazyCommand(commandMeta.init, () => import("./chunk-drke6t0h.js"), "initCommand"),
+    audit: lazyCommand(commandMeta.audit, () => import("./chunk-h9ekmtz7.js"), "auditCommand"),
+    build: lazyCommand(commandMeta.build, () => import("./chunk-q56730e0.js"), "buildCommand"),
+    check: lazyCommand(commandMeta.check, () => import("./chunk-pdwg3q9g.js"), "checkCommand"),
+    dev: lazyCommand(commandMeta.dev, () => import("./chunk-mfm4sjwx.js"), "devCommand"),
+    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-52cwcqvp.js"), "doctorCommand"),
+    eject: lazyCommand(commandMeta.eject, () => import("./chunk-he2zfgah.js"), "ejectCommand"),
+    eval: lazyCommand(commandMeta.eval, () => import("./chunk-np8dmfb0.js"), "evalCommand"),
+    init: lazyCommand(commandMeta.init, () => import("./chunk-5gfw0q4j.js"), "initCommand"),
     "mcp-stdio": lazyCommand(commandMeta["mcp-stdio"], () => import("./chunk-jtb45atp.js"), "mcpStdioCommand"),
-    preview: lazyCommand(commandMeta.preview, () => import("./chunk-zr3ygrq3.js"), "previewCommand"),
-    sync: lazyCommand(commandMeta.sync, () => import("./chunk-kwx90v78.js"), "syncCommand"),
-    translate: lazyCommand(commandMeta.translate, () => import("./chunk-qq9nm3qd.js"), "translateCommand"),
-    validate: lazyCommand(commandMeta.validate, () => import("./chunk-jk1zwka1.js"), "validateCommand"),
-    version: lazyCommand(commandMeta.version, () => import("./chunk-ckh3a410.js"), "versionCommand")
+    preview: lazyCommand(commandMeta.preview, () => import("./chunk-j5f2wrj5.js"), "previewCommand"),
+    sync: lazyCommand(commandMeta.sync, () => import("./chunk-90pdhkpm.js"), "syncCommand"),
+    translate: lazyCommand(commandMeta.translate, () => import("./chunk-k0v1f8bb.js"), "translateCommand"),
+    validate: lazyCommand(commandMeta.validate, () => import("./chunk-aqjvpd03.js"), "validateCommand"),
+    version: lazyCommand(commandMeta.version, () => import("./chunk-6mq7qkve.js"), "versionCommand")
   }
 });
 loadEnvFiles(process.cwd());

package/dist/types/components/layout/nav-utils.d.ts

@@ -78,15 +78,28 @@ export interface NavVariant {
     locale: string;
     navigation: Navigation;
 }
+/**
+ * The locale whose code must not appear as a fragment URL segment: the
+ * default locale while its URL prefix is hidden. Astro's i18n routing 404s any
+ * page URL carrying that locale's code as a segment (it expects the default
+ * locale to be unprefixed), so its trees are keyed `default` instead, the same
+ * way its page routes drop the prefix. `null` when every locale is prefixed
+ * or the site is single-locale.
+ */
+export declare const hiddenDefaultLocale: (i18n: {
+    defaultLocale: string;
+    hideDefaultLocalePrefix: boolean;
+} | null) => string | null;
 /**
  * Every navigation tree the runtime data holds — the default, each locale's,
  * and each archived version's per locale — keyed the way the deferred
  * sidebar fragments' URLs are (`/blume-nav/<version>/<locale>/…`). An
  * unlocalized version tree is keyed by `""` in the data; it maps to
- * `default` here.
+ * `default` here, as does the hidden-prefix default locale's (see
+ * `hiddenDefaultLocale`), whose current tree is `data.navigation` already.
  */
 export declare const navVariants: (data: {
     navigation: Navigation;
     navigationByLocale: Record<string, Navigation>;
     navigationByVersion: Record<string, Record<string, Navigation>>;
-}) => NavVariant[];
+}, hiddenDefault?: string | null) => NavVariant[];

package/dist/types/core/config-input.d.ts

@@ -628,6 +628,13 @@ export interface AskConfig {
      * limiting, and streaming. Accepts an absolute URL or root-relative path.
      */
     endpoint?: string;
+    /**
+     * Static request headers sent to the provider on every call — a
+     * caller-identifying header for a shared backend, for example. Values are
+     * written into the generated route as literals, so keep secrets in
+     * `apiKeyEnv` rather than here.
+     */
+    headers?: Record<string, string>;
     /**
      * Extra system-prompt text appended to the built-in instructions — use it
      * for identity, language, or tone. The built-in grounding behavior (answer

package/dist/types/core/schema.d.ts

@@ -336,6 +336,7 @@ declare const aiConfigSchema: z.ZodObject<{
         baseUrl: z.ZodOptional<z.ZodURL>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         endpoint: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         instructions: z.ZodOptional<z.ZodString>;
         model: z.ZodDefault<z.ZodString>;
         provider: z.ZodDefault<z.ZodEnum<{
@@ -577,6 +578,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             baseUrl: z.ZodOptional<z.ZodURL>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             endpoint: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             instructions: z.ZodOptional<z.ZodString>;
             model: z.ZodDefault<z.ZodString>;
             provider: z.ZodDefault<z.ZodEnum<{

package/docs/08-faq.mdx

@@ -160,3 +160,24 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
 :::warning[Version-pinned]
 The patch targets a specific oxfmt build — its diff references a file whose name is hashed per release (`dist/markdown-*.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
 :::
+
+## Why does Knip report my `blume.config.ts` dependencies as unused?
+
+[Knip](https://knip.dev) only follows imports from files it knows are entry points, and it learns those from its built-in plugins. There is no Blume plugin yet, and Knip's Astro plugin doesn't switch on either: it looks for `astro` in your own `package.json`, but a Blume project depends on `blume`, and the generated `.blume/` Astro project is gitignored, so Knip never sees it. Nothing references `blume.config.ts`, so any package it imports gets reported as unused.
+
+Register the files Blume loads from your project root as entries. In `knip.json`:
+
+```json knip.json
+{
+  "entry": [
+    "blume.config.{ts,mjs,js}",
+    "components.{ts,tsx}",
+    "islands/**/*.{ts,tsx}",
+    "pages/**/*"
+  ]
+}
+```
+
+In a monorepo, put the same `entry` list under the docs workspace in `workspaces` instead. Drop any line for a convention you don't use — `components.ts` for [component overrides](/docs/configuration/customization#component-overrides), `islands/` for [interactive islands](/docs/configuration/customization#interactive-islands), and `pages/` for [custom pages](/docs/configuration/customization#custom-pages) (adjust the last one if you've changed `content.pages`).
+
+Knip can only follow real imports. A package that's only named inside a string — say, an [Astro integration](/docs/configuration/customization#astro-integrations) that calls `injectScript("page", "import('some-package')")` — still needs an `ignoreDependencies` entry.

package/docs/configuration/ask-ai.mdx

@@ -166,6 +166,22 @@ ai: {
 
 Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point at a different env var or proxy.
 
+To send static request headers with every call — a caller-identifying header for a shared backend, say, so its own observability or rate limiting can tell your docs apart from other traffic — set `headers`. It works on every backend, including the gateway:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "openai-compatible",
+    baseUrl: "https://llm.internal.example.com/v1",
+    apiKeyEnv: "INTERNAL_LLM_API_KEY",
+    headers: { "X-Caller-Id": "docs" },
+  },
+}
+```
+
+The values are written into the generated route as-is, so keep secrets in `apiKeyEnv` rather than in `headers`. The API key's `Authorization` header is applied first, so a custom header can't displace it.
+
 :::note
 **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
 :::

package/docs/content/sources.mdx

@@ -163,7 +163,7 @@ A read token for a private dataset comes from the `SANITY_TOKEN` environment var
 
 ## Notion
 
-The built-in `notion` source turns a Notion database into a collection: each row becomes a page, its properties become frontmatter, and its block tree becomes MDX. Callouts, toggles, columns, and code blocks map to the matching Blume components. `@notionhq/client` (v5 or later) is an optional peer dependency; Blume reads the database through its first data source.
+The built-in `notion` source turns a Notion database into a collection: each row becomes a page, its properties become frontmatter, and its block tree becomes MDX. Callouts, toggles, columns, and code blocks map to the matching Blume components. Video blocks become a `<YouTube>` embed when they hold a YouTube link and a `<video>` player otherwise, with the block's caption as a `<Frame>` caption either way; a link to a video page rather than a media file (a Vimeo or Loom URL, say) is reported as a warning instead of embedded. `@notionhq/client` (v5 or later) is an optional peer dependency; Blume reads the database through its first data source.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -185,7 +185,7 @@ export default defineConfig({
 });
 ```
 
-The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build. API calls are paced through a small request pool (3 at a time, matching Notion's per-integration rate limit) so databases with hundreds of pages import without tripping `429` responses; set `concurrency` on the source to tune it.
+The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image and video URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS asset never rots a static build. API calls are paced through a small request pool (3 at a time, matching Notion's per-integration rate limit) so databases with hundreds of pages import without tripping `429` responses; set `concurrency` on the source to tune it.
 
 ## Preview and sync
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/ask.ts

@@ -7,16 +7,31 @@ import type { AskAiConfig } from "../core/schema.ts";
  * AI SDK's OpenAI-compatible provider.
  */
 export type AskBackend =
-  | { kind: "gateway"; model: string }
-  | { apiKeyEnv: string; kind: "openrouter"; model: string }
+  | { headers?: AskHeaders; kind: "gateway"; model: string }
+  | {
+      apiKeyEnv: string;
+      headers?: AskHeaders;
+      kind: "openrouter";
+      model: string;
+    }
   | {
       apiKeyEnv: string;
       baseUrl: string;
+      headers?: AskHeaders;
       kind: "openai-compatible";
       model: string;
       name: string;
     };
 
+/**
+ * Static request headers (`ai.ask.headers`) every backend forwards to its
+ * provider factory. Every provider Blume generates against accepts the same
+ * `headers` option, so the map travels unchanged; the OpenAI-compatible
+ * provider applies them after the `Authorization` header it derives from the
+ * API key, so a custom header can't displace auth.
+ */
+export type AskHeaders = Record<string, string>;
+
 interface AskPreset {
   apiKeyEnv: string;
   baseUrl?: string;
@@ -69,17 +84,28 @@ const ASK_PRESETS: AskPresetRegistry = {
 
 const DEFAULT_MODEL = "openai/gpt-5.5";
 
+/**
+ * The `headers` field every backend variant shares. An empty map is dropped so
+ * the generated route only carries a `headers` option when there is something
+ * to send.
+ */
+const askHeadersField = (ask?: AskAiConfig): { headers?: AskHeaders } =>
+  ask?.headers && Object.keys(ask.headers).length > 0
+    ? { headers: ask.headers }
+    : {};
+
 /** Resolve the `ai.ask` config into the backend the endpoint is built against. */
 export const resolveAskBackend = (ask?: AskAiConfig): AskBackend => {
   const provider = ask?.provider ?? "gateway";
   const model = ask?.model ?? DEFAULT_MODEL;
+  const headers = askHeadersField(ask);
   if (provider === "gateway") {
-    return { kind: "gateway", model };
+    return { ...headers, kind: "gateway", model };
   }
   const preset = ASK_PRESETS[provider];
   const apiKeyEnv = ask?.apiKeyEnv ?? preset?.apiKeyEnv ?? "API_KEY";
   if (provider === "openrouter") {
-    return { apiKeyEnv, kind: "openrouter", model };
+    return { apiKeyEnv, ...headers, kind: "openrouter", model };
   }
   // `llmgateway`, `inkeep`, and the generic `openai-compatible` provider all
   // stream through the AI SDK's OpenAI-compatible provider. The schema requires
@@ -87,6 +113,7 @@ export const resolveAskBackend = (ask?: AskAiConfig): AskBackend => {
   return {
     apiKeyEnv,
     baseUrl: ask?.baseUrl ?? preset?.baseUrl ?? "",
+    ...headers,
     kind: OPENAI_COMPATIBLE,
     model,
     name: preset?.name ?? OPENAI_COMPATIBLE,

package/src/astro/generate.ts

@@ -2339,6 +2339,7 @@ export const generateRuntime = async (
       changelogIndexTemplate({
         exportEpub,
         exportPdf,
+        mathEnabled: usesMath,
         needsReact,
         staged: hasStaged,
       })

package/src/astro/templates.ts

@@ -1080,16 +1080,23 @@ export const askEndpointTemplate = (
   ];
   let setup = "";
   let modelExpr = JSON.stringify(backend.model);
+  // `ai.ask.headers`, inlined as literals: every provider factory below takes
+  // the same `headers` option, so one line serves all three.
+  const headersField = backend.headers
+    ? `\n  headers: ${JSON.stringify(backend.headers)},`
+    : "";
   if (backend.kind === "gateway") {
-    setup = `\nconst gateway = createGateway({ apiKey: getSecret("AI_GATEWAY_API_KEY") });\n`;
+    setup = `\nconst gateway = createGateway({
+  apiKey: getSecret("AI_GATEWAY_API_KEY"),${headersField}
+});\n`;
     modelExpr = `gateway(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openrouter") {
     imports.push(
       'import { createOpenRouter } from "@openrouter/ai-sdk-provider";'
     );
-    setup = `\nconst openrouter = createOpenRouter({ apiKey: getSecret(${JSON.stringify(
-      backend.apiKeyEnv
-    )}) });\n`;
+    setup = `\nconst openrouter = createOpenRouter({
+  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),${headersField}
+});\n`;
     modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openai-compatible") {
     imports.push(
@@ -1097,7 +1104,7 @@ export const askEndpointTemplate = (
     );
     setup = `\nconst provider = createOpenAICompatible({
   apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
-  baseURL: ${JSON.stringify(backend.baseUrl)},
+  baseURL: ${JSON.stringify(backend.baseUrl)},${headersField}
   name: ${JSON.stringify(backend.name)},
 });\n`;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
@@ -1692,15 +1699,22 @@ export function GET({ props }: { props: { section: string } }) {
  * every collapsed section on every page. Ids are `navGroupIds` over the full
  * tree, the same ids the pages' sidebars use; the `version`/`locale`
  * segments pick the navigation variant (`current`/`default` for the
- * unversioned, unlocalized tree). Rendered with no current route — a
- * section that isn't on the active path has no active row by definition.
+ * unversioned, unlocalized tree, and `default` again for the default locale
+ * while its URL prefix is hidden: Astro's i18n routing 404s a page URL that
+ * carries the default locale's code as a segment). Rendered with no current
+ * route — a section that isn't on the active path has no active row by
+ * definition.
  */
 export const navFragmentTemplate = (): string =>
   `---
 // Generated by Blume. Do not edit.
 import NavTree from "blume/components/layout/NavTree.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
-import { navGroupIds, navVariants } from "blume/components/layout/nav-utils.ts";
+import {
+  hiddenDefaultLocale,
+  navGroupIds,
+  navVariants,
+} from "blume/components/layout/nav-utils.ts";
 import type { NavNode } from "blume/core/types.ts";
 import data from "blume:data";
 
@@ -1711,15 +1725,16 @@ export const partial = true;
 // Only imports are in scope here (Astro hoists getStaticPaths), which is why
 // the variant walk lives in nav-utils.
 export function getStaticPaths() {
-  return navVariants(data).flatMap(({ locale, navigation, version }) =>
-    [...navGroupIds(navigation.sidebar)]
-      .filter(([node]) => (node.display ?? "flat") !== "flat")
-      .map(([, id]) => ({ params: { id, locale, version } }))
+  return navVariants(data, hiddenDefaultLocale(data.config.i18n)).flatMap(
+    ({ locale, navigation, version }) =>
+      [...navGroupIds(navigation.sidebar)]
+        .filter(([node]) => (node.display ?? "flat") !== "flat")
+        .map(([, id]) => ({ params: { id, locale, version } }))
   );
 }
 
 const { id, locale, version } = Astro.params;
-const variant = navVariants(data).find(
+const variant = navVariants(data, hiddenDefaultLocale(data.config.i18n)).find(
   (entry) => entry.version === version && entry.locale === locale
 );
 const ids = variant
@@ -1933,37 +1948,22 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 </ReferenceLayout>
 `;
 
-export const catchAllPageTemplate = (options: {
-  exportEpub: boolean;
-  exportPdf: boolean;
-  mathEnabled: boolean;
-  /**
-   * Whether the sidebar defers collapsed sections to prerendered fragments
-   * (see `navFragmentTemplate`); true when some group renders as a
-   * disclosure or a drill-in panel.
-   */
-  navFragments?: boolean;
-  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
-  needsReact: boolean;
-}): string => {
-  const mathImport = options.mathEnabled
+/**
+ * The component map every rendered entry body receives via
+ * `<Content components={...} />`: Blume's content components, `<Math>` when
+ * math is enabled, the island wrappers, and the user's `mdxComponents`
+ * overrides. Shared by the catch-all page and the changelog index so a
+ * `:::` directive (compiled to `<Callout>`) or an explicit `<Steps>` renders
+ * wherever an entry is rendered — an MDX body throws "Expected component
+ * `X` to be defined" the moment a page renders it without this map.
+ */
+const contentComponentsSource = (mathEnabled: boolean) => {
+  const mathImport = mathEnabled
     ? 'import Math from "blume/components/content/Math.astro";\n'
     : "";
-  const mathEntry = options.mathEnabled ? "Math,\n  " : "";
-  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
-  const clientData = options.needsReact
-    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
-    : "";
-
-  return `---
-// Generated by Blume. Do not edit.
-import { getEntry, render } from "astro:content";
-import type { CollectionKey } from "astro:content";
-import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
-import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
-import { resolveSlot } from "blume/components/layout/overrides.ts";
-import Accordion from "blume/components/content/Accordion.astro";
+  const mathEntry = mathEnabled ? "Math,\n  " : "";
+  return {
+    imports: `import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
 import AutoTypeTable from "blume/components/content/AutoTypeTable.astro";
 import Badge from "blume/components/content/Badge.astro";
@@ -2003,19 +2003,8 @@ import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
-import { islandComponents } from "../generated/islands.ts";
-import data from "blume:data";
-
-const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
-const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
-
-// Docs content is file-based and always prerendered, even in server output
-// (where only endpoints like /api/ask render on demand). Without this, server
-// builds would render this route on demand and ignore getStaticPaths, leaving
-// the entry id undefined.
-export const prerender = true;
-
-const components = {
+import { islandComponents } from "../generated/islands.ts";`,
+    map: `{
   Accordion,
   AccordionItem,
   ApiOverview,
@@ -2052,8 +2041,52 @@ const components = {
   YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
+}`,
+  };
 };
 
+export const catchAllPageTemplate = (options: {
+  exportEpub: boolean;
+  exportPdf: boolean;
+  mathEnabled: boolean;
+  /**
+   * Whether the sidebar defers collapsed sections to prerendered fragments
+   * (see `navFragmentTemplate`); true when some group renders as a
+   * disclosure or a drill-in panel.
+   */
+  navFragments?: boolean;
+  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
+  needsReact: boolean;
+}): string => {
+  const { imports: componentImports, map: componentMap } =
+    contentComponentsSource(options.mathEnabled);
+  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
+  const clientData = options.needsReact
+    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
+    : "";
+
+  return `---
+// Generated by Blume. Do not edit.
+import { getEntry, render } from "astro:content";
+import type { CollectionKey } from "astro:content";
+import RootLayout from "blume/components/layout/RootLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
+${componentImports}
+import data from "blume:data";
+
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
+// Docs content is file-based and always prerendered, even in server output
+// (where only endpoints like /api/ask render on demand). Without this, server
+// builds would render this route on demand and ignore getStaticPaths, leaving
+// the entry id undefined.
+export const prerender = true;
+
+const components = ${componentMap};
+
 export function getStaticPaths() {
   return data.routes.map((route) => ({
     params: { slug: route.path === "/" ? undefined : route.path.slice(1) },
@@ -2324,7 +2357,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   exportEpub={${options.exportEpub}}${
     options.navFragments
       ? `
-  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n ? locale : "default"}\`)}`
+  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
       : ""
   }
   openInChat={data.config.openInChat}
@@ -2355,6 +2388,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 export const changelogIndexTemplate = (options: {
   exportEpub: boolean;
   exportPdf: boolean;
+  mathEnabled: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
   needsReact: boolean;
   /** Whether a `staged` collection exists (non-filesystem changelog sources). */
@@ -2368,6 +2402,8 @@ export const changelogIndexTemplate = (options: {
   const stagedSpread = options.staged
     ? '\n  ...(await getCollection("staged")),'
     : "";
+  const { imports: componentImports, map: componentMap } =
+    contentComponentsSource(options.mathEnabled);
 
   return `---
 // Generated by Blume. Do not edit.
@@ -2377,11 +2413,19 @@ import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { resolveDateFormatOptions } from "blume/core/date-format.ts";
-import { layoutOverrides } from "../generated/components.ts";
+${componentImports}
 import data from "blume:data";
 
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
 export const prerender = true;
 
+// Entry bodies are MDX rendered outside the catch-all, so they need the same
+// component map: a \`:::\` callout or \`<Steps>\` in a release note otherwise
+// throws "Expected component ... to be defined" at build time.
+const components = ${componentMap};
+
 const entryDate = (entry: {
   data: { date?: string | null; changelog?: { date?: string | null } | null };
 }) => entry.data.date ?? entry.data.changelog?.date ?? null;
@@ -2580,7 +2624,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content />
+            <Content components={components} />
           </Update>
         ))}
         {majorGroups.slice(1).map((group) => (
@@ -2591,7 +2635,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
           >
             {group.items.map(({ Content, href, id, label, date, tags }) => (
               <Update description={date} href={href} id={id} label={label} tags={tags}>
-                <Content />
+                <Content components={components} />
               </Update>
             ))}
           </section>
@@ -2611,7 +2655,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       <div class="not-prose mt-8">
         {items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content />
+            <Content components={components} />
           </Update>
         ))}
       </div>

package/src/components/content/YouTube.astro

@@ -20,7 +20,7 @@ const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
 
 {
   src && (
-    <div class="not-prose my-6 aspect-video overflow-hidden rounded-blume border border-border bg-muted/30">
+    <div class="not-prose my-6 aspect-video w-full overflow-hidden rounded-blume border border-border bg-muted/30">
       <iframe
         allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
         allowfullscreen

package/src/components/layout/Header.astro

@@ -150,7 +150,7 @@ const ctaClass = [
 // so the offset can't drift while open, and re-measure when a banner dismiss or
 // a resize/rotation moves the header. Crossing into the desktop breakpoint
 // (64rem, Tailwind `lg`) closes the drawer so the scroll lock can't outlive it.
-const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}d.style.overflow=open?"hidden":"";}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");d.style.overflow="";}else{dr();}});})();`;
+const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");}else{dr();}});})();`;
 ---
 
 <header

package/src/components/layout/Search.astro

@@ -445,6 +445,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.dialog.addEventListener("keydown", (event) =>
           this.onKeydown(event)
         );
+        this.dialog.addEventListener("close", () => this.unlockPageScroll());
         this.dialog.addEventListener("click", (event) => {
           if (event.target === this.dialog) {
             this.dialog.close();
@@ -454,6 +455,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       disconnectedCallback() {
         document.removeEventListener("keydown", this.#onDocumentKeydown);
+        this.unlockPageScroll();
       }
 
       isField(target: EventTarget | null): boolean {
@@ -473,6 +475,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           return;
         }
         this.dialog.showModal();
+        this.lockPageScroll();
         this.input.focus();
         this.input.select();
         if (!this.loaded) {
@@ -498,6 +501,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.render();
       }
 
+      lockPageScroll() {
+        document.documentElement.setAttribute("data-blume-search-dialog-open", "");
+      }
+
+      unlockPageScroll() {
+        document.documentElement.removeAttribute("data-blume-search-dialog-open");
+      }
+
       onKeydown(event: KeyboardEvent) {
         if (event.key === "ArrowDown") {
           event.preventDefault();