blume 2.0.1 → 2.0.3

package/dist/types/deploy/redirects.d.ts

@@ -1,3 +1,5 @@
+import type { RouteSet } from "../core/locale-links.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { VercelHeader } from "./headers.ts";
 /**
@@ -15,37 +17,51 @@ type Redirect = ResolvedConfig["redirects"][number];
  * - `from` gains only `basePath`. Astro builds the match pattern with
  *   `deployment.base` already applied (`getPattern(segments, config.base)`), so
  *   adding it here would serve the redirect at `{base}{base}/from`.
- * - `to` gains the full `{deployment.base}{basePath}` stack. Astro resolves a
- *   destination that matches a known route by regenerating it from that route's
- *   segments, which carry no base — and passes an unmatched destination through
- *   verbatim. Neither path prepends `base`, so a root-relative `to` escapes the
- *   base entirely (withastro/astro#7774, still the behavior in Astro 7).
+ * - `to` gains the full `{deployment.base}{basePath}` stack, or the deployment
+ *   base alone for a public file (see {@link baseRedirectTarget}). Astro
+ *   resolves a destination that matches a known route by regenerating it from
+ *   that route's segments, which carry no base — and passes an unmatched
+ *   destination through verbatim. Neither path prepends `base`, so a
+ *   root-relative `to` escapes the base entirely (withastro/astro#7774, still
+ *   the behavior in Astro 7).
  *
- * Both sides are authored as if mounted at root; external `to` URLs pass
- * through. Idempotent, so a hand-written base isn't doubled.
+ * Both sides are authored as if mounted at root; `routes` (the served page
+ * routes, carrying `basePath`) tell a dotted page route like `/releases/v1.2`
+ * from a file. Idempotent, so a hand-written base isn't doubled.
  */
-export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath: string, deployBase: string) => Redirect[];
+export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => Redirect[];
 /**
  * Base a redirect for the host platform files below. Unlike Astro's config,
- * these are matched against the real served URL, so both sides carry the full
- * `{deployment.base}{basePath}` stack.
+ * these are matched against the real served URL, so `from` carries the full
+ * `{deployment.base}{basePath}` stack, and so does `to` unless it names a
+ * public file (see {@link baseRedirectTarget}).
  */
-export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string) => Redirect[];
+export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => Redirect[];
 /**
  * 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.
  */
-export declare const platformRedirects: (config: ResolvedConfig) => Redirect[];
-/** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
-export declare const buildNetlifyRedirects: (redirects: Redirect[]) => string;
+export declare const platformRedirects: (project: {
+    config: ResolvedConfig;
+    manifest: Pick<BlumeProject["manifest"], "routes">;
+}) => Redirect[];
+/**
+ * `_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.
+ */
+export declare const buildNetlifyRedirects: (redirects: Redirect[], force?: boolean) => string;
 /**
  * `vercel.json` contents with a `redirects` array, and a `headers` array when
  * header rules are given (see `buildVercelHeaders`). Uses `statusCode` (Vercel's
  * 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.
+ * 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.
  */
 export declare const buildVercelConfig: (redirects: Redirect[], headers?: readonly VercelHeader[]) => string;
 /** Structured manifest for hosts that need manual wiring. */

package/dist/types/deploy/vercel-negotiation.d.ts

@@ -101,9 +101,10 @@ export declare const buildNegotiationRoutes: (routePaths: readonly string[], hom
  * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
- * nothing. Returns the updated JSON
+ * nothing. With `svgAssets`, a main-phase route also sandboxes the SVGs a
+ * content source downloaded (see {@link svgAssetRoute}). Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
  */
-export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[]) => string | null;
+export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean) => string | null;

package/dist/types/markdown/directives.d.ts

