blume 0.2.0 → 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/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

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

@@ -259,6 +259,19 @@ seo: {
 
 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/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/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

package/docs/index.mdx

@@ -21,18 +21,9 @@ library — with no app boilerplate to write or maintain.
 
 ## Why Blume exists
 
-Blume is the answer to a problem I kept trying to solve at Vercel: documentation
-should be _fast_, _AI-ready_, and require _zero configuration_ — down to not
-needing a starter template at all.
-
-Most docs tools hand you a project to own before you've written a word: an app to
-scaffold, a framework to learn, a template to keep in sync with upstream. Blume
-flips that around. The framework _is_ the template, so the only thing you ever
-touch is your content. When you outgrow the defaults, you add configuration one
-file at a time — and you can `blume eject` to a plain Astro project the day you
-want full control.
-
-— Hayden Bleasel
+Docs should be fast, AI-ready and require zero configuration — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
+
+Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start replacing the built-in components, modifying the single configuration file or even ejecting if you want the Astro site directly.
 
 ## What makes Blume different
 

package/docs/reference/cli.mdx

@@ -19,21 +19,63 @@ blume <command> [options]
 | `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
 | `blume sync`           | Re-fetch remote content sources and regenerate.        |
 | `blume eject`          | Promote the runtime into a standalone Astro app.       |
+| `blume check`          | Type-check the site with `astro check`.                |
 | `blume doctor`         | Diagnose config and content problems.                  |
 | `blume validate`       | Validate links across your content.                    |
 
 ## Common flags
 
 - `blume init --content-dir <dir> --yes` — set the content folder (default `docs`) and skip prompts.
+- `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
+- `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
+- `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
 - `blume dev --host --port <n> --open`
+- `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
+- `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
 - `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
 - `blume build --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
+- `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
+- `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
 - `blume preview --host --port <n>` — bind the preview server.
 - `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
 - `blume add <item> --force` — overwrite files that already exist.
+- `blume check --preview` — include drafts and unpublished CMS content when checking.
+- `blume check --strict` — fail on content diagnostics as well as type errors.
 - `blume eject --yes` — skip the confirmation prompt.
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
+- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on
+  stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI
+  and editor integrations.
+
+## Type-checking
+
+`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)
+over your project. It regenerates the `.blume` runtime, syncs Astro's content
+types, then reports any TypeScript errors — in your `blume.config.ts`, in custom
+`.astro` pages, and in the components they import. It exits non-zero when there
+are errors, so it works as a `typecheck` step in CI:
+
+```json title="package.json"
+{
+  "scripts": {
+    "typecheck": "blume check"
+  }
+}
+```
+
+Add a `tsconfig.json` extending Astro's config to your project root so authored
+pages resolve `blume/*` imports and virtual modules like `blume:data`:
+
+```json title="tsconfig.json"
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
+}
+```
+
+Without a project `tsconfig.json`, only the generated runtime is checked.
 
 ## Validating links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -43,6 +43,7 @@
       "default": "./src/core/schema.ts"
     },
     "./runtime": "./src/runtime/index.ts",
+    "./hooks": "./src/components/islands/hooks.ts",
     "./astro": "./src/astro/index.ts",
     "./og": "./src/og/index.ts",
     "./markdown": "./src/markdown/index.ts",
@@ -62,6 +63,7 @@
     "typecheck": "tsgo --noEmit && tsgo -p test/tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@astrojs/check": "^0.9.0",
     "@astrojs/markdown-satteri": "^0.3.2",
     "@astrojs/mdx": "^7.0.0",
     "@astrojs/node": "^11.0.0",