blume 0.6.7 → 0.8.0

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

@@ -108,6 +108,8 @@ export interface NormalizeContext {
         prefix?: string;
         staged: boolean;
     };
+    /** Site-wide route mount point (`""` or `/seg`), prepended to every route. */
+    basePath?: string;
     defaultType: string;
     i18n?: ResolvedI18nConfig;
 }

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

@@ -162,10 +162,14 @@ export interface NavSelectorItem {
     icon?: string;
     tag?: string;
 }
+/** Context-partition selector kinds (a versioned/localized/multi-product site). */
+type NavSelectorContextKind = "product" | "version";
+/** What a top-level partition selector switches between. */
+type NavSelectorKind = "dropdown" | "language" | NavSelectorContextKind;
 /** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
     label: string;
-    kind: "dropdown" | "language" | "product" | "version";
+    kind: NavSelectorKind;
     items: NavSelectorItem[];
 }
 /** A pinned link rendered above the sidebar sections (external or internal). */
@@ -252,3 +256,4 @@ export interface BlumeManifest {
     output: ResolvedConfig["deployment"]["output"];
     routes: RouteManifestEntry[];
 }
+export {};

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export type { ComponentMarkdown, ComponentMarkdownChild, ComponentMarkdownContext, } from "./ai/component-markdown.ts";
 export { defineConfig } from "./core/config.ts";
 export type { BlumeBanner, BlumeData, BlumeDataConfig, BlumeDataI18n, BlumeDataLocale, BlumeFavicon, BlumeFeed, BlumeLogo, BlumeRoute, } from "./core/data.ts";
 export { defineComponents } from "./core/define-components.ts";

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

