blume 0.7.0 → 1.0.0

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/dist/types/seo/x-handle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize an X account to the leading `@` that `twitter:site`/`twitter:creator`
+ * require, so `acme`, `@acme`, and `  @acme ` all land on `@acme`. Empty or
+ * blank input yields undefined, which renders no tag at all.
+ *
+ * The layouts call this on values that never passed through the config schema:
+ * Astro's collections carry no schema here, so a page's `seo.x.creator` reaches
+ * them as raw frontmatter, and the schema's own transform never runs on it.
+ * (Blume's page pipeline does reject a non-string `creator` before the page is
+ * built, so `unknown` is defense in depth rather than the expected path.)
+ */
+export declare const normalizeXHandle: (value: unknown) => string | undefined;

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.
 
@@ -88,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                              |
 | ------------ | --------------------- | ------------------------------------ |
@@ -97,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.
 
@@ -126,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.57.0.patch`:
+1. Save the patch as `patches/oxfmt@0.58.0.patch`:
 
-   ```diff patches/oxfmt@0.57.0.patch
-   diff --git a/dist/markdown-B5hFVJKQ.js b/dist/markdown-B5hFVJKQ.js
-   index 58322b247b263f87975c2a97eecfe0b97d7143c4..0f39f1901603026a391c6d343cb838dfaccbfd03 100644
-   --- a/dist/markdown-B5hFVJKQ.js
-   +++ b/dist/markdown-B5hFVJKQ.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.57.0": "patches/oxfmt@0.57.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.57.0` — its diff references a file hashed to that build (`dist/markdown-B5hFVJKQ.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/api-reference.mdx

@@ -3,7 +3,7 @@ title: OpenAPI / AsyncAPI
 description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
+Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. These docs ship one: the [Example API](/api) reference is generated from the Petstore spec by the config below.
 
 ```ts blume.config.ts lineNumbers
 openapi: {

package/docs/advanced/changelog.mdx

@@ -71,7 +71,7 @@ When your versions follow [semver](https://semver.org) and span more than one ma
 
 ## From GitHub Releases
 
-Rather than authoring entries by hand, point the built-in [`github-releases` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish:
+Rather than authoring entries by hand, point the built-in [`github-releases` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish. Blume's own [changelog](/changelog) is built this way:
 
 ```ts blume.config.ts
 content: {

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/export.mdx

@@ -1,6 +1,6 @@
 ---
 title: Export
-description: Let readers download any page as a PDF or EPUB.
+description: Let readers download any page as a PDF or EPUB — client-side, so static builds stay static.
 ---
 
 Blume can add an **Export** action to the [page actions](/docs/content/navigation#page-actions) beneath the table of contents, letting readers save the page they're on as a **PDF** or an **EPUB**. It's off by default and entirely client-side — no server, and [static](/docs/deployment) builds stay static.

package/docs/configuration/index.mdx

@@ -189,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:
@@ -248,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 },
 });
 ```
@@ -261,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: {
@@ -14,6 +14,7 @@ seo: {
   sitemap: true,
   robots: true,
   structuredData: true,
+  x: { handle: "@acme" },
 }
 ```
 
@@ -25,10 +26,34 @@ Every page renders the standard `<head>` tags from your config and frontmatter:
 
 - `<title>` — the page title plus your site `title`.
 - `<meta name="description">` and `og:description` — the page `description`, falling back to the site `description`.
-- `og:title` — the page title.
-- `<link rel="canonical">` — the page's absolute URL (when `deployment.site` is set).
+- `og:title` and `og:site_name` — the page title and your site `title`.
+- `<link rel="canonical">` and `og:url` — the page's absolute URL (when `deployment.site` is set).
+- `og:type` — `article` on blog posts and changelog entries, `website` elsewhere. Article pages also emit `article:published_time` and `article:modified_time` from the page's `date` and last-modified timestamp.
+- `og:image` — the [OG image](#open-graph-images) for the page. A generated card also declares its `og:image:width`, `og:image:height`, `og:image:type`, and `og:image:alt`, so a crawler can lay the card out without fetching it first; an `seo.image` you supply yourself declares none of these, since its size and format are unknown.
+- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` — the X card. Pages with an image get the wide `summary_large_image` variant; pages without one still get the compact `summary` card rather than rendering as a bare link.
 
-Override any of these per page with `seo` frontmatter:
+### X attribution
+
+X reads everything else on the card from the `og:*` tags, so the only values it can't infer are the accounts to credit. Set them under `seo.x` and Blume emits `twitter:site` (your site's account) and `twitter:creator` (the author's). The `@` is optional — `acme` and `@acme` both work.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  x: { handle: "@acme", creator: "@jane" },
+}
+```
+
+A page can claim its own author, which is what you want for a guest post:
+
+```yaml lineNumbers
+---
+title: How we shipped it
+seo:
+  x:
+    creator: "@guestauthor"
+---
+```
+
+Override any of the other tags per page with `seo` frontmatter:
 
 ```yaml lineNumbers
 ---
@@ -63,6 +88,11 @@ seo:
       type: "boolean",
       description: "Emit robots noindex and skip structured data.",
     },
+    "seo.x.creator": {
+      type: "string",
+      description:
+        "Credit this page to an X account (twitter:creator), overriding seo.x.creator from your config.",
+    },
   }}
 />
 
@@ -225,6 +255,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

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: The built-in JSX components — cards, columns, steps, tabs, accordions, badges, code groups, frames, trees, tooltips, type tables, live component previews, diffs, and a GitHub card — usable in any MDX page.
+description: Cards, steps, tabs, accordions, badges, code groups, frames, trees, type tables, live previews, and diffs — the built-in components, usable in any MDX page.
 ---
 
 Blume ships an accessible, themeable component set available in any `.mdx` page with **no imports**. Each one is shown below with a live preview and its source. Components are vanilla and React-free; React only switches on if you add your own island.
@@ -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

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/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.

package/docs/content/sources.mdx

@@ -159,7 +159,7 @@ Two flags control how remote content is fetched and what's included:
 blume dev --preview      # author workflow: see drafts live
 blume build --preview    # render a full preview build
 blume sync               # refresh remote content now
-blume sync --force        # ...ignoring any cached snapshot
+blume sync --force       # ...ignoring any cached snapshot
 ```
 
 ## Custom sources