@@ -0,0 +1,62 @@
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+export interface DirectiveNode extends MdastNode {
+    attributes?: Record<string, string | null | undefined> | null;
+    children?: MdastNode[] | null;
+    name: string;
+    position?: {
+        start?: {
+            offset?: number;
+        };
+        end?: {
+            offset?: number;
+        };
+    };
+}
+/**
+ * The visitor-context slice the directive visitors use. `source` is the page
+ * the directive offsets index into; without it the literal fallback rebuilds
+ * a directive from its node instead. `parent` walks up to an enclosing
+ * container directive, which renders the directives inside it itself.
+ */
+interface DirectiveVisitorContext extends MdastVisitorContext {
+    parent?: (node: MdastNode) => MdastNode | undefined;
+    source?: string;
+}
+/** Directive names that map directly onto a Callout type. */
+export declare const CALLOUT_TYPES: ReadonlySet<string>;
+/** Friendly aliases for the canonical Callout types. */
+interface CalloutAliases {
+    [alias: string]: string;
+}
+export declare const CALLOUT_ALIASES: Readonly<CalloutAliases>;
+/** Resolve a directive name to a Callout type, or `null` if it is not one. */
+export declare const calloutTypeFor: (name: string) => string | null;
+/**
+ * A text or leaf directive exactly as the author wrote it. The slice by
+ * offsets is the exact text — `[label]` and `{attrs}` included — and is
+ * trusted only when it opens with the directive's own marker and name;
+ * content an `<include>` spliced in carries no offsets into this page, so it
+ * is rebuilt from the node instead.
+ */
+export declare const directiveSource: (node: DirectiveNode, marker: string, source: string) => string;
+/**
+ * Satteri MDAST plugin for directives. Container directives (`:::note`,
+ * `:::warning`, `:::tip`, …) map onto Blume's `<Callout>` component, and any
+ * other container renders its body between its literal fence lines (see
+ * {@link renderContainer}).
+ *
+ * Blume handles no text (`:name`) or leaf (`::name`) directives, and prose is
+ * full of text that parses as one — `16:9`, `10:30am`, `og:image`,
+ * `pets:read` — so both render as the literal source the author wrote instead
+ * of vanishing.
+ */
+export declare const directiveToCalloutPlugin: () => {
+    containerDirective(node: DirectiveNode, ctx: DirectiveVisitorContext): void;
+    leafDirective: (node: DirectiveNode, ctx: DirectiveVisitorContext) => void;
+    name: string;
+    options: {
+        position: boolean;
+    };
+    textDirective: (node: DirectiveNode, ctx: DirectiveVisitorContext) => void;
+};
+export {};

package/dist/types/markdown/features.d.ts

@@ -19,3 +19,24 @@ export declare const MDX_FEATURES: {
     subscript: true;
     superscript: true;
 };
+/**
+ * The feature sets for a page body, once its front matter is off. Astro reads
+ * a page's front matter itself and hands the renderer the body alone, and the
+ * search extractor strips it first too — so front matter parsing is off here:
+ * left on, a body that opens with a `---` rule read everything up to the next
+ * `---` line as front matter and dropped it from the page.
+ */
+export declare const MARKDOWN_BODY_FEATURES: {
+    frontmatter: false;
+    subscript: true;
+    superscript: true;
+};
+export declare const MDX_BODY_FEATURES: {
+    frontmatter: false;
+    directive: true;
+    math: {
+        singleDollarTextMath: false;
+    };
+    subscript: true;
+    superscript: true;
+};

package/dist/types/markdown/mdast.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Minimal structural types and node builders for the (alpha) Satteri MDAST
+ * plugin API. We model only what Blume's plugins read and construct; the full
+ * types live in `satteri`, a transitive dependency. Plugins are bridged to
+ * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
+ */
+/**
+ * A property value on an MDAST node: primitives, nested nodes, and lists of
+ * either. Covers everything Blume's plugins read or build (positions, data
+ * flags, attribute lists) without admitting functions or class instances.
+ */
+export type MdastValue = string | number | boolean | null | undefined | MdastValue[] | {
+    [key: string]: MdastValue;
+};
+/**
+ * The visitor context Blume's plugins use to mutate the tree. A list of
+ * nodes takes the replaced node's place in order.
+ */
+export interface MdastVisitorContext {
+    replaceNode: (node: MdastNode, replacement: MdastNode | MdastNode[]) => void;
+}
+/** Any MDAST node, keyed loosely since we build a small subset by hand. */
+export interface MdastNode {
+    type: string;
+    [key: string]: MdastValue;
+}
+/** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
+export declare const jsxAttribute: (name: string, value?: string | null) => {
+    name: string;
+    type: string;
+    value: string | null;
+};
+type JsxAttribute = ReturnType<typeof jsxAttribute>;
+/** Build a block-level MDX JSX element (`<Name>…</Name>`). */
+export declare const jsxFlowElement: (name: string, attributes: JsxAttribute[], children: MdastValue[]) => {
+    attributes: {
+        name: string;
+        type: string;
+        value: string | null;
+    }[];
+    children: MdastValue[];
+    name: string;
+    type: string;
+};
+/** Build an inline MDX JSX element (phrasing context). */
+export declare const jsxTextElement: (name: string, attributes: JsxAttribute[], children?: MdastValue[]) => {
+    attributes: {
+        name: string;
+        type: string;
+        value: string | null;
+    }[];
+    children: MdastValue[];
+    name: string;
+    type: string;
+};
+/** Build a fenced code block node, optionally with a fence-meta string. */
+export declare const codeBlock: (lang: string, value: string, meta?: string | null) => {
+    lang: string;
+    meta: string | null;
+    type: string;
+    value: string;
+};
+export {};