@@ -0,0 +1,60 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { NavTab } from "../core/types.ts";
+/**
+ * Pure resolution of the configured API reference blocks into concrete routes,
+ * labels, and a renderer choice — no file IO, so the content source, the nav
+ * tabs, the Scalar page generator, and the `blume:openapi` data module all share
+ * one source of truth. Kept free of any Astro/template imports so `core` can
+ * depend on it without a cycle.
+ */
+export type ReferenceKind = "openapi" | "asyncapi";
+/** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
+export type ReferenceRenderer = "blume" | "scalar";
+/** Per-block display options for the Blume renderer. */
+export interface ReferenceDisplay {
+    /** Code-sample languages shown per operation. */
+    codeSamples: string[];
+    /** Whether nested schema rows start expanded. */
+    expandSchemas: boolean;
+}
+/** A spec source resolved to a concrete route, label, and renderer. */
+export interface ReferenceSource {
+    kind: ReferenceKind;
+    renderer: ReferenceRenderer;
+    /** Unique token derived from the route; the `<Operation source>` / data key. */
+    slug: string;
+    /** Normalized route the reference mounts at, e.g. `/reference`. */
+    route: string;
+    /**
+     * Site-wide `basePath` the rendered pages are mounted under (`""` when
+     * none). Kept separate from `route` — the content pipeline applies it to
+     * staged entries itself — so consumers prefix only the URLs they emit.
+     */
+    basePath: string;
+    label: string;
+    /** Local path or `http(s)` URL, verbatim from config. */
+    spec: string;
+    /** Per-block Scalar theme name override, if any (Scalar renderer only). */
+    theme?: string;
+    /** Display options carried through to the Blume renderer. */
+    display: ReferenceDisplay;
+    /**
+     * Warnings recorded while deduping — another source's route collided with
+     * this one and was dropped. Surfaced as diagnostics when the source loads.
+     */
+    collisions?: string[];
+}
+export declare const slugify: (text: string) => string;
+/** Normalize a configured route to a single leading slash, no trailing slash. */
+export declare const normalizeRoute: (route: string) => string;
+/**
+ * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
+ * by default); AsyncAPI is always rendered by Scalar for now.
+ */
+export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSource[];
+/** Nav tabs (header links) for every reference, regardless of renderer. */
+export declare const referenceTabs: (config: ResolvedConfig) => NavTab[];
+/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
+/** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
+export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;

package/docs/01-quickstart.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 1
 ---
 
-Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
+Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.12 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
 
 ## Install and run
 
@@ -20,7 +20,10 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
 
   </Step>
   <Step title="Scaffold a project">
-    `blume init` creates the minimum surface: a content folder and a config file.
+    `blume init` asks a few questions — where to create the project, what your
+    docs site is called, which template, and where your content lives — then
+    scaffolds the minimum surface: a content folder and a config file. Pass
+    `--yes` to skip the prompts and take the defaults.
 
     ```bash
     blume init

package/docs/02-deployment.mdx

@@ -10,11 +10,11 @@ sidebar:
 
 `blume build` compiles your docs to plain HTML, CSS, and a local search index in `dist/`. There's no server to run — point any static host at the folder.
 
-| Setting          | Value         |
-| ---------------- | ------------- |
-| Build command    | `blume build` |
-| Output directory | `dist`        |
-| Node version     | 22 or newer   |
+| Setting          | Value          |
+| ---------------- | -------------- |
+| Build command    | `blume build`  |
+| Output directory | `dist`         |
+| Node version     | 22.12 or newer |
 
 These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.
 
@@ -54,7 +54,7 @@ blume preview
 
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. Internal links and assets are rewritten to include the base path.
+Serving docs under a path like `example.com/docs`? Set `deployment.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.
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -62,6 +62,21 @@ deployment: {
 }
 ```
 
+## 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`).
+
+```ts blume.config.ts lineNumbers
+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.
+
+This is a distinct concept from the two paths above:
+
+- A per-source [`prefix`](/docs/content/sources#multiple-sources) namespaces **one** source and **does** add a sidebar group.
+- `deployment.base` is the host subdirectory the **whole** app is served from. The two compose — with both set, a page lands at `{deployment.base}/{basePath}/page`.
+
 ## Server rendering
 
 Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:
@@ -73,7 +88,7 @@ deployment: {
 }
 ```
 
-Choosing an adapter pulls in the matching Astro adapter automatically:
+The `vercel` and `node` adapters ship with Blume — choosing one just works. The `netlify` and `cloudflare` adapters must be installed in your project (e.g. `bun add -d @astrojs/netlify`); the CLI warns you if the package is missing:
 
 | Adapter      | Package               | Use for                              |
 | ------------ | --------------------- | ------------------------------------ |
@@ -82,7 +97,7 @@ Choosing an adapter pulls in the matching Astro adapter automatically:
 | `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
 | `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |
 
-On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy. Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
+On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy (on Netlify and Cloudflare, install the adapter package too). Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
 
 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.
 
@@ -111,7 +126,7 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 | Feature | Variable |
 | --- | --- |
 | Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
-| Ask AI (OpenRouter / OpenAI-compatible) | the provider's `apiKeyEnv` |
+| Ask AI (other providers) | the provider's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or your configured `apiKeyEnv` |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
 
 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.

package/docs/03-faq.mdx

@@ -79,26 +79,26 @@ Once the opening `:::note` fence is joined to the prose, it's no longer a direct
 
 ### Why it happens
 
-This is a bug in oxfmt's Markdown formatter (inherited from Prettier's Markdown printer — see [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). When it wraps prose, it treats the `:::` fence lines as ordinary text and joins them with the adjacent line, breaking the directive. It affects every container directive — `:::note`, `:::tip`, `:::warning`, `:::danger`, `:::success`.
+This is a bug in oxfmt's Markdown formatter (inherited from Prettier's Markdown printer — see [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). When it wraps prose, it treats the `:::` fence lines as ordinary text and joins them with the adjacent line, breaking the directive. It affects every container directive type — `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::success`.
 
 We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096); until it's fixed there, the patch below is the workaround.
 
 ### The fix
 
-Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships exactly this patch in its own repo, and you can apply the same one in any project.
+Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.55.0.patch`:
+1. Save the patch as `patches/oxfmt@0.58.0.patch`:
 
-   ```diff patches/oxfmt@0.55.0.patch
-   diff --git a/dist/markdown-Bowe09rB.js b/dist/markdown-Bowe09rB.js
-   index 0fe63ff712e07c9c2188711fa0940f7a7d8f7d74..44435d91a2f5a6711512981c9bcaddedc1760be4 100644
-   --- a/dist/markdown-Bowe09rB.js
-   +++ b/dist/markdown-Bowe09rB.js
-   @@ -1141,7 +1141,14 @@ function Yf(e, r, t) {
-    		case "sentence": return Yi(e, t);
-    		case "word": return Li(e);
+   ```diff patches/oxfmt@0.58.0.patch
+   diff --git a/dist/markdown-BjyDFyaO.js b/dist/markdown-BjyDFyaO.js
+   index 1905aa7563e612808426e26f1ed28bebbef3456f..42bb9f66829068676c5697fc9fc39279bf937f3e 100644
+   --- a/dist/markdown-BjyDFyaO.js
+   +++ b/dist/markdown-BjyDFyaO.js
+   @@ -4830,7 +4830,43 @@ function lu(e, t, r) {
+    		case "sentence": return Mh(e, r);
+    		case "word": return t.parser !== "mdx" ? Vh(e, t) : Gh(e);
     		case "whitespace": {
-   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
+   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
    +			let { next: i, previous: oxfmtFencePrev } = e;
    +			// Preserve line breaks that sit directly against a `:::` container
    +			// directive fence, so `proseWrap: "never"` keeps the opening/closing
@@ -106,8 +106,37 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    +			// breaks the directive). Ordinary prose still wraps per proseWrap.
    +			// See prettier/prettier#19040.
    +			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
-   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
-    			return qt(e, n.value, u);
+   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
+   +			// linkReference between two sentence nodes at the paragraph level: the
+   +			// fence word ends the sentence before the reference, and the body's
+   +			// leading newline opens the sentence after it. So when this whitespace
+   +			// starts its sentence, climb to the paragraph and check whether the two
+   +			// preceding siblings are a (link) reference and a sentence ending in a
+   +			// `:::` fence word.
+   +			let oxfmtPrevIsTitledFence = !1;
+   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
+   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
+   +				if (oxfmtSentIdx >= 2) {
+   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
+   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
+   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
+   +				}
+   +			}
+   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
+   +			// words, so the whole directive is one sentence. For a newline
+   +			// whitespace, walk back to the start of its visual line within the
+   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
+   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
+   +				let oxfmtLineFirst = null;
+   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
+   +					let oxfmtSib = e.parent.children[oxfmtJ];
+   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
+   +					oxfmtLineFirst = oxfmtSib;
+   +				}
+   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
+   +			}
+   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
+    			return ou(e, n.value, u, !1, t);
     		}
     		case "emphasis": {
    ```
@@ -117,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.55.0": "patches/oxfmt@0.55.0.patch"
+       "oxfmt@0.58.0": "patches/oxfmt@0.58.0.patch"
      }
    }
    ```
@@ -128,5 +157,6 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    bun install
    ```
 
-:::warning[Version-pinned] The patch targets oxfmt `0.55.0` — its diff references a file hashed to that build (`dist/markdown-Bowe09rB.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.
+:::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.
 :::

package/docs/advanced/custom-pages.mdx

@@ -74,7 +74,7 @@ The module exposes:
       type: "BlumeDataConfig",
       required: true,
       description:
-        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, og, analytics, feedback, structuredData, codeWrap, and imageZoom.",
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
     },
     navigation: {
       type: "Navigation",

package/docs/advanced/skills.mdx

@@ -18,7 +18,7 @@ npx skills add haydenbleasel/blume
 `blume-update-docs` keeps your docs in sync with the product they document. On each run — typically from a schedule you configure in your agent runner — it audits recently merged PRs, changelogs, config schemas, and CLI help against the docs content, updates only pages that are factually stale (feature-flagged work is ignored), verifies with `blume build`, and opens or updates a `blume/*` pull request. If nothing drifted, it reports a clean no-op instead of opening a noisy PR.
 
 ```bash
-npx skills use haydenbleasel/blume@blume-update-docs
+npx skills add haydenbleasel/blume --skill blume-update-docs
 ```
 
 Blume doesn't host the automation — wire the skill into a scheduled task in Claude Code, a Codex or Cursor automation, or plain cron, with permission to read repo history and open PRs. A typical weekly prompt:

package/docs/configuration/ai.mdx

@@ -17,23 +17,62 @@ ai: {
 
 While enabled, `blume build` writes two files to the root of your site:
 
-- **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary.
+- **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary, organized into sections that mirror your sidebar — folders and groups become headings, so an agent sees the docs' structure, not one flat blob.
 - **`/llms-full.txt`** — the entire corpus: each page's full Markdown body, with its source URL, in one file.
 
 Draft pages are excluded. Set [`deployment.site`](/docs/deployment) so the links and source URLs resolve to absolute addresses.
 
+`llmsTxt` also takes an object form with knobs for what the files include. If your [API reference](/docs/advanced/api-reference) documents a placeholder or example spec, set `openapi: false` to keep its generated pages out of both files:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  llmsTxt: {
+    enabled: true, // default
+    openapi: false, // exclude generated API reference pages
+  },
+}
+```
+
+To take full control of either file, add your own `llms.txt` or `llms-full.txt` to your `public/` folder. Like a custom favicon, it's picked up automatically and ships in place of the generated file — override one and Blume still generates the other.
+
 ## Raw Markdown
 
 Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — perfect for LLMs, coding agents, and "copy as Markdown" workflows. It's available for every page, in dev and production, with no configuration.
 
-| URL               | Returns                 |
-| ----------------- | ----------------------- |
-| `/quickstart`     | The rendered page       |
-| `/quickstart.md`  | The raw Markdown source |
-| `/quickstart.mdx` | The raw Markdown source |
+| URL               | Returns                                   |
+| ----------------- | ----------------------------------------- |
+| `/quickstart`     | The rendered page                         |
+| `/quickstart.md`  | Plain Markdown, with components converted |
+| `/quickstart.mdx` | The raw MDX source, exactly as written    |
 
 Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
+The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
+
+### Custom component serializers
+
+Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes) and its `children` (already downleveled to Markdown), and returns the replacement — or `null` to leave the JSX as-is:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import type { ComponentMarkdown } from "blume";
+
+const chart: ComponentMarkdown = ({ props }) =>
+  `![${props.title}](/charts/${props.slug}.png)`;
+
+export default defineConfig({
+  ai: {
+    markdownComponents: {
+      Chart: chart,
+    },
+  },
+});
+```
+
+For container components, `childComponents("Name")` extracts direct children by tag — the same way the built-in `<Steps>` serializer collects its `<Step>` items. A same-name entry replaces a built-in serializer, so you can restyle how `<Callout>` downlevels — or return `null` to opt one out entirely.
+
+Serializers live in `blume.config.ts`, not `components.tsx`: the config file is executed at build time, while the components file is only statically analyzed (it may import `.astro` files, which can't run outside the site build). Your components themselves stay registered in `components.tsx` exactly as before — `markdownComponents` only adds their agent-facing Markdown form.
+
 ## Copy as Markdown
 
 Every page carries a **Copy as Markdown** action — in the [page actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the page's raw Markdown to the clipboard. It's the same source served at the [`.md` URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes. It's available on every page, in dev and production, with no configuration.
@@ -46,7 +85,7 @@ The **Open in chat** action opens the current page in an AI assistant — v0, Ch
 
 Like Copy as Markdown, it needs no setup. The assistant fetches the page over its public URL, so it works as soon as the page is deployed.
 
-To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labelled row with a **Copy prompt** button and an optional open-in-Cursor link.
+To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labeled row with a **Copy prompt** button and an optional open-in-Cursor link.
 
 ## Ask AI
 
@@ -172,7 +211,7 @@ mcp: {
 | `name`         | title   | Server name shown to clients (defaults to title). |
 | `instructions` | —       | Optional system hint passed to connecting agents. |
 
-The server exposes four read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, and VS Code (shown once [`deployment.site`](/docs/deployment) is set).
+The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).
 
 `search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even when search is set to `none`. The MCP server is a separate feature from on-page search.
 
@@ -196,7 +235,7 @@ claude mcp add --transport http my-docs https://docs.example.com/mcp
 
 ## Agent readability
 
-Blume writes an **`/agent-readability.json`** manifest at your site root that indexes the agent-facing surface described on this page — so an agent can discover it in a single fetch instead of guessing at conventions or scraping HTML. Unlike the features above, it's on by default:
+Blume writes an **`/agent-readability.json`** manifest at your site root that indexes the agent-facing surface described on this page — so an agent can discover it in a single fetch instead of guessing at conventions or scraping HTML. Like `llms.txt`, it's on by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -241,4 +280,4 @@ npx skills add haydenbleasel/blume
 
 The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (`node_modules/blume/docs`).
 
-It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside skills for migrating an existing docs site to Blume and keeping docs in sync with your product from a scheduled agent run.
+It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside a skill for keeping docs in sync with your product from a scheduled agent run.

package/docs/configuration/customization.mdx

@@ -154,3 +154,14 @@ blume eject --yes
 ```
 
 Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.
+
+### What eject leaves behind
+
+After ejecting, your `build` script runs plain `astro build` — the site itself builds the same, but the artifacts `blume build` layered on top are no longer produced. The eject command warns about the ones your config actually uses. To keep them:
+
+- **Pagefind search index** — with `search.provider: "pagefind"`, the search UI loads the index from the built site, so search breaks in production until you index it yourself. Install `pagefind` as a devDependency and index after each build: `"build": "astro build && pagefind --site dist"`.
+- **Hosted search sync** — a hosted provider's index is no longer pushed on build; re-upload your search records after each build with the provider's API or CLI.
+- **sitemap.xml** — recreate it with the standard [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) integration.
+- **robots.txt** — ship your own as `public/robots.txt`.
+- **llms.txt / llms-full.txt and agent-readability.json** — write them by hand (or generate them in a build step of your own) and serve them from `public/`.
+- **Platform redirect files** — `_redirects` and `vercel.json` are no longer emitted for static builds. Your redirects still work as Astro-generated meta-refresh pages, or you can move them into your host's own config.

package/docs/configuration/index.mdx

@@ -53,6 +53,12 @@ export default defineConfig({
       icons: true, // language icon in the code-block header
       wrap: false, // wrap long lines instead of scrolling
     },
+    codeBlocks: {
+      theme: {
+        light: "github-light", // any bundled Shiki theme
+        dark: "github-dark",
+      },
+    },
   },
 
   // AI — see the AI guide
@@ -183,6 +189,24 @@ content: {
 
 Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`.
 
+## GitHub
+
+Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):
+
+```ts blume.config.ts lineNumbers
+github: {
+  owner: "acme",
+  repo: "docs",
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `owner` | — | GitHub account or organization that owns the repository. |
+| `repo` | — | Repository name. |
+| `branch` | `"main"` | Branch that edit links point at. |
+| `dir` | — | Path from the repo root to the project root (for monorepos). |
+
 ## Last modified
 
 Show a "Last updated on …" line at the bottom of each page. Off by default; set `lastModified` to `true` to derive each page's date from its git history:
@@ -242,7 +266,13 @@ The on-this-page outline is on by default and lists `H2`–`H3` headings. Turn i
 ```ts blume.config.ts
 export default defineConfig({
   toc: false, // hide it everywhere
-  // …or narrow the range:
+});
+```
+
+Or narrow the heading range instead:
+
+```ts blume.config.ts
+export default defineConfig({
   toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
 });
 ```
@@ -255,8 +285,8 @@ Each of these has its own guide. The config field is the entry point:
 | --- | --- | --- |
 | `theme` | Accent color, corner radius, fonts, light/dark mode | [Theming](/docs/configuration/theming) |
 | `navigation` | Explicit sidebar and header tabs | [Navigation](/docs/content/navigation) |
-| `search` | Provider (Orama or Pagefind) and indexing | [Search](/docs/configuration/search) |
-| `markdown` | Opt-in Markdown features like math | [Syntax](/docs/content/syntax) |
+| `search` | Provider (Orama, Pagefind, Algolia, and more) and indexing | [Search](/docs/configuration/search) |
+| `markdown` | Markdown rendering options — code blocks, heading anchors, image zoom | [Syntax](/docs/content/syntax) |
 | `ai` | `llms.txt`, Ask AI, and the MCP server | [AI](/docs/configuration/ai) |
 | `mcp` | Hosted MCP server for coding agents | [AI](/docs/configuration/ai#mcp-server) |
 | `analytics` | Vercel, PostHog, and custom scripts | [Analytics](/docs/configuration/analytics) |

package/docs/configuration/seo.mdx

@@ -5,7 +5,7 @@ sidebar:
   label: SEO
 ---
 
-Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The three configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.
+Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -225,6 +225,6 @@ seo: {
   }}
 />
 
-Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honour them.
+Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honor them.
 
 Ship your own `public/robots.txt` to take over.

package/docs/content/components.mdx

@@ -428,7 +428,7 @@ A single row with a label and a copy button. The `description` (Markdown) is the
 
 ## Visibility
 
-Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the generated Markdown (`llms.txt`) that AI agents read.
+Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the agent-facing Markdown that AI agents read (`llms-full.txt` and each page's `.md` mirror).
 
 <Visibility for="web">
   This note appears on the website but is omitted from the agent-facing
@@ -546,7 +546,33 @@ A card linking to a GitHub repository with its live star and fork counts. Counts
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The directory is configurable — set `examples` in `blume.config.ts` when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live.
+
+To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
+
+```ts
+// blume.config.ts
+export default defineConfig({
+  examples: { css: "examples/theme.css" },
+});
+```
+
+```css
+/* examples/theme.css */
+:root {
+  --primary: oklch(0.6 0.2 260);
+}
+
+.dark {
+  --primary: oklch(0.75 0.15 260);
+}
+
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+The directory is configurable too — set `source` (or use the string shorthand, `examples: "..."`) when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:
 
 ```ts
 // blume.config.ts
@@ -593,6 +619,7 @@ An Astro example renders live with no client JavaScript:
 
 <CodeBlock
   lang="ts"
+  icons={false}
   code={`export const greet = (name: string): string =>
   \`Hello, \${name}!\`;`}
 />
