blume 0.1.5 → 0.3.0

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

@@ -108,6 +108,8 @@ export interface PageRecord {
     format: "md" | "mdx";
     /** Internal/asset links discovered in the page (for validation). */
     links: PageLink[];
+    /** Capitalized JSX component tags used in the body (`.mdx` only). */
+    componentsUsed?: string[];
     /** Resolved "last updated" ISO date, when the feature is enabled. */
     lastModified?: string;
 }
@@ -168,8 +170,6 @@ export interface NavSidebarVariant {
 export interface NavChromeVariant {
     path: string;
     banner?: ResolvedConfig["banner"];
-    footer?: ResolvedConfig["footer"];
-    navbar?: ResolvedConfig["navbar"];
 }
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {

package/docs/02-deployment.mdx

@@ -118,8 +118,27 @@ Map old URLs to new ones in `blume.config.ts`:
 redirects: [{ from: "/old", to: "/new", status: 301 }];
 ```
 
-`status` accepts `301`, `302`, `307`, or `308` (default `301`). Static builds
-emit redirect pages; server builds handle redirects at request time.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds
+handle redirects at request time. Static builds emit redirect pages **and**
+platform files so your host issues a real HTTP redirect: `_redirects` (Netlify,
+Cloudflare Pages), `vercel.json` (Vercel), and `blume-redirects.json` — a
+structured manifest for anything else (nginx/Apache rules, an edge worker). A
+`_redirects` or `vercel.json` you ship in `public/` is left untouched.
+
+## Environment variables
+
+When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's
+missing — so the problem surfaces early instead of at the first request:
+
+| Feature                                 | Variable                              |
+| --------------------------------------- | ------------------------------------- |
+| Ask AI (AI Gateway)                     | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
+| Ask AI (OpenRouter / OpenAI-compatible) | the provider's `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.
 
 ## Build summary
 

package/docs/advanced/changelog.mdx

@@ -5,7 +5,8 @@ description: Author release notes as content, and Blume builds a timeline page a
 
 Blume ships a changelog out of the box. Write each release as a normal content
 file, mark it `type: changelog`, and Blume collects every entry into a generated
-timeline page and an RSS feed — no layout to build, no list to maintain.
+timeline page and an RSS feed — no layout to build, no list to maintain. Or skip
+the files entirely and [source your changelog from GitHub Releases](#from-github-releases).
 
 ## Write an entry
 
@@ -72,6 +73,32 @@ replace it with your own design, add a [custom page](/docs/advanced/custom-pages
 `pages/changelog.astro` — it takes over and Blume stops generating the default
 timeline.
 
+## 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:
+
+```ts blume.config.ts
+content: {
+  sources: [
+    { type: "filesystem", root: "content" },
+    {
+      type: "github-releases",
+      prefix: "changelog",
+      owner: "acme",
+      repo: "sdk",
+    },
+  ],
+}
+```
+
+The release name becomes the title, its tag becomes `changelog.version`, and its
+published date sorts the timeline. A private repo authenticates with the
+`GITHUB_TOKEN` environment variable. See
+[Content sources](/docs/content/sources#github-releases) for every option.
+
 ## The RSS feed
 
 Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted

package/docs/advanced/custom-pages.mdx

@@ -167,6 +167,51 @@ const posts = (await getCollection("docs"))
 </ul>
 ```
 
+## Runtime helpers
+
+`blume/runtime` bundles the common data patterns so you don't reach into
+`blume:data` internals.
+
+**`getBlumeCollection(data, query?)`** selects content routes — filtered by
+collection, locale, or path prefix, with drafts and hidden pages excluded and the
+result sorted by path — which is exactly what a custom index needs:
+
+```astro pages/blog/index.astro lineNumbers
+---
+import data from "blume:data";
+import { getBlumeCollection } from "blume/runtime";
+
+const posts = getBlumeCollection(data, { prefix: "/blog" });
+---
+
+<ul>
+  {posts.map((post) => (
+    <li><a href={post.path}>{post.title}</a></li>
+  ))}
+</ul>
+```
+
+**`<BlumePage>`** renders a content entry's body inside a custom page, with
+Blume's built-in MDX components (callouts, cards, steps…) already wired in — for
+featuring a doc on a landing page or building a bespoke index that shows real
+content:
+
+```astro pages/index.astro lineNumbers
+---
+import BlumePage from "blume/components/BlumePage.astro";
+import data from "blume:data";
+import { getBlumeCollection } from "blume/runtime";
+
+const [intro] = getBlumeCollection(data, { prefix: "/docs" });
+---
+
+{intro && <BlumePage id={intro.entryId} />}
+```
+
+Pass `components` to add your own overrides or islands (which live in the
+generated runtime and aren't imported by default), and `collection` to read from
+a collection other than `"docs"`.
+
 ## Using the site layout
 
 `RootLayout` gives a custom page the full docs chrome — header, sidebar, search,
@@ -211,7 +256,24 @@ generated `og:image` automatically: Blume renders an Open Graph card for every
 static custom page — the home included, the most-shared URL — served at
 `/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title
 with the description as its eyebrow; a deeper page is titled from its last path
-segment. Set `ogImage` or `canonical` explicitly to override.
+segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage`
+takes a root-relative path — a file in `public/`, resolved against
+[`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an
+external URL, which passes through untouched:
+
+```astro pages/index.astro lineNumbers
+<PageLayout
+  siteUrl={config.site}
+  ogEnabled={config.og.enabled}
+  ogImage="/opengraph-image.png"
+  page={{ title: config.title }}
+>
+  <!-- page content -->
+</PageLayout>
+```
+
+Only this page changes — every other route keeps its generated card — so it's how
+you give the home page alone a bespoke share image.
 
 `page.title` is used verbatim as the document title (no `- siteTitle` suffix),
 since marketing pages usually set their own. To give a custom page the full docs
@@ -233,7 +295,6 @@ import data from "blume:data";
   headings={[]}
   themeMode={data.config.theme.mode}
   searchEnabled={data.config.search.enabled}
-  searchProvider={data.config.search.provider}
   indexable={true}
 >
   <h1>Pricing</h1>

package/docs/configuration/ai.mdx

@@ -84,6 +84,24 @@ ai: {
 }
 ```
 
+### Grounding
+
+Ask AI is **grounded in your docs**. For each question it retrieves the most
+relevant pages — using the same lexical [Orama](/docs/configuration/search) index
+that powers on-page search — and injects them into the model's system prompt, so
+answers come from your content instead of the model's own knowledge. The
+assistant is told to answer only from the retrieved pages, to say when something
+isn't covered, and to cite the pages it drew from.
+
+The page the reader is currently on is added to the context first and used to
+scope retrieval to that page's language, so answers stay relevant to where they
+are in the docs. Retrieval runs at request time from a snapshot baked into the
+build, so it works regardless of your [search](/docs/configuration/search)
+provider — even when search is set to `none` — and needs no configuration.
+
+Grounding is on for every backend except **[Inkeep](#backends)**, which runs its
+own retrieval over the content you've indexed in its dashboard.
+
 ### Server output required
 
 Ask AI is a server route (`POST /api/ask`), so it can't run on a static build.
@@ -151,9 +169,8 @@ at a different env var or proxy.
 
 :::note
 **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it
-runs its own retrieval — rather than from this site's pages. The other backends
-are plain model passthroughs: the endpoint streams the reader's messages straight
-to the model.
+runs its own retrieval — so Blume leaves it ungrounded. Every other backend is
+[grounded](#grounding) in this site's pages.
 :::
 
 Keys are read with `process.env`, which covers the Node, Vercel, and Netlify

package/docs/configuration/customization.mdx

@@ -25,6 +25,101 @@ export default defineComponents({
 Keys are the names you write in MDX (`<Callout>`, `<Pricing>`). Use the `.tsx`
 filename when you import React components.
 
+### Reference form
+
+Every override — in `mdx`, `layout`, or `islands` — accepts three forms:
+
+```ts components.ts
+import { defineComponents } from "blume";
+import Callout from "./components/Callout.astro";
+
+export default defineComponents({
+  mdx: {
+    Callout, // 1. an imported component
+    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
+    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
+  },
+});
+```
+
+The **descriptor** form adds a hydration mode so an interactive
+React/Vue/Svelte component ships its JavaScript and comes alive on the client.
+Without a `client` mode a framework component renders as static HTML — Blume
+prints a build warning when it spots one, since that's usually a mistake.
+
+| `client`    | Hydrates                                                         |
+| ----------- | ---------------------------------------------------------------- |
+| `"load"`    | Immediately on page load                                         |
+| `"idle"`    | When the main thread is idle                                     |
+| `"visible"` | When scrolled into view                                          |
+| `"media"`   | When a `media` query matches (add `media: "(min-width: 40rem)"`) |
+| `"only"`    | Client only, never server-rendered                               |
+
+For interactive components you use across many pages, the [`islands`
+group](/docs/content/islands#registering-islands-in-componentsts) is a shorthand
+for the descriptor form with `client: "visible"`.
+
+### Typing an override
+
+When you replace a built-in, import its prop type from `blume/components` so your
+component matches the contract — the types are derived from the components
+themselves, so they never drift:
+
+```tsx components/Callout.tsx
+import type { CalloutProps } from "blume/components";
+
+export default function Callout(props: CalloutProps) {
+  // …your own callout, same props as the built-in
+}
+```
+
+Prop types are exported for the content components (`CalloutProps`, `CardProps`,
+`TabsProps`, `StepsProps`, `BadgeProps`, and more).
+
+## Layout slots
+
+The `layout` map replaces a piece of Blume's chrome with your own component. Each
+override receives the same props as the built-in it replaces, so you can wrap the
+default or start from scratch.
+
+```ts components.ts
+import { defineComponents } from "blume";
+import Footer from "./components/Footer.astro";
+import Logo from "./components/Logo.astro";
+
+export default defineComponents({
+  layout: {
+    Logo, // brand mark + title in the header
+    Footer, // site-wide footer (no built-in — renders only when set)
+  },
+});
+```
+
+Wired slots:
+
+| Slot              | Replaces                                                 | Props                                                          |
+| ----------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
+| `Layout`          | The entire page shell (`RootLayout`)                     | Everything the built-in layout receives, plus the `layout` map |
+| `Header`          | The top navigation bar                                   | `site`, `logo`, `navigation`, `route`, `searchEnabled`, …      |
+| `Logo`            | The brand link (mark + title) in the header              | `site`, `logo`                                                 |
+| `Search`          | The header search trigger + modal                        | `navigation`, `strings`, `locale`, `askEnabled`                |
+| `Sidebar`         | The primary navigation tree                              | `items`, `currentRoute`                                        |
+| `MobileNav`       | The nav inside the mobile drawer (defaults to `Sidebar`) | `items`, `currentRoute`                                        |
+| `Breadcrumbs`     | The breadcrumb trail                                     | `crumbs`                                                       |
+| `TableOfContents` | The on-this-page outline                                 | `headings`, `title`, `variant`                                 |
+| `Pagination`      | The prev/next footer links                               | `prev`, `next`, `strings`                                      |
+| `PageHeader`      | An injection point above the article (no built-in)       | `page`, `headings`, `route`                                    |
+| `PageFooter`      | An injection point below the article (no built-in)       | `page`, `headings`, `route`                                    |
+| `Footer`          | A site-wide footer after the content grid (no built-in)  | `site`, `navigation`, `ui`                                     |
+
+`PageHeader`, `PageFooter`, and `Footer` have no built-in component — they render
+nothing until you set them, which makes them handy injection points for a
+promo banner, a "last updated" note, or a marketing footer.
+
+Layout slots accept the same [three reference forms](#reference-form) as MDX
+overrides, so a slot can be a path string or a hydrated descriptor
+(`{ component, client }`) when you want an interactive header or footer.
+
 ## Interactive islands
 
 For interactive UI (React, Vue, or Svelte), drop a component into an `islands/`
@@ -66,16 +161,19 @@ available:
 blume add
 ```
 
-Install a widget, or any built-in layout slot you want to customize — the
-header, sidebar, breadcrumbs, table of contents, or pagination:
+Install a layout slot (header, sidebar, breadcrumbs, table of contents,
+pagination, or feedback) or any content component (callout, card, tabs, steps,
+accordion, and more):
 
 ```bash
+blume add callout
 blume add pagination
 ```
 
-The copy imports the rest of the framework from `blume/*`, so it renders
-exactly like the built-in until you change it. `blume add` prints the
-`defineComponents` snippet to register it under the matching layout slot.
+The copy imports the rest of the framework from `blume/*`, so it renders exactly
+like the built-in until you change it. `blume add` prints the `defineComponents`
+snippet to register it — content components under `mdx`, layout pieces under
+`layout`.
 
 ## Eject
 

package/docs/configuration/index.mdx

@@ -20,7 +20,8 @@ export default defineConfig({
 
 ## A complete example
 
-Every option Blume reads, with its default:
+A broader example touching the most common options (see each feature's guide for
+the rest):
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";
@@ -238,7 +239,7 @@ the full reference.
 
 ```ts blume.config.ts lineNumbers
 seo: {
-  og: { enabled: false },
+  og: { enabled: true },
   rss: { enabled: true, types: ["blog", "changelog"] },
   sitemap: true,
   robots: true,
@@ -246,18 +247,31 @@ seo: {
 }
 ```
 
-| Option           | Default                 | Description                                   |
-| ---------------- | ----------------------- | --------------------------------------------- |
-| `og.enabled`     | `false`                 | Generate per-page Open Graph images.          |
-| `rss.enabled`    | `true`                  | Build feeds for blog and changelog content.   |
-| `rss.types`      | `["blog", "changelog"]` | Content types that each get a feed.           |
-| `rss.limit`      | `50`                    | Maximum items per feed.                       |
-| `sitemap`        | `true`                  | Generate sitemap.xml (needs deployment.site). |
-| `robots`         | `true`                  | Generate robots.txt with a Sitemap link.      |
-| `structuredData` | `true`                  | Emit schema.org JSON-LD in each page's head.  |
+| Option           | Default                 | Description                                             |
+| ---------------- | ----------------------- | ------------------------------------------------------- |
+| `og.enabled`     | auto                    | Per-page Open Graph images — on when a site URL is set. |
+| `rss.enabled`    | `true`                  | Build feeds for blog and changelog content.             |
+| `rss.types`      | `["blog", "changelog"]` | Content types that each get a feed.                     |
+| `rss.limit`      | `50`                    | Maximum items per feed.                                 |
+| `sitemap`        | `true`                  | Generate sitemap.xml (needs deployment.site).           |
+| `robots`         | `true`                  | Generate robots.txt with a Sitemap link.                |
+| `structuredData` | `true`                  | Emit schema.org JSON-LD in each page's head.            |
 
 These work best with an absolute [`deployment.site`](/docs/deployment) for full URLs.
 
+## Table of contents
+
+The on-this-page outline is on by default and lists `H2`–`H3` headings. Turn it
+off, or change the heading range, with `toc`:
+
+```ts blume.config.ts
+export default defineConfig({
+  toc: false, // hide it everywhere
+  // …or narrow the range:
+  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
+});
+```
+
 ## Feature options
 
 Each of these has its own guide. The config field is the entry point:

package/docs/configuration/search.mdx

@@ -17,7 +17,8 @@ so picking one backend never pulls in the others.
 ## Using search
 
 Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/`
-when you're not typing in a field. `Esc` closes it.
+when you're not typing in a field. `Esc` closes it, and `⌘J` (or `Ctrl J`)
+toggles the result preview pane.
 
 Queries match page **titles**, **descriptions**, and **body text**, with title
 matches ranked highest and descriptions above body.
@@ -29,6 +30,17 @@ to plain text — code blocks, images, and markup are stripped, so results stay
 relevant. The index is built from your source files, so it's identical in dev and
 production.
 
+## 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.
+
+```yaml
+search:
+  tags: [api, reference]
+```
+
 ## Providers
 
 The client-side providers are keyless and need no extra config. The hosted ones

package/docs/configuration/seo.mdx

@@ -114,6 +114,11 @@ OG rendering uses hex internally, so an `oklch` custom accent falls back to the
 default. Use a named accent (`blue`, `teal`, …) or a hex value for custom cards.
 :::
 
+`seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a
+custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a
+marketing home or landing page, and the way to give the home page alone a bespoke
+share image — pass the `ogImage` prop to `PageLayout`.
+
 ## RSS feeds
 
 Blume builds an RSS feed for each content type in `rss.types` — `blog` and

package/docs/configuration/theming.mdx

@@ -98,6 +98,55 @@ Each value is a Google Fonts slug from the curated set below:
 Need a font that isn't listed, or want to drop back to the system stack? Override
 the `--blume-font-*` tokens directly in [`theme.css`](#theme-css).
 
+### Dark-mode colors
+
+By default light and dark share one `accent`. Set `accentDark` for a different
+accent in dark mode, and `background` / `backgroundDark` to override the page
+background per mode:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  accent: "blue",
+  accentDark: "teal",        // a different accent in dark mode
+  background: "#ffffff",     // light-mode page background
+  backgroundDark: "#0a0a0a", // dark-mode page background
+}
+```
+
+Each takes a named preset or any CSS color, exactly like `accent`.
+
+### Action color
+
+`action` is a secondary accent for primary calls to action and the `action`
+Tailwind utilities (`bg-action`, `text-action`). It defaults to your `accent`:
+
+```ts blume.config.ts
+theme: {
+  action: "#ff0066",
+}
+```
+
+### Background decoration
+
+Add a subtle, theme-aware pattern behind your content with `backgroundDecoration`
+— `gradient`, `grid`, or `windows`:
+
+```ts blume.config.ts
+theme: {
+  backgroundDecoration: "grid",
+}
+```
+
+For a full background image, set `backgroundImage` (and `backgroundImageDark` for
+a dark variant) to a URL or a path under `public/`:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  backgroundImage: "/bg-light.svg",
+  backgroundImageDark: "/bg-dark.svg",
+}
+```
+
 ## theme.css
 
 Drop a `theme.css` in your project root to override any design token. It's the
@@ -128,6 +177,7 @@ dark mode.
 | `--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                              |
@@ -159,6 +209,7 @@ a utility, so your components track the theme automatically:
 | `--blume-border`            | `border-border`            |
 | `--blume-accent`            | `bg-accent`, `text-accent` |
 | `--blume-accent-foreground` | `text-accent-foreground`   |
+| `--blume-action`            | `bg-action`, `text-action` |
 | `--blume-radius`            | `rounded-blume`            |
 | `--blume-font-display`      | `font-display`             |
 | `--blume-font-body`         | `font-sans`                |

package/docs/content/components.mdx

@@ -133,6 +133,24 @@ A negative or breaking state, such as a deprecation.
 <Badge variant="danger">Deprecated</Badge>
 ```
 
+## Icon
+
+Render an icon from Blume's built-in set by name — the same set the `icon` props
+on cards, tiles, tabs, and sidebar entries draw from. Names are lowercase and
+kebab-cased (`rocket`, `book-open`, `chevron-right`).
+
+<Icon icon="rocket" size={20} />
+
+```astro
+<Icon icon="rocket" size={20} />
+```
+
+`icon` is the icon name; `size` sets the pixel size (default `16`) and `color`
+tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string,
+an image URL, or a local image path in place of a name to render your own art,
+and add a `label` to expose it to assistive tech — without one, the icon is
+decorative.
+
 ## File tree
 
 Illustrate a project or folder layout. Wrap a normal Markdown list and Blume

package/docs/content/islands.mdx

@@ -36,6 +36,35 @@ pages (a styled callout, a pricing table), use an [MDX
 override](/docs/configuration/customization) instead — it ships no JavaScript.
 :::
 
+## 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"`).
+
+```ts components.ts
+import { defineComponents } from "blume";
+import Counter from "./widgets/Counter.tsx";
+
+export default defineComponents({
+  islands: {
+    Counter, // <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:
+
+```ts components.ts
+export default defineComponents({
+  islands: {
+    Chart: { component: "./widgets/Chart.tsx", client: "only" },
+  },
+});
+```
+
 ## Hydration
 
 By default an island uses `client:visible`: it hydrates when the reader scrolls
@@ -92,3 +121,47 @@ and children (`<Counter>label</Counter>`) arrive as the default slot.
 Islands hydrate on the client, so anything you pass as a prop must be
 serializable — strings, numbers, plain objects, not functions.
 :::
+
+## Hooks
+
+Islands hydrate on their own, so there's no React context to thread project data
+through. Instead, `blume/hooks` reads a small snapshot the layout serializes into
+the page — no props to drill:
+
+```tsx islands/PageInfo.tsx lineNumbers
+import { useBlume, usePage } from "blume/hooks";
+
+export default function PageInfo() {
+  const blume = useBlume();
+  const page = usePage();
+  if (!(blume && page)) {
+    return null;
+  }
+  return (
+    <p>
+      You're reading <strong>{page.title}</strong> on {blume.config.title}.
+    </p>
+  );
+}
+```
+
+| Hook          | Returns                                                               |
+| ------------- | --------------------------------------------------------------------- |
+| `useBlume()`  | `{ config, navigation }` for the site, or `null` before mount         |
+| `usePage()`   | `{ route, title }` for the current page, or `null` before mount       |
+| `useSearch()` | `{ search, results, loading }` — query the configured search provider |
+| `useAskAI()`  | `{ ask, messages, loading, reset }` — stream from the Ask AI endpoint |
+
+`useBlume()` and `usePage()` return `null` until the island mounts (so server and
+client render the same first frame) — guard for it. The snapshot is emitted only
+on pages that ship React, so a fully static site pays nothing.
+
+On [custom pages](/docs/advanced/custom-pages) built with `PageLayout`, pass
+`clientData` so islands there can read it:
+
+```astro
+<PageLayout
+  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
+  {/* …other props… */}
+/>
+```

package/docs/content/navigation.mdx

@@ -113,6 +113,31 @@ your loose top-level pages while the sectioned content stays behind its tab,
 mirroring Fumadocs' root folders. If a route has no pages of its own to show
 this way, the full tree is shown instead, so the sidebar is never left blank.
 
+## Selectors
+
+For switching between whole partitions of a site — a product, a version, or any
+grouped set of destinations — add a `selector`. Each renders as a dropdown in the
+header, showing the option whose `path` matches the current route:
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  selectors: [
+    {
+      kind: "version",
+      label: "Version",
+      items: [
+        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
+        { label: "v1", path: "/v1" },
+      ],
+    },
+  ],
+}
+```
+
+Each item takes a `label`, a `path`, and optional `icon`, `description`, and
+`tag`. `kind` (`dropdown`, `product`, `version`, or `language`) is a hint for how
+the selector is used; all render the same dropdown.
+
 ## Explicit sidebar
 
 For full control, define `navigation.sidebar` in config. When it's set, Blume