blume 1.7.2 → 2.0.0

package/docs/configuration/search.mdx

@@ -1,11 +1,36 @@
 ---
 title: Search
-description: Client-side search that works out of the box with no API keys, plus optional hosted and semantic backends you can switch to as your docs grow.
+description: Client-side search that works out of the box with no API keys, plus hosted and semantic adapters you can switch to as your docs grow.
 ---
 
-Blume ships local search with no hosted infrastructure and no API keys. It runs in the browser, works in both `blume dev` and `blume build`, and indexes only your real content — navigation chrome and excluded pages are skipped. When you outgrow it, you can switch to a hosted or semantic backend without changing how search looks or behaves — only the `search.provider` you configure changes.
+Blume ships local search with no hosted infrastructure and no API keys. It runs in the browser, works in both `blume dev` and `blume build`, and indexes only your real content — navigation chrome and excluded pages are skipped. When you outgrow it, you can switch to a hosted or semantic backend without changing how search looks or behaves — only the adapter you pass to `search` changes.
 
-Blume reaches parity with Fumadocs' provider set: **Orama**, **FlexSearch**, **Algolia**, **Orama Cloud**, **Typesense**, and **Mixedbread** (plus **Pagefind**). Only the configured provider's SDK is installed into your project, so picking one backend never pulls in the others.
+Every backend is an **adapter** imported from `blume/search`: **Orama** (the default), **FlexSearch**, **Pagefind**, **Algolia**, **Orama Cloud**, **Typesense**, and **Mixedbread**. Each adapter owns its options, its runtime dependency, and the secrets it needs, so only the configured adapter's SDK is installed into your project — picking one backend never pulls in the others.
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { algolia } from "blume/search";
+
+export default defineConfig({
+  search: algolia({
+    appId: "YOUR_APP_ID",
+    apiKey: "YOUR_SEARCH_ONLY_KEY",
+    indexName: "docs",
+  }),
+});
+```
+
+An adapter is a plain description of the backend — not a live client — so Blume can inline it into the generated site and into an ejected project. Pass the adapter directly, or use the object form when you also want to set the [popular links](#popular-pages) or [indexing](#whats-indexed) options beside it:
+
+```ts blume.config.ts lineNumbers
+import { pagefind } from "blume/search";
+
+search: {
+  provider: pagefind(),
+  popular: [{ href: "/guides/getting-started", icon: "rocket", label: "Getting started" }],
+  indexing: { includeCodeBlocks: true },
+},
+```
 
 ## Using search
 
@@ -27,7 +52,7 @@ search: {
 },
 ```
 
-Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG (same _inputs_ as nav icons), defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.
+Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG (same _inputs_ as nav icons), defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback. Leaving `provider` out of the object form keeps the default Orama adapter.
 
 Write `href` as if the site were mounted at the root — a `basePath` is applied for you, the same as `navigation.featured`. External URLs pass through untouched.
 
@@ -52,31 +77,31 @@ search: {
 },
 ```
 
-Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/discoverability/markdown), so an `ai.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted providers cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.
+Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/discoverability/markdown), so an `agents.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted adapters cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.
 
 On a [versioned](/docs/content/versioning) site, results default to the version being viewed, with an "All versions" toggle in the dialog footer (remembered per reader). Cross-version hits name their version on the row. Orama, FlexSearch, Algolia, and Typesense honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.
 
 ## Tags
 
-Add `search.tags` to a page's frontmatter to group it under a filter in the search dialog — readers can narrow results to a tag with a click. Tags also become a facet on the hosted providers.
+Add `search.tags` to a page's frontmatter to group it under a filter in the search dialog — readers can narrow results to a tag with a click. Tags also become a facet on the hosted adapters.
 
 ```yaml
 search:
   tags: [api, reference]
 ```
 
-## Providers
+## Adapters
 
-The client-side providers are keyless and need no extra config. The hosted ones take **public** credentials in `blume.config.ts` (safe to ship to the browser) and read their **secret** admin key from an environment variable at build time — the secret never lands in the config or the client bundle.
+The client-side adapters are keyless and need no options — their clients are configured from `i18n` (or, for Pagefind, from the built HTML), so an unknown key is rejected by config validation rather than ignored. The hosted ones take **public** credentials (safe to ship to the browser) and read their **secret** admin key from an environment variable at build time — the secret never lands in the config or the client bundle. Every option you pass to a hosted adapter is kept verbatim and handed to its search client in the browser (or, for Mixedbread, to the search endpoint), so an option Blume doesn't name still reaches the SDK — Algolia's `liteClient`, the Typesense `Client`, or `OramaClient`. Those options must be JSON values — the descriptor is inlined into the generated project as a literal, so a function, `undefined`, or a bigint fails config validation with a path instead of vanishing on the way.
 
 ### Orama (default)
 
-Blume's default engine. It builds a JSON index served at `/blume-search.json` and queries it in the browser — instant, client-side, and live in `blume dev` as you edit. No keys, no service.
+Blume's default engine. It builds a JSON index served at `/blume-search.json` and queries it in the browser — instant, client-side, and live in `blume dev` as you edit. No keys, no service. Omitting `search` entirely selects it; spell it out only when you want to be explicit:
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "orama", // default
-}
+import { orama } from "blume/search";
+
+search: orama(),
 ```
 
 #### Non-Latin scripts