@@ -602,7 +629,7 @@ An Astro example renders live with no client JavaScript:
 import CodeBlock from "blume/components/content/CodeBlock.astro";
 ---
 
-<CodeBlock lang="ts" code={source} />
+<CodeBlock lang="ts" code={source} icons={false} />
 ```
 
 To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:

package/docs/content/i18n.mdx

@@ -108,7 +108,7 @@ When i18n is on, a language switcher appears in the header automatically, genera
 
 Blume ships built-in translations for its own interface chrome — “On this page”, “Search”, “Edit on GitHub”, and the rest — so a locale with a built-in pack gets translated UI out of the box. **You only translate your content.**
 
-Packs ship for 36 languages — Arabic, Bengali, Bulgarian, Catalan, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (and Brazilian Portuguese), Romanian, Russian, Serbian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. They're community-maintained — open a PR to add a locale or sharpen a translation.
+Packs ship for over 30 languages — Arabic, Bengali, Bulgarian, Catalan, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (and Brazilian Portuguese), Romanian, Russian, Serbian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. They're community-maintained — open a PR to add a locale or sharpen a translation.
 
 Missing or unshipped strings fall back to the default locale, then to English. To override a string or supply your own language, set `i18n.ui`, keyed by locale:
 

package/docs/content/islands.mdx

@@ -77,6 +77,14 @@ export default function Chart() {
 
 **React works out of the box** — Blume turns it on automatically the moment your project contains a `.tsx`/`.jsx` island.
 
+The [React Compiler](https://react.dev/learn/react-compiler) is on by default whenever React is enabled, so your islands are auto-memoized — no hand-written `useMemo`/`useCallback` needed. It ships with Blume; there's nothing to install. Opt out in `blume.config.ts`:
+
+```ts blume.config.ts
+export default defineConfig({
+  react: { compiler: false },
+});
+```
+
 **Vue and Svelte** are supported too; install the matching Astro integration and Blume wires up the renderer when it sees a `.vue` or `.svelte` island:
 
 ```bash