package/dist/types/openapi/asyncapi.d.ts

@@ -34,7 +34,8 @@ export interface AsyncApiChannelObject {
     messages?: Record<string, AsyncApiRefLike>;
     parameters?: Record<string, AsyncApiRefLike>;
     servers?: AsyncApiRefLike[];
-    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+    bindings?: Record<string, AsyncApiSpecValue>;
     [key: string]: AsyncApiSpecValue;
 }
 /** A permissive view of an AsyncAPI 3.x operation — only the fields we render. */
@@ -51,7 +52,8 @@ export interface AsyncApiOperationObject {
     }[];
     security?: AsyncApiRefLike[];
     messages?: AsyncApiRefLike[];
-    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+    bindings?: Record<string, AsyncApiSpecValue>;
     [key: string]: AsyncApiSpecValue;
 }
 /** A permissive view of an AsyncAPI 3.x server object. */

package/dist/types/openapi/model.d.ts

@@ -1,5 +1,5 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
-import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+import type { AsyncApiAction, AsyncApiDocument, AsyncApiSpecValue } from "./asyncapi.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 export { slugify } from "./references.ts";
@@ -46,7 +46,10 @@ export interface ApiOperationRef {
     /** The channel the operation acts on (AsyncAPI only). */
     channelId?: string;
 }
