blume 0.2.0 → 0.4.0

package/docs/content/islands.mdx

@@ -3,15 +3,11 @@ title: Islands
 description: Drop an interactive component into islands/ and use it in any MDX page — hydrated automatically, no per-page import.
 ---
 
-Blume renders your docs as static HTML with **zero JavaScript** by default. When
-you need something interactive — a live demo, a chart, a playground — you add an
-**island**: a framework component that ships JS only for itself, only on the
-pages that use it.
+Blume renders your docs as static HTML with **zero JavaScript** by default. When you need something interactive — a live demo, a chart, a playground — you add an **island**: a framework component that ships JS only for itself, only on the pages that use it.
 
 ## The `islands/` convention
 
-Drop a component into an `islands/` folder at your project root. Its filename
-becomes a component you can use in **any** `.mdx` page, with no import:
+Drop a component into an `islands/` folder at your project root. Its filename becomes a component you can use in **any** `.mdx` page, with no import:
 
 ```tsx islands/Counter.tsx lineNumbers
 import { useState } from "react";
@@ -26,21 +22,38 @@ export default function Counter() {
 Here's a live counter: <Counter />
 ```
 
-The filename is the component name, so it **must be PascalCase**
-(`Counter.tsx` → `<Counter />`). Lowercase filenames and two islands that
-resolve to the same name are skipped with a build warning.
+The filename is the component name, so it **must be a PascalCase identifier** — letters, digits, and underscores only (`Counter.tsx` → `<Counter />`). Lowercase filenames, names with dashes/dots/spaces (like `Time-Picker.tsx`), and two islands that resolve to the same name are skipped with a build warning.
 
-:::note
-Islands are for **interactive** UI. For a static component you reuse across
-pages (a styled callout, a pricing table), use an [MDX
-override](/docs/configuration/customization) instead — it ships no JavaScript.
-:::
+:::note Islands are for **interactive** UI. For a static component you reuse across 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
-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:
+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:
 
 ```tsx islands/Chart.tsx lineNumbers
 // Skip server rendering entirely — for components that touch the DOM/window.
@@ -51,20 +64,18 @@ export default function Chart() {
 }
 ```
 
-| `client` value          | Hydrates                           | Use it for                                                |
-| ----------------------- | ---------------------------------- | --------------------------------------------------------- |
-| `"visible"` _(default)_ | When scrolled into view            | Most islands                                              |
-| `"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) |
+| `client` value | Hydrates | Use it for |
+| --- | --- | --- |
+| `"visible"` _(default)_ | When scrolled into view | Most islands |
+| `"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) |
 
 ## Frameworks
 
-**React works out of the box** — Blume turns it on automatically the moment your
-project contains a `.tsx`/`.jsx` island.
+**React works out of the box** — Blume turns it on automatically the moment your project contains a `.tsx`/`.jsx` island.
 
-**Vue and Svelte** are supported too; install the matching Astro integration and
-Blume wires up the renderer when it sees a `.vue` or `.svelte` island:
+**Vue and Svelte** are supported too; install the matching Astro integration and Blume wires up the renderer when it sees a `.vue` or `.svelte` island:
 
 ```bash
 # Vue
@@ -85,10 +96,45 @@ const on = ref(false);
 </template>
 ```
 
-Props you pass in MDX (`<Counter start={5} />`) are forwarded to the component,
-and children (`<Counter>label</Counter>`) arrive as the default slot.
+Props you pass in MDX (`<Counter start={5} />`) are forwarded to the component, and children (`<Counter>label</Counter>`) arrive as the default slot.
+
+:::tip Islands hydrate on the client, so anything you pass as a prop must be serializable — strings, numbers, plain objects, not functions. :::
+
+## Hooks
 
-:::tip
-Islands hydrate on the client, so anything you pass as a prop must be
-serializable — strings, numbers, plain objects, not functions.
-:::
+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/meta.mdx

@@ -3,16 +3,11 @@ title: Folder meta
 description: Configure a sidebar group — its title, icon, order, display mode, and page order — with a meta.ts file.
 ---
 
-Every folder in your content tree becomes a sidebar group. Drop a `meta.ts`
-beside its pages to control how that group looks and how its children are
-ordered. It's entirely optional: without one, the group's label is the humanized
-folder name and its pages sort by [index, numeric prefix, then
-alphabetically](/docs/content/navigation#ordering).
+Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).
 
 ## Defining meta
 