package/docs/content/navigation.mdx

@@ -147,7 +147,7 @@ navigation: {
 }
 ```
 
-Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/configuration/customization) name, image path/URL, or inline SVG — the same as anywhere else). An `href` may point anywhere: an external URL opens in a new tab, while an internal route (`/contact`) is validated against your pages at build time, warning you if nothing matches.
+Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG — the same as anywhere else). An `href` may point anywhere: an external URL opens in a new tab, while an internal route (`/contact`) is validated against your pages at build time, warning you if nothing matches.
 
 ## Explicit sidebar
 
@@ -196,10 +196,10 @@ A right-rail outline is generated automatically from each page's `##` and `###`
 
 Below the table of contents, every page shows a set of quick actions:
 
-- **Edit this page on GitHub** — links straight to the source file. Appears once you set [`github`](/docs/configuration) in your config.
+- **Edit on GitHub** — links straight to the source file. Appears once you set [`github`](/docs/configuration) in your config.
 - **Scroll to top** — smoothly returns to the top of long pages.
 - **Give feedback** — opens a prefilled GitHub issue with an optional reaction and note (also requires `github`).
 
-Three more hand the page to AI tools — **Copy as Markdown**, **Open in chat**, and **Ask AI about this page** — covered in [AI](/docs/configuration/ai#copy-as-markdown).
+Others hand the page to AI tools — **Copy as Markdown** and **Open in chat** — covered in [AI](/docs/configuration/ai#copy-as-markdown).
 
 With [`export`](/docs/configuration/export) on, an **Export** action also lets readers download the page as a PDF or EPUB.