-/** A tag/section, in first-seen order. */
+/**
+ * A tag/section: the spec's declared tags in their declared order, then any
+ * undeclared tag an operation uses, in first-seen order.
+ */
 export interface ApiTagRef {
     slug: string;
     name: string;
@@ -114,6 +117,15 @@ export interface SpecAddresses {
  * live endpoint stands in.
  */
 export declare const specAddresses: (spec: ApiSpecData) => SpecAddresses;
+/**
+ * A server URL template — an OpenAPI `servers[].url`, an AsyncAPI server's
+ * `host` or `pathname` — with each `{variable}` replaced by the `default` its
+ * `variables` map declares. Code samples, the playground's Send, and the
+ * proxy allowlist all need a real address, and
+ * `https://{region}.api.example.com` is not one. A variable the map doesn't
+ * define with a default (invalid per both specs) stays templated.
+ */
+export declare const withServerDefaults: (template: string, variables: AsyncApiSpecValue) => string;
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
  * different names onto one value — any two punctuation-only tags (`!!!`,
@@ -142,16 +154,18 @@ export interface ExtractedOperations extends CollectedOperations {
 }
 /**
  * The collector behind both extractors (OpenAPI here, AsyncAPI in
- * `asyncapi.ts`): first-seen tag ordering, key de-duplication (a repeated key
- * gains its method/action as a suffix), and the shared route template — so
- * URL shape and slug rules can never drift between the two spec kinds.
+ * `asyncapi.ts`): declared-then-first-seen tag ordering, key de-duplication
+ * (a repeated key gains its method/action as a suffix), and the shared route
+ * template — so URL shape and slug rules can never drift between the two spec
+ * kinds.
  */
 export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
  * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item), so missing operations aren't silent.
+ * anything skipped (a `$ref` path item, webhooks), so missing operations
+ * aren't silent.
  */
 export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */

package/dist/types/search/sync/algolia.d.ts

@@ -9,6 +9,8 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked.
+ * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
+ * the site declared itself, so the dialog's locale and version filters match.
  */
 export declare const syncAlgolia: (records: SearchRecord[], config: AlgoliaSyncConfig) => Promise<void>;

package/docs/01-quickstart.mdx

@@ -23,11 +23,12 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
     npx blume init
     ```
 
-    On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx` (`pnpm dlx --allow-build=esbuild blume init`): pnpm 12 refuses to run the install script of esbuild, which Astro depends on, unless you approve it. Inside an existing pnpm workspace, add `allowBuilds: { esbuild: true }` to the workspace's `pnpm-workspace.yaml`; `init` reminds you. With Yarn 2 or later, `init` writes a `.yarnrc.yml` that switches Yarn to a `node_modules` install, which Blume needs; on Yarn 1, run `npx blume init`.
+    On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx` (`pnpm dlx --allow-build=esbuild blume init`): pnpm 12 refuses to run the install script of esbuild, which Astro depends on, unless you approve it. Inside an existing pnpm workspace, the new folder must be listed under the workspace's `packages` (pnpm installs nothing else, so `init` skips the install until it is), and esbuild needs `allowBuilds: { esbuild: true }` in the workspace's `pnpm-workspace.yaml`; `init` reminds you of both. With Yarn 2 or later, `init` writes a `.yarnrc.yml` that switches Yarn to a `node_modules` install, which Blume needs; on Yarn 1, run `npx blume init`.
 
     ```txt
     docs/
       index.mdx
+    .gitignore
     blume.config.ts
     package.json
     ```
@@ -52,7 +53,7 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
   </Step>
 </Steps>
 
-Adding Blume to a project that already has a `package.json`? `blume init` leaves existing files alone, so add `"dev": "blume dev"` and `"build": "blume build"` to its scripts, or run `npx blume dev` directly.
+Adding Blume to a project that already has a `package.json`? `blume init` leaves existing files alone and skips the install, so install Blume yourself (`npm install blume`), then add `"dev": "blume dev"` and `"build": "blume build"` to its scripts, or run `npx blume dev` directly. The next steps `init` prints include both commands for your package manager.
 
 :::tip
 Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.

package/docs/02-deployment.mdx

@@ -22,7 +22,8 @@ A static build includes:
 
 - every docs and custom page as static HTML
 - a local search index (Orama by default, Pagefind opt-in)
-- a [`sitemap.xml`](/docs/discoverability/sitemap-and-robots#sitemap) and [`robots.txt`](/docs/discoverability/sitemap-and-robots#robots) when the site URL is known
+- a [`sitemap.xml`](/docs/discoverability/sitemap-and-robots#sitemap) when the site URL is known
+- a [`robots.txt`](/docs/discoverability/sitemap-and-robots#robots), which points to the sitemap when the site URL is known
 - `llms.txt` and `llms-full.txt` for AI tools
 - redirect pages
 - prerendered [Open Graph images](/docs/discoverability/open-graph) when `seo.og.enabled` is on
@@ -31,7 +32,7 @@ A static build includes:
 
 Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the platform's environment at build time — no config required.
 
-Set `site` to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN). For a static build that's the plain `deployment` object:
+Set `site`, an absolute `http://` or `https://` URL, to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN). For a static build that's the plain `deployment` object:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -39,7 +40,7 @@ deployment: {
 }
 ```
 
-When detecting automatically, Blume prefers your stable production domain over per-deploy preview URLs, so the canonical origin stays put across deploys.
+On Vercel and Netlify, automatic detection prefers your stable production domain over per-deploy preview URLs, so the canonical origin stays put across deploys. Cloudflare Pages exposes only the current deployment's URL (`CF_PAGES_URL`), which changes with every deploy, so set `site` there.
 
 During `blume dev`, the site URL falls back to your local dev server (e.g. `http://localhost:4321`) when none is set, so site-gated features — Open Graph images, canonicals, the sitemap — work out of the box. Builds never use this fallback, so production output is never pointed at localhost.
 
@@ -52,6 +53,8 @@ blume build
 blume preview
 ```
 
+`blume preview` serves static builds and `node()` and `cloudflare()` server builds. The Vercel and Netlify adapters have no local preview server, so after a `vercel()` or `netlify()` server build it stops with an error instead. Try the site with `blume dev`, or deploy a preview with `vercel deploy` or `netlify deploy`.
+
 ## Subpath deploys
 
 Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
@@ -64,6 +67,8 @@ deployment: {
 
 `base` (and `site`) are options of every host adapter too: `vercel({ base: "/docs" })`.
 
+Every page keeps its own path under the base, even in a content folder that shares the base's name: with `base: "/docs"`, `docs/setup.md` is served at `/docs/docs/setup`, and its canonical URL, sidebar link, and `llms.txt` entry point there. A root-relative link you write that already starts with the base is taken to include it and left as written, so link to that page with a relative link (`./docs/setup`) or its full path (`/docs/docs/setup`).
+
 ## Mount the docs under a path
 
 `basePath` mounts every generated route under a segment (`/docs/getting-started`) while leaving the sidebar untouched — the top level is your sections, not a wrapper group. Use it when the docs live at `/docs/*` but the site root stays yours (like Docusaurus `routeBasePath` or Fumadocs `baseUrl`).
@@ -72,7 +77,7 @@ deployment: {
 basePath: "/docs",
 ```
 
-Write links as if mounted at root (`/getting-started`); Blume rewrites them, along with redirects, the sitemap, canonical URLs, Open Graph images, `llms.txt`, and the search index. Public assets (images, files under `public/`) stay at the site root.
+Write links as if mounted at root (`/getting-started`); Blume rewrites them, along with redirects, the sitemap, canonical URLs, Open Graph images, `llms.txt`, and the search index. Public assets (images, files under `public/`) stay at the site root, or under [`base`](#subpath-deploys) when you set one.
 
 This is a distinct concept from the two paths above:
 
@@ -117,7 +122,7 @@ Naming an adapter switches the build to server output. To keep a static build on
 deployment: netlify({ output: "static" }),
 ```
 
-A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node()` adapter produces a standalone server you can run directly with `node dist/server/entry.mjs`. The server resolves its packages through links into your project's `node_modules`, so deploy the project with its installed dependencies, not `dist/` alone. When the site publishes discovery files, Blume puts a small wrapper in front of Astro's entry (moved to `astro-entry.mjs` beside it) so the `.well-known` discovery files go out with their media types and CORS headers, which the standalone server's static handler can't set on its own.
+A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node()` adapter produces a standalone server you can run directly with `node dist/server/entry.mjs`. It listens on `localhost:4321` unless you set the `HOST` and `PORT` environment variables when you start it (`HOST=0.0.0.0 PORT=8080 node dist/server/entry.mjs`); `host` and `port` passed to `node()` have no effect, because `@astrojs/node` replaces them with Astro's own server settings. The server resolves its packages through links into your project's `node_modules`, so deploy the project with its installed dependencies, not `dist/` alone. When the site publishes discovery files, serves images a content source downloaded, or configures redirects, Blume puts a small wrapper in front of Astro's entry (moved to `astro-entry.mjs` beside it). It sends the `.well-known` discovery files with their media types and CORS headers and downloaded SVGs sandboxed, which the standalone server's static handler can't do on its own, and answers each redirect with its configured status.
 
 A `cloudflare()` server build deploys with `npx wrangler deploy` from the project root after `blume build`: Blume writes the redirected Wrangler config to `.wrangler/deploy/` (and adds `.wrangler/` to `.gitignore`), and names the Worker after your project — the `package.json` `name`, else the site's hostname, else the folder — unless a `wrangler.jsonc` of your own at the project root sets `name`.
 
@@ -139,19 +144,24 @@ Map old URLs to new ones in `blume.config.ts`:
 redirects: [{ from: "/old", to: "/new", status: 301 }],
 ```
 
-`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds handle redirects at request time. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `blume-redirects.json`, a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds answer redirects at request time with the configured status. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `blume-redirects.json`, a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
+
+Two hosts need more than the file:
+
+- **Netlify** serves a file that exists ahead of a redirect rule unless the rule is forced, and a static build has a redirect page at every `from`. The `_redirects` for `netlify()` forces its rules (`/old /new 301!`). Cloudflare rejects that flag, so the file a build for no named host writes leaves it off, and on Netlify that build answers with the redirect page instead; name the host with `netlify({ output: "static" })` to get the HTTP redirect.
+- **Vercel** reads `vercel.json` from the project's root directory, never from the output directory, so the copy in `dist/` applies only when you deploy that folder itself with the Vercel CLI (`vercel deploy dist`). A Git-connected project never reads it: it serves the redirect pages and none of the headers from [Content types](#content-types). Copy the `redirects` and `headers` from `dist/vercel.json` into the `vercel.json` in your project's root directory, or use `vercel()` for a server build, whose routing config carries the redirects and the discovery headers.
 
 :::note
 `from` and `to` are exact paths — a `:param` segment or `*` wildcard (e.g. `/blog/:slug` or `/old/*`) fails config validation, since hosts disagree on patterns. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
 :::
 
 :::note
-Write both `from` and `to` as if mounted at root — under [`base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
+Write both `from` and `to` as if mounted at root, starting with `/` (`to` can also be a full `https://` URL) — under [`base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A `to` that names a file in `public/` (`/files/guide.pdf`) gains `base` but not `basePath`, since that's where the file is served. A base you've already written into `to` by hand is preserved rather than doubled.
 :::
 
 ## Content types
 
-Where the host reads one, a build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify reads `_headers` on a static deploy and Cloudflare (Pages, and Workers static assets) on both static and server builds, so those adapters and an unnamed static host get the file; Vercel (whose headers ride the routing config) and Node (whose server ignores the file) don't. A `_headers` you ship in `public/` is left untouched.
+Where the host reads one, a build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify reads `_headers` on a static deploy and Cloudflare (Pages, and Workers static assets) on both static and server builds, so those adapters and an unnamed static host get the file; Vercel (whose headers ride the routing config) and Node (whose server ignores the file) don't. A Netlify server build writes the same rules into the `headers` of its Frameworks API config (`.netlify/v1/config.json`) instead. A static Vercel build writes the same rules into `dist/vercel.json` instead, which a Git-connected project doesn't read (see [Redirects](#redirects)). A `_headers` you ship in `public/` is left untouched.
 
 ## Environment variables
 
@@ -162,8 +172,9 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 | Assistant (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
 | Assistant (other adapters) | the adapter's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or the `apiKeyEnv` you passed it |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
+| [Content sources](/docs/content/sources) | `NOTION_TOKEN` (`notion()`), `SANITY_TOKEN` (`sanity()`), `CONTENTFUL_ACCESS_TOKEN` (`contentful()`), `PAYLOAD_API_KEY` (`payload()`), `STRAPI_API_TOKEN` (`strapi()`), `GITHUB_TOKEN` (`githubReleases()`, and `mdxRemote()` reading from GitHub) |
 
-Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.
+Set them in `.env.local` for local dev and in your host's environment for production. A content source reads its token when it fetches, during `blume dev` and `blume build`, so set it where your site builds. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.
 
 ## Build cache
 

package/docs/08-faq.mdx

@@ -45,7 +45,7 @@ No. A folder of Markdown is a complete site — navigation, search, and theming
 
 ## Can I use React components and MDX?
 
-Yes. Any page can be `.md` or `.mdx`, and MDX lets you drop in the [built-in components](/docs/content/components) with no imports. You can also add your own `.tsx`/`.jsx` [islands](/docs/content/islands) — Blume auto-enables React only for the pages that use them, so the core theme stays JavaScript-free everywhere else.
+Yes. Any page can be `.md` or `.mdx`, and MDX lets you drop in the [built-in components](/docs/content/components) with no imports. You can also add your own `.tsx`/`.jsx` [islands](/docs/content/islands). Blume switches React on only when your project uses it — any `.tsx` or `.jsx` file in the project (your islands included), a React [`<Component>`](/docs/content/components#component) example, a [component override](/docs/configuration/customization), or the [assistant](/docs/configuration/assistant) — so a site with none of those ships no framework JavaScript.
 
 ## Where can I deploy it?
 
@@ -57,7 +57,7 @@ No. [Orama](/docs/configuration/search) builds a local index that works in both
 
 ## How do I customize the look?
 
-Start with [theme tokens](/docs/configuration/theming) — accent color, fonts, radius, and a `theme.css` for anything else Tailwind can express. Go further by [overriding built-in components](/docs/configuration/customization) or adding [custom pages](/docs/configuration/customization#custom-pages). When you want the Astro project itself, [`blume eject`](/docs/cli) hands you a standalone app that still uses the `blume` package.
+Start with [theme tokens](/docs/configuration/theming) — accent color, fonts, radius, and a `theme.css` for anything else Tailwind can express. Go further by [overriding built-in components](/docs/configuration/customization) or adding [custom pages](/docs/configuration/customization#custom-pages). When you want the Astro project itself, [`blume eject`](/docs/configuration/customization#eject) hands you a standalone app that still uses the `blume` package.
 
 ## Why is oxfmt / Ultracite collapsing my directives?
 
@@ -141,7 +141,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
     		case "emphasis": {
    ```
 
-2. Register it with your package manager's `patchedDependencies`. With Bun or pnpm, add to `package.json`:
+2. Register it with your package manager's `patchedDependencies`. With Bun, add to `package.json`:
 
    ```json package.json
    {
@@ -151,6 +151,13 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    }
    ```
 
+   With pnpm, add to `pnpm-workspace.yaml` (pnpm 11 and later no longer read settings from `package.json`):
+
+   ```yaml pnpm-workspace.yaml
+   patchedDependencies:
+     oxfmt@0.67.0: patches/oxfmt@0.67.0.patch
+   ```
+
 3. Reinstall so the patch is applied:
 
    ```package-install

package/docs/advanced/changelog.mdx

@@ -62,7 +62,7 @@ Once you have at least one `type: changelog` entry, Blume generates a **`/change
 - The date follows the configured [`dateFormat`](/docs/configuration#date-format), minus the year the row's group already shows.
 - Drafts and `sidebar.hidden` entries are skipped.
 
-The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default index. The `<Update>` component the previous timeline was built from is still available for a hand-authored page that wants inline release notes.
+The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default index. The `<Update>` component the previous timeline was built from still ships for a custom page that wants inline release notes. It isn't one of the MDX components, so import it in the `.astro` page itself: `import Update from "blume/components/content/Update.astro";`.
 
 A header [tab](/docs/content/navigation#tabs) pointing at `/changelog` opens this index — no `href` needed.
 

package/docs/advanced/custom-pages.mdx

@@ -102,10 +102,10 @@ The module exposes:
       description: "Generated RSS feeds: { href, title }.",
     },
     fontCssVars: {
-      type: "string[]",
+      type: "FontHead[]",
       required: true,
       description:
-        "CSS variable names for the configured fonts (Astro <Font> integration).",
+        "The configured fonts for Astro's <Font> component in the head, one per family: { cssVariable, preloadWeights, preloadSubsets? }.",
     },
     ui: {
       type: "UIStrings",
@@ -230,13 +230,15 @@ const { config } = data;
 </PageLayout>
 ```
 
-The header a custom page gets is the same one the docs pages get, so the chrome that lives in it comes along: search, the theme toggle, the language switcher, and — when the [assistant](/docs/configuration/assistant) is configured — its trigger. None of it needs wiring up per page. Pass `assistantEnabled={false}` to leave the assistant trigger off one page while keeping it everywhere else.
+The header a custom page gets is the same one the docs pages get, so the chrome that lives in it comes along: search, the theme toggle, and — when the [assistant](/docs/configuration/assistant) is configured — its trigger. None of it needs wiring up per page. Pass `assistantEnabled={false}` to leave the assistant trigger off one page while keeping it everywhere else.
+
+The language switcher is the exception. A custom page is served only at its own route, so Blume can't know which other locales have a version of it, and the header shows no switcher unless you pass one: `localeSwitch` takes an entry per locale — `{ code, label, dir, href, current, untranslated }` — pointing at the page you built for each language.
 
 The [agent-discovery head links](/docs/discoverability/agent-discovery#discovery-link-header) come along too: the layout reads the resolved config, so a custom page carries the same `describedby`, `ai-catalog`, and `ard` links the docs pages do without passing a prop. The homepage also advertises its `/index.md` Markdown mirror as a `text/markdown` alternate, since that mirror always exists; other custom pages have none, so none is advertised. Pass `discovery={null}` to drop the links from one page.
 
 Pass `transparentHeader` to start the header see-through with its chrome in white, so it can sit over a dark hero at the top of the page; it becomes the usual frosted bar as soon as the page scrolls, and the search dialog keeps the page's own colors throughout. The hero has to run under the header for this to show — pull it up by the header's height (`-mt-16`) and pad its top to compensate.
 
-Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generated `og:image` automatically: Blume renders an Open Graph card for every static custom page (not a dynamic `[param]` one) — the home included, the most-shared URL — served at `/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title with the description as its eyebrow; a deeper page is titled from its last path segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage` takes a root-relative path — a file in `public/`, resolved against [`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an external URL, which passes through untouched:
+Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generated `og:image` automatically: Blume renders an Open Graph card for every static custom page (not a dynamic `[param]` one) — the home included, the most-shared URL — served at `/og/<route>.png` (`/og/index.png` for `/`). The home card's headline is the site title, with the site description as the subtitle beneath it; a deeper page is titled from its last path segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage` takes a root-relative path — a file in `public/`, resolved against [`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an external URL, which passes through untouched:
 
 ```astro pages/index.astro lineNumbers
 <PageLayout
@@ -288,7 +290,7 @@ Blume ships a default **not found** page out of the box: a centered "404" messag
 
 The page also has a Markdown twin at `/404.md` and a JSON twin at `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details) with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set), plus the [`openapi.json`](/docs/discoverability/json-api) description when the JSON API is on. On a [Vercel or Cloudflare server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/discoverability/markdown#content-negotiation) gets the Markdown body with the `404` status instead of the HTML shell, and one that sends `Accept: application/json` gets the problem document — so an agent never has to parse a page of chrome to learn where to go next. On Vercel the same goes for a `.md` or `.json` URL no file backs.
 
-To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:
+To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped, along with its `/404.md` and `/404.json` twins. Build it like any other custom page, in `PageLayout` or `RootLayout`:
 
 ```astro pages/404.astro lineNumbers
 ---

package/docs/cli/audit.mdx

@@ -83,7 +83,23 @@ Anything the audit did not run is reported as skipped rather than silently passi
 
 ## Check catalog
 
-Every check `blume audit` can report, grouped by category, with its default severity, the tier it runs in, and the fix the report suggests. `--only` and `--skip` accept these ids (without the `BLUME_AUDIT_` prefix is fine too) or the category names.
+Every check `blume audit` can report, grouped by category, with its default severity, the tier it runs in, and the fix the report suggests. `--only` and `--skip` accept these ids (without the `BLUME_AUDIT_` prefix is fine too) or a category's key. The key isn't always the category's heading, so use this table: `blume audit --only i18n`, not `--only Internationalization`.
+
+| Category             | Key               |
+| -------------------- | ----------------- |
+| Content              | `content`         |
+| Duplicates           | `duplicates`      |
+| Indexability         | `indexability`    |
+| Links                | `links`           |
+| Redirects            | `redirects`       |
+| Social cards         | `social`          |
+| Internationalization | `i18n`            |
+| Assets               | `assets`          |
+| Sitemap              | `sitemap`         |
+| robots.txt           | `robots`          |
+| AI discoverability   | `ai`              |
+| Structured data      | `structured-data` |
+| Live deployment      | `network`         |
 
 ### Content
 
@@ -497,7 +513,7 @@ Fix: Remove the URL from the sitemap, or build the page it names.
 
 `BLUME_AUDIT_SITEMAP_INVALID` · error · from the built HTML
 
-Fix: Sitemaps must be valid XML in the sitemaps.org urlset format.
+Fix: Sitemaps must be valid XML in the sitemaps.org urlset or sitemap index format.
 
 #### Sitemap exceeds 50 MB or 50,000 URLs [#sitemap-too-large]
 
@@ -573,7 +589,7 @@ Fix: Rebuild so llms.txt matches the site — a stale entry sends an AI agent to
 
 `BLUME_AUDIT_LLMS_TXT_PAGE_MISSING` · warning · from the built HTML
 
-Fix: Rebuild so llms.txt matches the site; if the page is deliberately excluded, mark it `seo.noindex` or `sidebar.hidden`.
+Fix: Rebuild so llms.txt matches the site; if the page is deliberately excluded, set `ai.exclude: true` in its front matter.
 
 #### No DNS-AID agent-discovery records [#dns-aid-missing]
 

package/docs/cli/doctor.mdx

@@ -14,11 +14,11 @@ blume doctor
 - **The Node version** against the range the installed `blume` package supports, read from its own `engines` field. A version outside it is a warning: things may work, but it isn't a combination Blume tests.
 - **`blume.config.ts`**, with the same validation a build runs. A removed or renamed key fails with a hint naming its replacement rather than a bare "unrecognized key".
 - **Every content page and folder meta**: the diagnostics `blume dev` and `blume build` print as they load the project — invalid frontmatter, navigation problems, missing include targets, and the rest — collected in one report.
-- **Features that need a server** on a site configured for static output — the assistant, the MCP server, or the Try it playground's built-in proxy: an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to `output: "static"`, telling you to drop that option).
+- **Features that need a server** on a site configured for static output — the assistant, the MCP server, the Try it playground's built-in proxy, or server-mode search (Mixedbread): an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to `output: "static"`, telling you to drop that option).
 - **Packages your config needs** that aren't installed — the SDK a search, content source, or assistant adapter imports, a deployment adapter's `@astrojs/*` package, or the renderer for Vue or Svelte islands: an error naming each package, with the install command for your package manager. `blume build` stops on the same check.
 - **`components.ts` overrides** Blume can't plan — an inline or computed entry, or an import whose file doesn't exist: an error for each, at its line.
 - **A version-shaped folder** (`v1.0/`) on a site with no `versions` configured, which would otherwise build as ordinary content: a warning pointing at [`blume version`](/docs/cli/version).
-- **Secrets an enabled feature reads** that aren't set, such as `ALGOLIA_ADMIN_API_KEY` or `OPENROUTER_API_KEY`: a warning naming the variable. Doctor loads `.env` and `.env.local` first, like `blume dev` and `blume build`.
+- **Secrets an enabled feature reads** that aren't set, such as `MIXEDBREAD_API_KEY` or `OPENROUTER_API_KEY`: a warning naming the variable. Doctor loads `.env` and `.env.local` first, like `blume dev` and `blume build`.
 
 ## The summary