@@ -101,9 +126,9 @@ A second keyless, client-side option. It reuses the same `/blume-search.json` in
 FlexSearch has no equivalent segmentation hook, so for sites in a non-Latin script prefer Orama (the default) or [Pagefind](#pagefind), whose `pagefind_extended` binary indexes a broad set of languages and segments Chinese, Japanese and Korean natively.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "flexsearch",
-}
+import { flexsearch } from "blume/search";
+
+search: flexsearch(),
 ```
 
 ### Pagefind
@@ -111,26 +136,25 @@ search: {
 For very large docs, opt into [Pagefind](https://pagefind.app). It indexes your built HTML and loads the index in shards on demand, keeping the initial payload tiny no matter how big the site grows.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "pagefind",
-}
+import { pagefind } from "blume/search";
+
+search: pagefind(),
 ```
 
-Pagefind only runs during `blume build`, so search isn't available in `blume dev` with this provider.
+Pagefind only runs during `blume build`, so search isn't available in `blume dev` with this adapter. It indexes each docs page's article — not the header, sidebar, or footer around it — so custom pages built on `PageLayout`, the 404 page, and the generated changelog index aren't in its results.
 
 ### Algolia
 
 The browser queries [Algolia](https://www.algolia.com) directly with your search-only key. Each `blume build` replaces the index using the admin key from `ALGOLIA_ADMIN_API_KEY` (the build warns and skips the upload if it's unset). The whole index is replaced on every sync, so pages you delete or rename don't linger as stale results.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "algolia",
-  algolia: {
-    appId: "YOUR_APP_ID",
-    indexName: "docs",
-    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
-  },
-}
+import { algolia } from "blume/search";
+
+search: algolia({
+  appId: "YOUR_APP_ID",
+  apiKey: "YOUR_SEARCH_ONLY_KEY", // public
+  indexName: "docs",
+}),
 ```
 
 ### Orama Cloud
@@ -138,14 +162,13 @@ search: {
 Hosted Orama. The browser queries your index endpoint with the public API key; `blume build` pushes records to the index using `ORAMA_PRIVATE_API_KEY`. Set `indexId` to enable the sync.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "orama-cloud",
-  oramaCloud: {
-    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
-    apiKey: "YOUR_PUBLIC_API_KEY",
-    indexId: "your-index-id", // for the build-time sync
-  },
-}
+import { oramaCloud } from "blume/search";
+
+search: oramaCloud({
+  endpoint: "https://cloud.orama.run/v1/indexes/your-index",
+  apiKey: "YOUR_PUBLIC_API_KEY",
+  indexId: "your-index-id", // for the build-time sync
+}),
 ```
 
 ### Typesense