-Export a `defineMeta` object for a fully typed config. Place the file at the root
-of the folder it configures — `guides/meta.ts` configures the **Guides** group:
+Export a `defineMeta` object for a fully typed config. Place the file at the root of the folder it configures — `guides/meta.ts` configures the **Guides** group:
 
 ```ts meta.ts lineNumbers
 import { defineMeta } from "blume";
@@ -31,45 +26,32 @@ Every field is optional — set only what you want to override.
 
 ## Fields
 
-| Field       | Type                          | Description                                                                            |
-| ----------- | ----------------------------- | -------------------------------------------------------------------------------------- |
-| `title`     | `string`                      | The group's label. Defaults to the humanized folder name.                              |
-| `icon`      | `string`                      | Icon shown next to the label.                                                          |
-| `order`     | `number`                      | Position among sibling groups and pages. Lower numbers sort first.                     |
-| `display`   | `"flat" \| "group" \| "page"` | How the group renders in the sidebar. Defaults to `flat`. See [below](#display-modes). |
-| `collapsed` | `boolean`                     | For `display: "group"`, whether the group starts collapsed.                            |
-| `pages`     | `string[]`                    | Explicit order for the group's children, by slug.                                      |
+| Field | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The group's label. Defaults to the humanized folder name. |
+| `icon` | `string` | Icon shown next to the label. |
+| `order` | `number` | Position among sibling groups and pages. Lower numbers sort first. |
+| `display` | `"flat" \| "group" \| "page"` | How the group renders in the sidebar. Defaults to `flat`. See [below](#display-modes). |
+| `collapsed` | `boolean` | For `display: "group"`, whether the group starts collapsed. |
+| `pages` | `string[]` | Explicit order for the group's children, by slug. |
 
-The `pages` array lists children by slug — the folder or file name with its
-numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is
-`"quickstart"`). Children you leave out still appear, after the listed ones.
+The `pages` array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is `"quickstart"`). Children you leave out still appear, after the listed ones.
 
 ## Display modes
 
 `display` controls how a group and its items appear in the sidebar:
 
 - **`flat`** (default) — a non-collapsible header with its pages listed beneath.
-- **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed`
-  to set the initial state; a group containing the current page always starts
-  open.
-- **`page`** — a single row that, when clicked, slides the sidebar into a
-  sub-panel showing only that group's items, with a back arrow at the top. The
-  panel is route-aware, so landing directly on a page inside the group opens
-  straight to it.
-
-:::tip
-`page` mode keeps deep sections tidy — reach for it when a group has many
-children and you'd rather drill into it than scroll past it.
-:::
-
-`display` works the same on a group in an [explicit
-sidebar](/docs/content/navigation#explicit-sidebar) config.
+- **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed` to set the initial state; a group containing the current page always starts open.
+- **`page`** — a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
+
+:::tip `page` mode keeps deep sections tidy — reach for it when a group has many children and you'd rather drill into it than scroll past it. :::
+
+`display` works the same on a group in an [explicit sidebar](/docs/content/navigation#explicit-sidebar) config.
 
 ## Computed meta
 
-Because `meta.ts` is a real module, you can compute the meta — pass a function
-(sync or `async`) instead of an object to build it at scan time. Handy for
-ordering pages from an external source:
+Because `meta.ts` is a real module, you can compute the meta — pass a function (sync or `async`) instead of an object to build it at scan time. Handy for ordering pages from an external source:
 
 ```ts meta.ts
 import { defineMeta } from "blume";
@@ -82,30 +64,21 @@ export default defineMeta(async () => ({
 
 ## Ordering within a group
 
-The `pages` array sets the order of a group's children. Anything it omits falls
-back to each page's frontmatter `sidebar.order`, then the file system (an `index`
-page first, then numeric prefixes, then alphabetical). For the full sidebar
-precedence — including an explicit config sidebar — see [Navigation ›
-Ordering](/docs/content/navigation#ordering).
+The `pages` array sets the order of a group's children. Anything it omits falls back to each page's frontmatter `sidebar.order`, then the file system (an `index` page first, then numeric prefixes, then alphabetical). For the full sidebar precedence — including an explicit config sidebar — see [Navigation › Ordering](/docs/content/navigation#ordering).
 
-To group pages _without_ adding a URL segment, you don't need a `meta.ts` at all:
-use a parenthesized folder name — see [Pages › Group
-folders](/docs/content#group-folders).
+To group pages _without_ adding a URL segment, you don't need a `meta.ts` at all: use a parenthesized folder name — see [Pages › Group folders](/docs/content#group-folders).
 
 ## Internationalization
 
-Under [i18n](/docs/content/i18n), folder meta resolves per locale: put a
-`meta.ts` under `fr/guides/` to order the French group independently.
+Under [i18n](/docs/content/i18n), folder meta resolves per locale: put a `meta.ts` under `fr/guides/` to order the French group independently.
 
-For folder meta that's identical in every language, add a `$` marker so one file
-serves all locales without duplication:
+For folder meta that's identical in every language, add a `$` marker so one file serves all locales without duplication:
 
 ```txt
 docs/guides/meta.$.ts   (folder meta applied to every locale)
 ```
 
-A locale-specific `meta.ts` still overrides the shared `meta.$.ts` for that
-language.
+A locale-specific `meta.ts` still overrides the shared `meta.$.ts` for that language.
 
 ## Where to next
 

package/docs/content/navigation.mdx

@@ -3,27 +3,21 @@ title: Navigation
 description: Build the sidebar from your files, then refine it with frontmatter, folder meta, or config.
 ---
 
-Blume builds your sidebar from the file system, then lets you refine it as much —
-or as little — as you want: page by page, folder by folder, or with one explicit
-config. Breadcrumbs, previous/next links, and the on-page outline all follow from
-the same model, with nothing to wire up.
+Blume builds your sidebar from the file system, then lets you refine it as much — or as little — as you want: page by page, folder by folder, or with one explicit config. Breadcrumbs, previous/next links, and the on-page outline all follow from the same model, with nothing to wire up.
 
 ## The generated sidebar
 
 By default the sidebar mirrors your content tree:
 
 - folders become **groups**, files become **pages**
-- a page's label is its frontmatter `title`; a group's label is the humanized
-  folder name
-- items sort by [numeric prefix](/docs/content), then alphabetically, and a folder's
-  `index` page comes first
+- a page's label is its frontmatter `title`; a group's label is the humanized folder name
+- items sort by [numeric prefix](/docs/content), then alphabetically, and a folder's `index` page comes first
 
 That's enough for many sites — everything below is opt-in.
 
 ## Page label, icon, and badge
 
-Tune how a single page appears in the sidebar from its frontmatter, under
-`sidebar`:
+Tune how a single page appears in the sidebar from its frontmatter, under `sidebar`:
 
 ```yaml lineNumbers
 sidebar:
@@ -37,9 +31,7 @@ See [Frontmatter](/docs/reference/frontmatter) for the full page schema.
 
 ## Folder groups
 
-Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta)
-beside its pages to set the group's title, icon, order, [display
-mode](/docs/content/meta#display-modes), and the order of its children:
+Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, [display mode](/docs/content/meta#display-modes), and the order of its children:
 
 ```ts meta.ts
 import { defineMeta } from "blume";
@@ -51,11 +43,9 @@ export default defineMeta({
 });
 ```
 
-See [Folder meta](/docs/content/meta) for every field, the three display modes,
-and computing meta at scan time.
+See [Folder meta](/docs/content/meta) for every field, the three display modes, and computing meta at scan time.
 
-To group pages _without_ adding a URL segment, use a parenthesized folder name —
-see [Pages](/docs/content#group-folders).
+To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
 ## Ordering
 
@@ -76,8 +66,7 @@ When the sidebar is generated, order is resolved highest priority first:
 
 ## Hidden pages
 
-Hide a page from the sidebar — and from previous/next pagination — while keeping
-it built and reachable by its URL:
+Hide a page from the sidebar — and from previous/next pagination — while keeping it built and reachable by its URL:
 
 ```yaml
 sidebar:
@@ -86,9 +75,7 @@ sidebar:
 
 ## Tabs
 
-Render top-level sections as tabs in the header, useful for splitting a large
-site into distinct areas — say adapters, an API, and AI guides. A tab is
-highlighted when the current route falls under its `path`:
+Render top-level sections as tabs in the header, useful for splitting a large site into distinct areas — say adapters, an API, and AI guides. A tab is highlighted when the current route falls under its `path`:
 
 ```ts blume.config.ts lineNumbers
 navigation: {
@@ -100,23 +87,34 @@ navigation: {
 }
 ```
 
-Tabs also **scope the sidebar**: when the current route falls under a tab's
-`path`, the sidebar shows only that section's pages — so `/adapters/*` lists the
-adapters and nothing else. The folder at a tab's `path` becomes the section, so
-this needs no extra config beyond the tabs themselves; structure your content
-into a folder per tab and point each tab at it.
+Tabs also **scope the sidebar**: when the current route falls under a tab's `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the adapters and nothing else. The folder at a tab's `path` becomes the section, so this needs no extra config beyond the tabs themselves; structure your content into a folder per tab and point each tab at it.
 
-On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the
-pages that _don't_ belong to a tab — each tab's folder is hidden from it, since
-that section already has its own tab in the header. So a root landing page lists
-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.
+On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the pages that _don't_ belong to a tab — each tab's folder is hidden from it, since that section already has its own tab in the header. So a root landing page lists 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
-uses it verbatim and skips file-system generation:
+For full control, define `navigation.sidebar` in config. When it's set, Blume uses it verbatim and skips file-system generation:
 
 ```ts blume.config.ts lineNumbers
 navigation: {
@@ -132,15 +130,11 @@ navigation: {
 }
 ```
 
-Each item is a page route (a string), a group (`label` + `items`), or a link
-(`label` + `href`). Groups can nest, take a [`display`
-mode](/docs/content/meta#display-modes), and start `collapsed`.
+Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, take a [`display` mode](/docs/content/meta#display-modes), and start `collapsed`.
 
 ## Repository link
 
-When you set [`github`](/docs/configuration) in your config, Blume shows a GitHub
-icon in the header — beside the theme toggle — that links to your repository. It's
-on by default; hide it with `navigation.repo`:
+When you set [`github`](/docs/configuration) in your config, Blume shows a GitHub icon in the header — beside the theme toggle — that links to your repository. It's on by default; hide it with `navigation.repo`:
 
 ```ts blume.config.ts lineNumbers
 navigation: {
@@ -148,35 +142,27 @@ navigation: {
 }
 ```
 
-The link only appears when `github` is configured, so projects without a repo are
-unaffected either way.
+The link only appears when `github` is configured, so projects without a repo are unaffected either way.
 
 ## Breadcrumbs and pagination
 
 These come for free from the sidebar tree — no configuration:
 
 - **Breadcrumbs** show the current page's parent group above the title.
-- **Previous and next** links at the foot of each page follow sidebar order,
-  skipping hidden pages.
+- **Previous and next** links at the foot of each page follow sidebar order, skipping hidden pages.
 
 ## On this page
 
-A right-rail outline is generated automatically from each page's `##` and `###`
-headings, so long pages stay scannable. On narrower screens, where the right rail
-is hidden, it collapses into an “On this page” dropdown above the content.
+A right-rail outline is generated automatically from each page's `##` and `###` headings, so long pages stay scannable. On narrower screens, where the right rail is hidden, it collapses into an “On this page” dropdown above the content.
 
 ## Page actions
 
 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 this page 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`).
+- **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).
+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).
 
-With [`export`](/docs/configuration/export) on, an **Export** action also lets
-readers download the page as a PDF or EPUB.
+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

@@ -3,16 +3,11 @@ title: Content sources
 description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
 ---
 
-By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let
-you pull pages from somewhere else — a remote repository, a CMS, or any custom
-backend — and mix several sources into a single site. Sources are read at
-build time; Blume stays static-first.
+By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.
 
 ## The default
 
-With no configuration, Blume scans your content root (`docs` by default) as one
-implicit filesystem source. The top-level `content.root`/`include`/`exclude`
-options still work exactly as before — nothing to change.
+With no configuration, Blume scans your content root (`docs` by default) as one implicit filesystem source. The top-level `content.root`/`include`/`exclude` options still work exactly as before — nothing to change.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -24,10 +19,7 @@ export default defineConfig({
 
 ## Multiple sources
 
-Add a `content.sources` array to compose sources. Each entry is namespaced by an
-optional `prefix`, so its routes nest under `/<prefix>/…`. When `sources` is
-present it replaces the implicit default, so include a `filesystem` entry for
-your local docs.
+Add a `content.sources` array to compose sources. Each entry is namespaced by an optional `prefix`, so its routes nest under `/<prefix>/…`. When `sources` is present it replaces the implicit default, so include a `filesystem` entry for your local docs.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -49,14 +41,11 @@ export default defineConfig({
 });
 ```
 
-If two sources resolve to the same route, Blume reports a `BLUME_DUPLICATE_ROUTE`
-build error — give each source a distinct `prefix`.
+If two sources resolve to the same route, Blume reports a `BLUME_DUPLICATE_ROUTE` build error — give each source a distinct `prefix`.
 
 ## Remote MDX
 
-The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate
-files either from a GitHub repo subtree (`github`) or explicitly against a raw
-base URL (`url` + `files`):
+The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate files either from a GitHub repo subtree (`github`) or explicitly against a raw base URL (`url` + `files`):
 
 ```ts blume.config.ts
 {
@@ -67,34 +56,19 @@ base URL (`url` + `files`):
 }
 ```
 
-A private repo's token is read from the `GITHUB_TOKEN` environment variable — it
-is never inlined into your config or generated output.
+A private repo's token is read from the `GITHUB_TOKEN` environment variable — it is never inlined into your config or generated output.
 
-Remote pages are rendered with full MDX-plus-component fidelity: their bodies are
-materialized into a hidden staging directory and rendered through Astro
-alongside your local docs, so callouts, tabs, and every other Blume component
-keep working.
+Remote pages are rendered with full MDX-plus-component fidelity: their bodies are materialized into a hidden staging directory and rendered through Astro alongside your local docs, so callouts, tabs, and every other Blume component keep working.
 
 ### Caching and offline builds
 
-Each remote source keeps a snapshot under `.blume/cache/<source>/`. If a fetch
-fails — a network blip or a CMS outage — Blume serves the last-known-good
-snapshot with a warning rather than failing the build. The cache lives inside
-`.blume/` and is regenerated, never committed.
+Each remote source keeps a snapshot under `.blume/cache/<source>/`. If a fetch fails — a network blip or a CMS outage — Blume serves the last-known-good snapshot with a warning rather than failing the build. The cache lives inside `.blume/` and is regenerated, never committed.
 
-In dev, remote content is fetched once and frozen for the session; restart the
-dev server to refresh it. Local filesystem sources hot-reload as usual. To poll
-a remote source for changes instead, set `pollInterval` (seconds) on it — the
-dev server re-fetches on that interval and reloads only when the content
-actually changes. Leave it unset to avoid hitting the API while you work.
+In dev, remote content is fetched once and frozen for the session; restart the dev server to refresh it. Local filesystem sources hot-reload as usual. To poll a remote source for changes instead, set `pollInterval` (seconds) on it — the dev server re-fetches on that interval and reloads only when the content actually changes. Leave it unset to avoid hitting the API while you work.
 
 ## GitHub Releases
 
-The built-in `github-releases` source turns a repo's releases into a changelog:
-each release becomes a `type: changelog` entry, so your release notes _are_ your
-changelog — nothing to write twice. Combined with the generated
-[changelog timeline](/docs/advanced/changelog), publishing a GitHub release
-ships a changelog entry.
+The built-in `github-releases` source turns a repo's releases into a changelog: each release becomes a `type: changelog` entry, so your release notes _are_ your changelog — nothing to write twice. Combined with the generated [changelog timeline](/docs/advanced/changelog), publishing a GitHub release ships a changelog entry.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -117,25 +91,13 @@ export default defineConfig({
 });
 ```
 
-Each release maps to the changelog fields automatically: its name (or tag)
-becomes the title, its published date drives the timeline order, the tag becomes
-`changelog.version`, and prereleases are tagged `Prerelease` (others `Release`).
-The notes render as the entry body. Give the source a `prefix` so its release
-pages nest under a route like `/changelog/v1-2-0`.
+Each release maps to the changelog fields automatically: its name (or tag) becomes the title, its published date drives the timeline order, the tag becomes `changelog.version`, and prereleases are tagged `Prerelease` (others `Release`). The notes render as the entry body. Give the source a `prefix` so its release pages nest under a route like `/changelog/v1-2-0`.
 
-A private repo authenticates with the `GITHUB_TOKEN` environment variable — the
-same token the other GitHub features use, never inlined into your config. Like
-every remote source it's cached under `.blume/cache/<source>/` and served
-offline if the API is unreachable. Because a changelog is supplementary, a fetch
-failure with no cache (say a CI build without a token) degrades to an empty
-changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in
-your CI and deploy environments to populate it.
+A private repo authenticates with the `GITHUB_TOKEN` environment variable — the same token the other GitHub features use, never inlined into your config. Like every remote source it's cached under `.blume/cache/<source>/` and served offline if the API is unreachable. Because a changelog is supplementary, a fetch failure with no cache (say a CI build without a token) degrades to an empty changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in your CI and deploy environments to populate it.
 
 ## Sanity
 
-The built-in `sanity` source runs a GROQ query and maps each document's fields
-to frontmatter and its Portable Text body to Markdown. The `@sanity/client`
-package is an optional peer dependency — install it only if you use this source.
+The built-in `sanity` source runs a GROQ query and maps each document's fields to frontmatter and its Portable Text body to Markdown. The `@sanity/client` package is an optional peer dependency — install it only if you use this source.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -158,17 +120,11 @@ export default defineConfig({
 });
 ```
 
-A read token for a private dataset comes from the `SANITY_TOKEN` environment
-variable. Custom Portable Text block types map to Blume components through the
-adapter's `serializers` option, available when you construct `sanitySource`
-directly via a [custom source](#custom-sources).
+A read token for a private dataset comes from the `SANITY_TOKEN` environment variable. Custom Portable Text block types map to Blume components through the adapter's `serializers` option, available when you construct `sanitySource` directly via a [custom source](#custom-sources).
 
 ## Notion
 
-The built-in `notion` source turns a Notion database into a collection: each row
-becomes a page, its properties become frontmatter, and its block tree becomes
-MDX. Callouts, toggles, columns, and code blocks map to the matching Blume
-components. `@notionhq/client` is an optional peer dependency.
+The built-in `notion` source turns a Notion database into a collection: each row becomes a page, its properties become frontmatter, and its block tree becomes MDX. Callouts, toggles, columns, and code blocks map to the matching Blume components. `@notionhq/client` is an optional peer dependency.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -190,29 +146,14 @@ export default defineConfig({
 });
 ```
 
-The integration token comes from the `NOTION_TOKEN` environment variable (share
-the database with your integration). By default every page is imported; set
-`publishedValue` to make the `Status` property a publish gate — any other value
-then maps to `draft: true`, which production builds drop. **Notion image URLs
-are signed and expire**, so the adapter downloads them at build time into the
-site's assets and rewrites the references — a CMS image never rots a static
-build.
+The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build.
 
 ## Preview and sync
 
 Two flags control how remote content is fetched and what's included:
 
-- **`--preview`** on `blume dev` or `blume build` renders drafts and pulls
-  unpublished CMS content — Sanity switches to its `previewDrafts` perspective,
-  and Notion stops filtering by `Status`. Production builds without the flag
-  exclude drafts as usual, so a preview build is a safe way to review
-  unpublished work before it ships.
-- **`blume sync`** re-fetches every remote source and regenerates the runtime.
-  Dev is cache-first — a remote source is fetched once and served from
-  `.blume/cache` on restart (fast and offline-tolerant), so `blume sync` is how
-  you pull the latest CMS content without restarting the dev server (a running
-  server hot-reloads). Add `--force` to drop the cache first, or set
-  `pollInterval` on a source to refresh automatically.
+- **`--preview`** on `blume dev` or `blume build` renders drafts and pulls unpublished CMS content — Sanity switches to its `previewDrafts` perspective, and Notion stops filtering by `Status`. Production builds without the flag exclude drafts as usual, so a preview build is a safe way to review unpublished work before it ships.
+- **`blume sync`** re-fetches every remote source and regenerates the runtime. Dev is cache-first — a remote source is fetched once and served from `.blume/cache` on restart (fast and offline-tolerant), so `blume sync` is how you pull the latest CMS content without restarting the dev server (a running server hot-reloads). Add `--force` to drop the cache first, or set `pollInterval` on a source to refresh automatically.
 
 ```sh
 blume dev --preview      # author workflow: see drafts live
@@ -223,9 +164,7 @@ blume sync --force        # ...ignoring any cached snapshot
 
 ## Custom sources
 
-Any object implementing the `ContentSource` interface can be passed directly,
-which is how an adapter with custom serializers — or any backend not built in —
-plugs in without its SDK touching the core install:
+Any object implementing the `ContentSource` interface can be passed directly, which is how an adapter with custom serializers — or any backend not built in — plugs in without its SDK touching the core install:
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -254,6 +193,4 @@ export default defineConfig({
 });
 ```
 
-A source normalizes its native shape (Portable Text, Notion blocks, remote HTML)
-to Markdown/MDX text, so the same components and markdown features apply no
-matter where a page comes from.
+A source normalizes its native shape (Portable Text, Notion blocks, remote HTML) to Markdown/MDX text, so the same components and markdown features apply no matter where a page comes from.