@@ -153,38 +176,36 @@ search: {
 Self-hosted or cloud [Typesense](https://typesense.org). The browser queries the collection with the search-only key; `blume build` recreates the collection and imports documents using `TYPESENSE_ADMIN_API_KEY`. The collection is dropped and rebuilt on every sync so deleted or renamed pages don't linger as stale results — if you hand-tune the collection's settings, reapply them after a build.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "typesense",
-  typesense: {
-    host: "xyz.a1.typesense.net",
-    collection: "docs",
-    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
-    // port + protocol default to 443 / https
-  },
-}
+import { typesense } from "blume/search";
+
+search: typesense({
+  host: "xyz.a1.typesense.net",
+  collection: "docs",
+  apiKey: "YOUR_SEARCH_ONLY_KEY", // public
+  // port + protocol default to 443 / https
+}),
 ```
 
 ### Mixedbread
 
-Semantic search via [Mixedbread](https://www.mixedbread.com). Queries are proxied through a generated `/api/search` endpoint that holds your key, so this provider **requires server output** (`deployment.output: "server"`). The endpoint reads `MIXEDBREAD_API_KEY`. Sync your content to the store with the Mixedbread CLI in your build, e.g. `mxbai vs sync <STORE_ID> ./content --ci`.
+Semantic search via [Mixedbread](https://www.mixedbread.com). Queries are proxied through a generated `/api/search` endpoint that holds your key, so this adapter **requires server output**: a host adapter such as `deployment: vercel()` from `blume/deploy` (see [Server rendering](/docs/deployment#server-rendering)). The endpoint reads `MIXEDBREAD_API_KEY`. Sync your content to the store with the Mixedbread CLI in your build, e.g. `mxbai vs sync <STORE_ID> ./content --ci`.
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "mixedbread",
-  mixedbread: {
-    storeId: "YOUR_STORE_ID",
-  },
-}
+import { mixedbread } from "blume/search";
+
+search: mixedbread({
+  storeId: "YOUR_STORE_ID",
+}),
 ```
 
 ### Disabling search
 
 ```ts blume.config.ts lineNumbers
-search: {
-  provider: "none",
-}
+search: false,
 ```
 
+Set `provider: false` in the object form instead when you still want `indexing` to apply to the MCP server's index.
+
 ## Excluding pages
 
 Only indexable pages are searched. A page is left out of the index when it sets `search.exclude` in frontmatter:

package/docs/configuration/theming.mdx

@@ -214,21 +214,27 @@ Set a token under `:root` for light mode and under `:root[data-theme="dark"]` fo
 
 ### Design tokens
 
-| Token                       | Controls                                  |
-| --------------------------- | ----------------------------------------- |
-| `--blume-background`        | Page background                           |
-| `--blume-foreground`        | Body text                                 |
-| `--blume-muted`             | Subtle surfaces — callouts, table headers |
-| `--blume-muted-foreground`  | Secondary text                            |
-| `--blume-border`            | Borders and dividers                      |
-| `--blume-accent`            | Accent color                              |
-| `--blume-accent-foreground` | Text and icons on an accent background    |
-| `--blume-action`            | Secondary accent (defaults to accent)     |
-| `--blume-code-background`   | Code block surface                        |
-| `--blume-radius`            | Corner radius                             |
-| `--blume-font-display`      | Heading font                              |
-| `--blume-font-body`         | Body / UI font                            |
-| `--blume-font-mono`         | Code font                                 |
+| Token | Controls |
+| --- | --- |
+| `--blume-background` | Page background |
+| `--blume-foreground` | Body text |
+| `--blume-muted` | Subtle surfaces — callouts, table headers |
+| `--blume-muted-foreground` | Secondary text |
+| `--blume-border` | Borders and dividers |
+| `--blume-accent` | Accent color |
+| `--blume-accent-foreground` | Text and icons on an accent background |
+| `--blume-action` | Secondary accent (defaults to accent) |
+| `--blume-action-foreground` | Text and icons on an action background (defaults to accent foreground) |
+| `--blume-code-background` | Code block surface |
+| `--blume-code-highlight`, `--blume-code-highlight-border` | Background and left rule of a highlighted code line (`// [!code highlight]` or a `{1,4-5}` range) |
+| `--blume-code-add`, `--blume-code-add-border` | Background and left rule of an added line (`// [!code ++]`) |
+| `--blume-code-remove`, `--blume-code-remove-border` | Background and left rule of a removed line (`// [!code --]`) |
+| `--blume-code-word`, `--blume-code-word-border` | Background and outline of a highlighted word (`// [!code word:…]`) |
+| `--blume-content-width` | Max width of the prose column — article, breadcrumb, table of contents, feedback, and pagination (default `42rem`) |
+| `--blume-radius` | Corner radius |
+| `--blume-font-display` | Heading font |
+| `--blume-font-body` | Body / UI font |
+| `--blume-font-mono` | Code font |
 
 Set a `--blume-font-*` token to any font stack to use a font outside the curated list, or to fall back to the system stack:
 
@@ -252,6 +258,9 @@ Blume's theme is built with Tailwind v4 internally, and your project's `.astro`,
 | `--blume-accent`            | `bg-accent`, `text-accent` |
 | `--blume-accent-foreground` | `text-accent-foreground`   |
 | `--blume-action`            | `bg-action`, `text-action` |
+| `--blume-action-foreground` | `text-action-foreground`   |
+| `--blume-code-background`   | `bg-code`                  |
+| `--blume-content-width`     | `max-w-content`            |
 | `--blume-radius`            | `rounded-blume`            |
 | `--blume-font-display`      | `font-display`             |
 | `--blume-font-body`         | `font-sans`                |

package/docs/content/components.mdx

@@ -31,9 +31,11 @@ Cards link to a destination with an icon, title, and short blurb. Group them wit
 
 `Card` takes `title`, an optional `href` (omit it for a non-clickable card), and an `icon` from Blume's built-in icon set. `CardGroup` takes `cols` (default `2`).
 
+A card also takes `img`, an image across its top (or beside the text from the `sm` breakpoint up, with `horizontal`); `cta`, a call-to-action line in the accent color beneath the text; `arrow`, an arrow after the title and the CTA (shown by default only for external links); `type`, which tints the card and picks a matching icon the way a callout does (`note`, `info`, `tip`, `check`, `warning`, or `danger`); and `color`, any CSS color for the icon.
+
 ## Steps
 
-A numbered vertical sequence for ordered instructions — installs, setup flows, and tutorials where the order matters. Each `Step` takes a `title`.
+A numbered vertical sequence for ordered instructions — installs, setup flows, and tutorials where the order matters. Each `Step` takes a `title` and an optional `icon`, shown in its marker in place of the number. `titleSize` on `Steps` sizes the step titles like body text (`p`, the default) or an `h4`, `h3`, or `h2` heading.
 
 <Steps>
   <Step title="Install Blume">Add the package to your project.</Step>
@@ -71,7 +73,9 @@ Switch between equivalent content in place — language variants, OS-specific co
 
 Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page.
 
-Groups with same-titled tabs switch together — pick "macOS" in one and every group with a macOS tab follows. Add `syncKey` to scope that syncing: only groups sharing the same key switch together, so unrelated groups that happen to share a tab title stay independent.
+Groups with same-titled tabs switch together — pick "macOS" in one and every group with a macOS tab follows. Add `syncKey` to scope that syncing: only groups sharing the same key switch together, so unrelated groups that happen to share a tab title stay independent, or `sync={false}` to keep a group out of it entirely.
+
+The active tab is written to the URL hash, so a link opens on it; pass `hash={false}` to leave the URL alone. `defaultTabIndex` picks the tab that opens first (zero-based, default `0`) when no link or synced selection chooses one. `dropdown` swaps the tab strip for a select menu (in the boxed layout only), `borderBottom={false}` drops the rule under the strip, and each `Tab` takes an `icon` shown before its title.
 
 <Tabs inline param="install">
   <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
@@ -139,6 +143,16 @@ A negative or breaking state, such as a deprecation.
 <Badge variant="danger">Deprecated</Badge>
 ```
 
+### Color, shape, and size
+
+Beyond `variant`, a badge takes `color` — a named hue (`blue`, `green`, `orange`, `purple`, `red`, `teal`, `violet`, `yellow`), a neutral (`gray`, `surface`, `white`, `surface-destructive`, or `white-destructive`), or a hex value — plus `shape` (`rounded`, the default, or `pill`), `size` (`xs`, `sm`, `md` by default, or `lg`), `stroke` for an outline instead of a fill, `icon` for an icon before the label, `tooltip` for hover text, and `disabled` to dim it.
+
+An outlined purple pill with an icon: <Badge color="purple" icon="sparkles" shape="pill" stroke>Preview</Badge>
+
+```astro
+<Badge color="purple" icon="sparkles" shape="pill" stroke>Preview</Badge>
+```
+
 ## Icon
 
 Render an icon by name — the same `icon` prop powers cards, steps, tabs, and sidebar entries. Names come from [Lucide](https://lucide.dev/icons), lowercase and kebab-cased (`rocket`, `gauge`, `book-open`).
@@ -334,7 +348,7 @@ Embed a YouTube video in a responsive, privacy-friendly (`youtube-nocookie.com`)
 
 ## Color
 
-Show color swatches with copyable hex values — useful for documenting a palette or brand colors. Use `variant="compact"` for a swatch list, or `variant="table"` with `Color.Row` to group them. Each `Color.Item` takes a `name` and a `value` (a hex string, or `{ light, dark }` for theme-aware colors).
+Show color swatches with copyable hex values — useful for documenting a palette or brand colors. Use `variant="compact"` for a swatch list, or `variant="table"` with `Color.Row` to group them. Each `Color.Item` takes a `name` and a `value` (a hex string, or `{ light, dark }` for theme-aware colors); a theme-aware swatch copies the value for the theme the reader is viewing.
 
 <Color variant="compact">
   <Color.Item name="blue-500" value="#3B82F6" />
@@ -424,7 +438,7 @@ A clickable preview that leads with a visual — an icon or image — above a ti
 
 ## Prompt
 
-A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard when the **Copy prompt** button is pressed. `actions` controls the buttons (e.g. `["copy", "cursor"]`).
+A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard as Markdown, with its links, lists, and code intact, when the **Copy prompt** button is pressed. `actions` controls the buttons (e.g. `["copy", "cursor"]`).
 
 <Prompt
   description="Ask the model to **document** an endpoint."
@@ -546,7 +560,7 @@ export interface ButtonProps {
 
 ## GitHub info
 
-A card linking to a GitHub repository with its live star and fork counts. Counts are fetched at build time — no client JavaScript — and the card still renders if the API is unreachable. Pass `owner` and `repo`, or omit them to use the repository from your `blume.config`. Set a `GITHUB_TOKEN` environment variable to lift the API rate limit.
+A card linking to a GitHub repository with its live star and fork counts. Counts are fetched at build time — no client JavaScript — and the card still renders if the API is unreachable. Pass `owner` and `repo`, or omit them to use the repository from your `blume.config`. Set a `GITHUB_TOKEN` environment variable to lift the API rate limit; a `token` prop overrides it for one card, but the environment variable keeps the token out of your content.
 
 The card reads the instance from [`github.host`](/docs/configuration#github-enterprise), so on an Enterprise-hosted site explicit `owner`/`repo` address that instance too. Pass `host` to point one card somewhere else — a public project from an Enterprise site, say; the REST base is derived from it the same way it is from `github.host`.
 
@@ -659,6 +673,8 @@ import CodeBlock from "blume/components/content/CodeBlock.astro";
 <CodeBlock lang="ts" code={source} />
 ```
 
+`title` sets the header label — a filename, say — which otherwise shows the language, and `icons={false}` hides the language's brand icon, as [`markdown.code.icons`](/docs/content/syntax#code-blocks) does for fences.
+
 To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:
 
 ```ts

package/docs/{reference → content}/frontmatter.mdx

@@ -29,6 +29,27 @@ Every page accepts the following frontmatter. All fields are optional.
       default: "false",
       description: "Exclude from production builds.",
     },
+    deprecated: {
+      type: "boolean",
+      default: "false",
+      description:
+        "Mark the page deprecated: its sidebar row gets a deprecated pill (a translatable UI string).",
+    },
+    hidden: {
+      type: "boolean",
+      default: "false",
+      description: "Shorthand for sidebar.hidden.",
+    },
+    noindex: {
+      type: "boolean",
+      default: "false",
+      description: "Shorthand for seo.noindex.",
+    },
+    icon: {
+      type: "string",
+      description:
+        "Lucide icon for the page's sidebar row when sidebar.icon isn't set (sidebar.icon wins).",
+    },
     lastModified: {
       type: "string",
       description:
@@ -49,6 +70,8 @@ sidebar:
   display: page
 ```
 
+`hidden` removes the page from the sidebar and from previous/next pagination. On a folder's `index` page it removes only the page's own row: the group row keeps linking to the page, and previous/next links still pass through it.
+
 `display` sets the render mode of the page's folder group ([per-group overrides](/docs/content/navigation#per-group-overrides)) and is only meaningful on a folder's `index` page under the generated sidebar — anywhere else (a non-index page, the content root's own `index` page, or any page under an explicit `navigation.sidebar`) it has no group to configure, and Blume warns with `BLUME_SIDEBAR_DISPLAY_IGNORED`.
 
 ## SEO
@@ -60,8 +83,12 @@ seo:
   image: /og/install.png
   canonical: https://acme.com/install
   noindex: false
+  x:
+    creator: "@jane"
 ```
 
+`noindex` emits a robots `noindex`, drops the page from the sitemap, and skips its structured data. `x.creator` credits the page to an X account (`twitter:creator`) — a guest post's author, say. See [Metadata](/docs/discoverability/metadata#per-page-overrides) for every field.
+
 ## Search
 
 ```yaml lineNumbers
@@ -70,6 +97,15 @@ search:
   tags: [api]
 ```
 
+## AI
+
+```yaml lineNumbers
+ai:
+  exclude: true
+```
+
+`ai.exclude` keeps the page out of [`llms.txt` and `llms-full.txt`](/docs/discoverability/llms-txt#excluding-a-page). The page still renders, stays in search, and keeps its place in the sitemap.
+
 ## Changelog
 
 Changelog entries (`type: changelog`) accept an optional `changelog` object for richer feed and display metadata:
@@ -145,6 +181,6 @@ status: enforced
 
 Per-type keys follow the same validation rules as `extend`, scoped to pages whose resolved `type` matches — including pages that set no `type`, when the declaration is for [`content.defaultType`](/docs/configuration#content). A key belongs to one declaration, site-wide or per-type, not both. And a key declared only for another type stays unknown elsewhere, so a stray `status` on a plain doc page still fails the build.
 
-A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
+A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
 
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/docs/content/i18n.mdx

@@ -20,7 +20,7 @@ i18n: {
 }
 ```
 
-Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default). An optional `style` gives [`blume translate`](/docs/reference/translate) freeform guidance for the locale — register, dialect, terminology, e.g. `"Brazilian Portuguese, informal você"` — so the choice is pinned from the very first translation instead of decided by the agent.
+Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default). An optional `style` gives [`blume translate`](/docs/cli/translate) freeform guidance for the locale — register, dialect, terminology, e.g. `"Brazilian Portuguese, informal você"` — so the choice is pinned from the very first translation instead of decided by the agent.
 
 ## Organize translated content
 
@@ -83,7 +83,7 @@ i18n: {
 
 Each language gets its own sidebar, built from that locale's files — so translations can diverge in structure, ordering, or labels. Folder [`meta.ts`](/docs/content/meta) files resolve per locale, too: under the default `dir` parser, put a `meta.ts` under `fr/guides/` to order the French group independently. Under the `dot` parser translations sit next to the originals, so a folder's `meta.ts` applies to every locale. Everything else about [navigation](/docs/content/navigation) works the same, per language.
 
-Header tabs are configured, not derived from content, so their labels localize in `blume.config.ts`: a tab `label` accepts a per-locale map (`{ en: "Docs", fr: "Documentation" }`) alongside the plain-string form, falling back to the default locale's entry for locales you haven't filled in. See [Tabs](/docs/content/navigation#tabs).
+Header tabs are configured, not derived from content, so their labels localize in `blume.config.ts`: a tab `label` accepts a per-locale map (`{ en: "Docs", fr: "Documentation" }`) alongside the plain-string form, falling back to the default locale's entry for locales you haven't filled in. See [Tabs](/docs/content/navigation#tabs). Tab paths, header links, and the header logo's link move into the reader's locale too, whenever that locale serves the route, so the header stays inside one language. A route only the default locale serves — a [custom page](/docs/advanced/custom-pages) or the generated [changelog](/docs/advanced/changelog) index — keeps its own path instead of pointing at a localized URL that would 404.
 
 ## Fallbacks
 
@@ -96,7 +96,9 @@ i18n: {
 }
 ```
 
-Fallback pages are excluded from the search index and aren't advertised as real translations in `hreflang`, so untranslated content doesn't compete for ranking. They still appear in that locale's sidebar, so navigation stays complete — a reader can reach every page in any language.
+Fallback pages point their canonical link at the page they copy, are left out of the search index, `llms.txt`, and the MCP and JSON API page lists, and aren't advertised as real translations in `hreflang`, so untranslated content doesn't compete for ranking. They still appear in that locale's sidebar, so navigation stays complete — a reader can reach every page in any language.
+
+Release notes from a [`githubReleases()`](/docs/content/sources#github-releases) source are the exception: they're published in one language, so they're never copied to other locales' URLs and show no language switcher.
 
 :::tip
 Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links.
@@ -106,11 +108,11 @@ Start by translating your most important pages — the homepage, quickstart, and
 
 Write internal links the way you would in the default locale — `[Setup](/guides/setup)`, `<Card href="/guides/setup">` — in every language, including translated pages. When a page renders under a locale prefix, Blume moves each root-relative page link into that locale (`/fr/guides/setup`) as long as the route is served there, as a real translation or as a fallback page. A link with no per-locale variant — a custom page, a generated route, or a missing translation on a site with fallbacks disabled — keeps its authored target rather than pointing at a 404, and a link that already carries a locale prefix (`/de/guides/setup`) is left alone, so cross-locale links stay explicit.
 
-Anchors travel with the link, so heading ids have to agree across languages. [`blume translate`](/docs/reference/translate) takes care of that: every translated heading is pinned to its source heading's id with a trailing `[#id]` marker. In a translation you write by hand, pin the headings yourself with the same [`[#custom-id]` marker](/docs/content/syntax#custom-anchors) — otherwise `#ordering` won't match the French page's auto-generated `#ordre`, and `blume validate` reports the mismatch against the translated page a reader actually lands on.
+Anchors travel with the link, so heading ids have to agree across languages. [`blume translate`](/docs/cli/translate) takes care of that: every translated heading is pinned to its source heading's id with a trailing `[#id]` marker. In a translation you write by hand, pin the headings yourself with the same [`[#custom-id]` marker](/docs/content/syntax#custom-anchors) — otherwise `#ordering` won't match the French page's auto-generated `#ordre`, and `blume validate` reports the mismatch against the translated page a reader actually lands on.
 
 ## Translating with an agent
 
-You don't have to fill in the locales by hand. [`blume translate`](/docs/reference/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli)):
+You don't have to fill in the locales by hand. [`blume translate`](/docs/cli/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli)):
 
 ```bash
 blume translate --claude
@@ -120,7 +122,7 @@ Blume validates each result's structure — frontmatter, code fences, links —
 
 ## The language switcher
 
-When i18n is on, a language switcher appears in the header automatically, generated from your `locales`. For each page it links the matching translation in every language; where a translation is missing it links the fallback page and marks it as not translated. There's nothing to configure.
+When i18n is on, a language switcher appears in the header automatically, generated from your `locales`. For each page it links the matching translation in every language; where a translation is missing it links the fallback page and marks it as not translated. There's nothing to configure. Pages from a [GitHub Releases](/docs/content/sources#github-releases) source are the exception: release notes exist in one language only, so those pages render without a switcher.
 
 ## Translated UI
 

package/docs/content/includes.mdx

@@ -3,7 +3,7 @@ title: Includes
 description: Reuse content across pages — splice shared Markdown, MDX, or code files into any page with the include syntax.
 ---
 
-Write a snippet once and splice it into any page. An `<include>` statement on its own line embeds another file at build time, as if its content were written inline — headings join the page's table of contents, text is indexed by search, and the content appears in the page's `.md` mirror and llms-full.txt.
+Write a snippet once and splice it into any page. An `<include>` statement on its own line embeds another file at build time, as if its content were written inline — headings join the page's table of contents, text is indexed by search, and the content appears in the page's `.md` mirror and llms-full.txt. A statement a formatter wraps across lines still splices, and one Blume can't parse raises a `BLUME_INCLUDE_MALFORMED` warning at its line instead of rendering as a raw tag.
 
 ```mdx
 <include>./_snippets/prerequisites.mdx</include>
@@ -48,9 +48,7 @@ A target that isn't `.md`/`.mdx` is embedded as a fenced code block, with the la
 ```mdx
 <include>./examples/config.ts</include>
 
-<include lang="ts" meta='title="blume.config.ts"'>
-  ../blume.config.ts
-</include>
+<include meta='title="config.ts"'>./examples/config.ts</include>
 
 <include lang="mdx">./_snippets/prerequisites.mdx</include>
 ```

package/docs/content/index.mdx

@@ -113,7 +113,7 @@ The contents list your `##` and `###` headings (H2 and H3). A page with no headi
 ## Where to next
 
 <CardGroup cols={2}>
-  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file">
+  <Card title="Frontmatter" href="/docs/content/frontmatter" icon="file">
     Page metadata: title, description, sidebar, SEO, and search.
   </Card>
   <Card title="Syntax" href="/docs/content/syntax" icon="book-open">

package/docs/content/islands.mdx

@@ -30,29 +30,31 @@ Islands are for **interactive** UI. For a static component you reuse across page
 
 ## Registering islands in `components.ts`
 
-If you'd rather keep islands next to the rest of your components — or give them a different name than the file — register them with `defineComponents`. The `islands` group is exactly like the `islands/` folder: each entry is available in every MDX page and hydrates (defaulting to `client: "visible"`).
+If you'd rather keep islands next to the rest of your components — or give them a different name than the file — register them with `defineComponents` as an `mdx` entry with a `client` mode. That's all an island is: an MDX component that hydrates. Each entry is available in every MDX page, and an entry with the same name as an `islands/` file replaces it.
 
 ```ts components.ts
 import { defineComponents } from "blume";
 import Counter from "./widgets/Counter.tsx";
 
 export default defineComponents({
-  islands: {
-    Counter, // <Counter /> in any MDX page, hydrated
+  mdx: {
+    Counter: { component: Counter, client: "visible" }, // <Counter /> in any MDX page, hydrated
   },
 });
 ```
 
-Reference the component by import or by a path string, and set a hydration mode per island with the descriptor form:
+Reference the component by import or by a path string, and pick the hydration mode per island (`"media"` takes a `media` query alongside it):
 
 ```ts components.ts
 export default defineComponents({
-  islands: {
+  mdx: {
     Chart: { component: "./widgets/Chart.tsx", client: "only" },
   },
 });
 ```
 
+Unlike the folder, there's no default: an `mdx` entry without `client` renders as static HTML, and Blume warns when that entry is a React, Vue, or Svelte component. Blume reads `components.ts` statically, so an entry must be an imported component, a path string, or a `{ component, client, media }` object literal — see [Customization](/docs/configuration/customization#reference-form) for the accepted forms and the error you get otherwise.
+
 ## Hydration
 
 By default an island uses `client:visible`: it hydrates when the reader scrolls it into view, so a page full of islands still loads instantly. Opt into a different strategy with an `export const client` in the island file:
@@ -72,6 +74,9 @@ export default function Chart() {
 | `"load"` | Immediately on page load | Above-the-fold, must-be-instant UI |
 | `"idle"` | When the main thread is idle | Non-urgent interactivity |
 | `"only"` | Client only, never server-rendered | Libraries that need `window`/`document` (charts, editors) |
+| `"media"` _(`components.ts` only)_ | When a CSS media query matches | UI that only runs at some sizes, like a mobile-only menu |
+
+`"media"` needs the query beside it, so it's available only to a [`components.ts` entry](#registering-islands-in-componentsts) — `{ component: Menu, client: "media", media: "(max-width: 50em)" }`. An `islands/` file that declares it falls back to `"visible"` with a warning.
 
 ## Frameworks
 

package/docs/content/meta.mdx

@@ -75,7 +75,7 @@ A locale-specific `meta.ts` still overrides the shared `meta.$.ts` for that lang
   <Card title="Navigation" href="/docs/content/navigation" icon="menu">
     How the sidebar, breadcrumbs, and tabs are built.
   </Card>
-  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file">
+  <Card title="Frontmatter" href="/docs/content/frontmatter" icon="file">
     Per-page metadata, including the `sidebar` overrides.
   </Card>
 </CardGroup>

package/docs/content/meta.ts

@@ -5,6 +5,7 @@ export default defineMeta({
   pages: [
     "navigation",
     "meta",
+    "frontmatter",
     "syntax",
     "includes",
     "components",