blume 1.7.3 → 2.0.0

package/docs/03-upgrading.mdx

@@ -0,0 +1,351 @@
+---
+title: Upgrade to Blume 2
+description: Move a Blume 1 site to Blume 2 with one command, then use this guide for each config change — or hand the whole upgrade to Claude Code or Codex.
+sidebar:
+  label: Upgrade to Blume 2
+  order: 2.5
+---
+
+Blume 2 changes configuration, not content: your Markdown and MDX pages need no edits, unless one sets the removed `search.boost` frontmatter field (see [Frontmatter](#frontmatter)). Settings that used to be a named string or a keyed block — the search provider, the deployment target, content sources, API references, analytics, and the Ask AI backend — are now **adapters** you import from a `blume/*` subpath and call. The machine-readable settings move from `ai` to a new `agents` key, and `components.ts` overrides are checked before the build. A zero-config site, or one that sets none of these, only needs the version bump.
+
+## Upgrade with one command
+
+Run the upgrade from your project, the folder with `blume.config.ts`:
+
+```package-install
+npx blume@latest upgrade
+```
+
+It bumps `blume` in your `package.json` to 2, installs it with the package manager your project uses, then checks your config and `components.ts` against Blume 2. Every change that's still needed is listed with its file, line, and replacement — including `package.json` scripts that still pass the removed `blume build` flags — and the command exits non-zero until none are left. Run from a folder with neither a config nor a `blume` dependency, it stops with an error instead. Run it through `npx blume@latest` rather than `blume`: the command ships in Blume 2, so a project still on 1 doesn't have it yet. On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx`, since pnpm 12 won't run esbuild's install script unapproved.
+
+To hand the changes to a coding agent instead, add `--claude` or `--codex`:
+
+```package-install
+npx blume@latest upgrade --claude
+```
+
+The agent opens interactively with the findings and this guide, applies each change, and runs `blume doctor` and `blume build` until both pass, so you review every edit through its own permission flow. Pass `--no-install` to bump `package.json` without installing.
+
+The sections below cover each change, for upgrading by hand or checking what the agent did.
+
+## Search
+
+`search` takes an adapter from `blume/search` instead of a `provider` string with a credentials block. The default local search needs no change.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  search: {
+    provider: "algolia",
+    algolia: { appId: "APP_ID", indexName: "docs", searchApiKey: "SEARCH_KEY" },
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { algolia } from "blume/search";
+
+export default defineConfig({
+  search: algolia({ appId: "APP_ID", indexName: "docs", apiKey: "SEARCH_KEY" }),
+});
+```
+
+</CodeGroup>
+
+- Orama Cloud, Typesense, and Mixedbread map the same way to `oramaCloud()`, `typesense()`, and `mixedbread()`. The search-only key is `apiKey` in every adapter that takes one; `mixedbread()` takes `storeId` rather than a key, since its queries run on the docs server; any other option it's given is forwarded to the store search call, where `top_k` defaults to 8. Admin keys stay in their env vars (`ALGOLIA_ADMIN_API_KEY`, `ORAMA_PRIVATE_API_KEY`, `TYPESENSE_ADMIN_API_KEY`, `MIXEDBREAD_API_KEY`).
+- `provider: "pagefind"` becomes `pagefind()`, and `provider: "none"` becomes `search: false`.
+- To keep `popular` links or `indexing` options, wrap the adapter: `search: { provider: algolia({ … }), popular: […] }`.
+
+## Deployment
+
+`deployment` takes a host adapter from `blume/deploy` instead of `adapter` and `output` fields. `site` and `base` move into the adapter's options.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  deployment: {
+    adapter: "vercel",
+    output: "server",
+    site: "https://docs.example.com",
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { vercel } from "blume/deploy";
+
+export default defineConfig({
+  deployment: vercel({ site: "https://docs.example.com" }),
+});
+```
+
+</CodeGroup>
+
+- `netlify()`, `cloudflare()`, and `node()` work the same way. Naming a host adapter switches to server output; pass `output: "static"` to keep a static build with that host's platform files.
+- A config that only sets `site` or `base` stays as it is: `deployment: { site, base }` is still the static form.
+- `redirects` take exact paths. A `from` or `to` with a `:param` segment or a `*` wildcard now fails validation; Blume 1 never supported patterns, and hosts treated them differently. Move pattern rules into your host's own config (`vercel.json`, `_redirects`).
+- The `--adapter`, `--output`, and `--base` flags on `blume build` are gone, and passing one stops the build with an error naming the `deployment` setting that replaces it. Set the adapter in `blume.config.ts`, and name it explicitly: server output is no longer inferred from the platform's environment.
+
+See [Deployment](/docs/deployment) for each adapter's options.
+
+## Content sources
+
+Each `content.sources` entry is an adapter from `blume/sources` instead of a `{ type }` object.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  content: {
+    sources: [
+      { type: "filesystem", root: "content" },
+      {
+        type: "github-releases",
+        owner: "acme",
+        repo: "sdk",
+        prefix: "changelog",
+      },
+    ],
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { filesystem, githubReleases } from "blume/sources";
+
+export default defineConfig({
+  content: {
+    sources: [
+      filesystem({ root: "content" }),
+      githubReleases({ owner: "acme", repo: "sdk", prefix: "changelog" }),
+    ],
+  },
+});
+```
+
+</CodeGroup>
+
+- `mdx-remote`, `sanity`, `notion`, and `obsidian` become `mdxRemote()`, `sanity()`, `notion()`, and `obsidian()`, with every other field moving into the call unchanged. `{ type: "custom", source }` becomes `custom(source)`.
+- `content.root`, `content.include`, and `content.exclude` are still the shorthand for a single folder, but they can't sit beside `sources` any more. Move them into the `filesystem()` entry.
+- Release pages from `githubReleases()` publish in one language now, so a multi-locale site no longer copies them to every other locale's URL (`/de/changelog/…`). If other sites link to those copies, add [redirects](/docs/deployment#redirects) to the default-locale pages.
+
+## API references
+
+The top-level `openapi`, `asyncapi`, and `graphql` blocks become one `reference` list of adapters from `blume/reference`. Drop `enabled`.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  openapi: { enabled: true, spec: "./openapi.yaml" },
+  graphql: {
+    enabled: true,
+    spec: "./schema.graphql",
+    endpoint: "https://api.example.com/graphql",
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { graphql, openapi } from "blume/reference";
+
+export default defineConfig({
+  reference: [
+    openapi({ spec: "./openapi.yaml" }),
+    graphql({
+      spec: "./schema.graphql",
+      endpoint: "https://api.example.com/graphql",
+    }),
+  ],
+});
+```
+
+</CodeGroup>
+
+- `asyncapi: { … }` becomes `asyncapi({ … })` with the same options.
+- An AsyncAPI 1.x or 2.x spec is still converted to 3.0 for you, but the converter is now an optional peer: install `@asyncapi/converter` in your project, or the build fails with the install command. A 3.x spec needs nothing.
+- `renderer: "scalar"` becomes its own `scalar({ spec, theme, … })` entry in the list, keeping the block's `route` and `sources`.
+- A block with `enabled: false` is simply left out of the list.
+
+## Analytics
+
+The `analytics` object becomes a list of adapters from `blume/analytics`.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  analytics: {
+    posthog: { key: "phc_…" },
+    vercel: true,
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { posthog, vercel } from "blume/analytics";
+
+export default defineConfig({
+  analytics: [posthog({ key: "phc_…" }), vercel()],
+});
+```
+
+</CodeGroup>
+
+`cloudflare: { token }` becomes `cloudflare({ token })`, and each `scripts[]` entry becomes `script({ … })`.
+
+## Ask AI
+
+`ai.ask.provider` takes an adapter from `blume/ai`, which owns the model and the fields that went with it.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  ai: {
+    ask: {
+      enabled: true,
+      provider: "openrouter",
+      model: "anthropic/claude-sonnet-4-5",
+      reasoning: "none",
+    },
+  },
+});
+```
+
+```ts title="Blume 2"
+import { defineConfig } from "blume";
+import { openrouter } from "blume/ai";
+
+export default defineConfig({
+  ai: {
+    ask: {
+      enabled: true,
+      provider: openrouter({
+        model: "anthropic/claude-sonnet-4-5",
+        reasoning: "none",
+      }),
+    },
+  },
+});
+```
+
+</CodeGroup>
+
+The adapters are `gateway()`, `openrouter()`, `llmgateway()`, `inkeep()`, and `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`. `model`, `apiKeyEnv`, `baseUrl`, `headers`, and `reasoning` move into the adapter; `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` stay on `ai.ask`. Leaving `provider` unset still uses the AI Gateway.
+
+## Agents and other config moves
+
+The machine-readable settings move from `ai` to a new `agents` key, and three smaller fields change shape.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+export default defineConfig({
+  ai: { mcp: { enabled: true }, skills: "./skills" },
+  lastModified: true,
+  markdown: {
+    codeBlocks: { theme: { light: "github-light", dark: "github-dark" } },
+  },
+  theme: { layout: "sidebar" },
+});
+```
+
+```ts title="Blume 2"
+export default defineConfig({
+  agents: { mcp: { enabled: true }, skills: "./skills" },
+  lastModified: "git",
+  markdown: {
+    code: { theme: { light: "github-light", dark: "github-dark" } },
+  },
+});
+```
+
+</CodeGroup>
+
+- `ai.api`, `ai.catalog`, `ai.llmsTxt`, `ai.markdownComponents`, `ai.mcp`, `ai.skills`, `ai.webBotAuth`, and `ai.webmcp` become `agents.*`, and so do `seo.agentReadability` and `seo.contentSignals`. `ai` keeps only `ask` and `openInChat`.
+- `lastModified` is a flat value: `true` becomes `"git"`, and `{ type: "git" }` or `{ type: "frontmatter" }` becomes the bare string.
+- `markdown.codeBlocks` merges into `markdown.code`.
+- `theme.layout` is gone. Nothing read it, so delete it.
+
+## Frontmatter
+
+One frontmatter field is gone: `search.boost`. Blume 1 accepted it, but search never read it, so a page ranked the same without it. Delete it wherever it appears; a page that still sets it fails validation with a hint, and `blume upgrade` lists each one with its file and line.
+
+## Component overrides
+
+Blume 2 checks every `components.ts` entry before the build instead of falling back at runtime. Each `mdx` and `layout` entry must be an imported component, a path string, or a `{ component, client, media }` object, and the `islands` group is gone: an `mdx` entry with a `client` mode is an island.
+
+<CodeGroup>
+
+```ts title="Blume 1"
+import { defineComponents } from "blume";
+import Counter from "./islands/Counter.tsx";
+
+export default defineComponents({
+  islands: { Counter },
+});
+```
+
+```ts title="Blume 2"
+import { defineComponents } from "blume";
+import Counter from "./islands/Counter.tsx";
+
+export default defineComponents({
+  mdx: { Counter: { component: Counter, client: "visible" } },
+});
+```
+
+</CodeGroup>
+
+An inline function, a component declared in `components.ts` itself, a spread, or a computed key now fails with `BLUME_COMPONENTS_INVALID`, naming the entry. Move the component into its own file and import it. The `islands/` folder convention works as before. See [Customization](/docs/configuration/customization) for the accepted forms.
+
+## Ejected apps
+
+An app you [ejected](/docs/configuration/customization#eject) on Blume 1 no longer runs through the Blume CLI, but it still depends on the `blume` package. Its pages import Blume's components, `src/generated/` holds a snapshot of your site written by the Blume 1 generator, and `astro build` loads `blume.config.ts` again to write the search index, `llms.txt`, and the sitemap. Bumping `blume` to 2 under it pairs that Blume 1 snapshot with Blume 2 components that expect the new shapes, so eject again instead:
+
+<Steps>
+  <Step title="Copy the project out">
+    Copy everything except `astro.config.mjs`, `src/`, `.blume/`, `dist/`, and
+    `node_modules/` into an empty folder: your content, `blume.config.ts`,
+    `components.ts`, `islands/`, `public/`, any spec files your references read,
+    and `package.json`. Leave the ejected app as it is.
+  </Step>
+  <Step title="Upgrade the copy">
+    In the copy, run `npx blume@latest upgrade` and apply what it lists, so
+    `blume.config.ts` and `components.ts` are valid Blume 2. Then run `npx blume
+    build` to confirm the site builds before you eject it.
+  </Step>
+  <Step title="Eject a fresh copy">
+    Run `npx blume eject --yes` in the copy, install the packages it adds, and
+    build it with `npm run build`.
+  </Step>
+  <Step title="Carry your edits across">
+    Diff the fresh `astro.config.mjs` and `src/` against your ejected app, and
+    move your own changes onto the new files.
+  </Step>
+</Steps>
+
+Until the fresh copy is ready, keep the ejected app on Blume 1 (`"blume": "^1"`) and don't run `blume upgrade` in it: nothing changes until you bump it.
+
+## Command-line flags
+
+Every `blume` command now rejects a flag it doesn't take, where Blume 1 ignored it. A script or CI step that passes a stray or misspelled flag fails, naming the flag it didn't recognize and the ones the command accepts. `blume upgrade` reports only the three removed `blume build` flags (`--adapter`, `--output`, `--base`), so check your other `blume` scripts too.
+
+## Check your work
+
+Once `blume upgrade` reports nothing left to change, run the site's own checks:
+
+```bash
+npx blume doctor
+npx blume build
+```
+
+The full list of changes, with the reasoning behind each, is in the [changelog](/changelog).

package/docs/04-migrating.mdx

@@ -0,0 +1,58 @@
+---
+title: Migrate to Blume
+description: Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with one command that hands the migration to Claude Code or Codex.
+sidebar:
+  label: Migrate to Blume
+  order: 2.4
+---
+
+Moving a docs site to idiomatic Blume takes judgment a codemod can't make: which declared navigation becomes folders, which components become directives, and what has no Blume equivalent. So `blume migrate` hands the job to a coding agent, working from Blume's migration playbook, while you review each edit.
+
+## Migrate with one command
+
+Run it from the root of the docs project you're migrating:
+
+```package-install
+npx blume migrate fumadocs --claude
+```
+
+Swap `fumadocs` for your framework, and `--claude` for `--codex` to use Codex. With pnpm 12, add `--allow-build=esbuild` after `pnpm dlx`, since pnpm 12 won't run esbuild's install script unapproved. The agent opens interactively in your terminal, so every edit goes through its own permission flow. It works in place, so start from a clean working tree and review the whole migration as one diff.
+
+## Sources
+
+Name the framework you're migrating from, or leave it out and Blume detects it from the project's own files. When you name one and the project looks like another, Blume warns and continues with the one you named:
+
+| Source | Detected from |
+| --- | --- |
+| `mintlify` | `docs.json` or `mint.json` |
+| `fumadocs` | `source.config.ts`, or `fumadocs-core`, `fumadocs-ui`, or `fumadocs-mdx` in `package.json` |
+| `docusaurus` | `docusaurus.config.*` |
+| `starlight` | `@astrojs/starlight` in `package.json` |
+| `nextra` | `nextra` in `package.json` |
+
+Each source has its own mapping reference in the playbook. A site built with anything else still migrates: run the command without a source, and the agent inventories the repo first, then works from the playbook's general rules.
+
+## What the agent does
+
+The agent follows the playbook's workflow from the source's config to a passing build:
+
+1. Writes `blume.config.ts`, mapping only what your source declares and leaving Blume's defaults to cover the rest.
+2. Restructures content into [filesystem navigation](/docs/content/navigation), converting per-folder ordering files (Fumadocs `meta.json`, Nextra `_meta`) to `meta.ts`.
+3. Rewrites pages: frontmatter to Blume's schema, callout components to [directives](/docs/content/syntax), icons to Lucide, and snippets inlined.
+4. Adds a [redirect](/docs/deployment#redirects) for every URL that moves, so no link breaks.
+5. Points your `package.json` scripts at `blume dev` and `blume build`, and swaps the old framework's dependencies for `blume`.
+6. Runs `blume build` and `blume validate` until both pass.
+
+It finishes with a summary of what it migrated, dropped, or approximated, such as footer links or dynamic redirects with no Blume equivalent, so you can decide what to do with each.
+
+## Other agents
+
+Without `--claude` or `--codex`, the command reports the source it detected, prints the path to the playbook — the `blume-migrate` [skill](/docs/advanced/skills) bundled in the package — and exits without changing anything. Point any other agent at that `SKILL.md`, or install the skill where your agent looks for skills, with the command it prints:
+
+```bash
+npx skills add haydenbleasel/blume --skill blume-migrate
+```
+
+## Compare first
+
+The [comparison pages](/compare) set Blume beside each framework and list what the migration carries over and rewrites for it.

package/docs/08-faq.mdx

@@ -49,15 +49,15 @@ Yes. Any page can be `.md` or `.mdx`, and MDX lets you drop in the [built-in com
 
 ## Where can I deploy it?
 
-Anywhere. `blume build` outputs static HTML by default, which you can serve from any static host or CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or your own server. Server-only features (Ask AI, the MCP server, on-demand rendering) switch the build to a server function through an adapter for Vercel, Node, Netlify, or Cloudflare. See [Deployment](/docs/deployment).
+Anywhere. `blume build` outputs static HTML by default, which you can serve from any static host or CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or your own server. Server-only features (Ask AI, the MCP server, on-demand rendering) need server output: name a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — as `deployment`. See [Deployment](/docs/deployment).
 
 ## Does search need a hosted service?
 
-No. [Orama](/docs/configuration/search) builds a local index that works in both dev and production with nothing to host or pay for. For very large sites, [Pagefind](/docs/configuration/search) is one flag away. Either way the index ships as part of your site.
+No. [Orama](/docs/configuration/search) builds a local index that works in both dev and production with nothing to host or pay for. For very large sites, [Pagefind](/docs/configuration/search#pagefind) is one adapter away: `search: pagefind()`. Either way the index ships as part of your site.
 
 ## How do I customize the look?
 
-Start with [theme tokens](/docs/configuration/theming) — accent color, fonts, radius, and a `theme.css` for anything else Tailwind can express. Go further by [overriding built-in components](/docs/configuration/customization) or adding [custom pages](/docs/configuration/customization#custom-pages). When you want the Astro project itself, [`blume eject`](/docs/reference/cli) hands you a standalone app that still uses the `blume` package.
+Start with [theme tokens](/docs/configuration/theming) — accent color, fonts, radius, and a `theme.css` for anything else Tailwind can express. Go further by [overriding built-in components](/docs/configuration/customization) or adding [custom pages](/docs/configuration/customization#custom-pages). When you want the Astro project itself, [`blume eject`](/docs/cli) hands you a standalone app that still uses the `blume` package.
 
 ## Why is oxfmt / Ultracite collapsing my directives?
 

package/docs/advanced/blog.mdx

@@ -61,21 +61,28 @@ description: News and writing from the team.
 </CardGroup>
 ```
 
-To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages) at `pages/blog/index.astro` that reads from Astro's `docs` content collection and pairs each entry with its route from `blume:data`:
+To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages) at `pages/blog/index.astro` that reads from Astro's `docs` content collection and pairs each entry with its route from `blume:data`, keyed by the route's `entryId`:
 
 ```astro pages/blog/index.astro lineNumbers
 ---
 import { getCollection } from "astro:content";
 import data from "blume:data";
+import { getBlumeCollection } from "blume/runtime";
 
-const routeById = new Map(data.routes.map((route) => [route.id, route.path]));
+// A custom page renders at its own path only, so list the default locale's
+// posts. getBlumeCollection leaves out drafts, hidden pages, and the copies
+// i18n serves for untranslated pages, so each post is listed once.
+const routes = getBlumeCollection(data, {
+  locale: data.config.i18n?.defaultLocale,
+});
+const routeByEntry = new Map(routes.map((route) => [route.entryId, route.path]));
 
 const posts = (await getCollection("docs"))
-  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
+  .filter((entry) => entry.data.type === "blog" && routeByEntry.has(entry.id))
   .map((entry) => ({
     date: entry.data.date,
     description: entry.data.description,
-    href: routeById.get(entry.id),
+    href: routeByEntry.get(entry.id),
     title: entry.data.title,
   }))
   .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
@@ -93,10 +100,10 @@ const posts = (await getCollection("docs"))
 </ul>
 ```
 
-See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this in the full site layout.
+See [Custom pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this in the full site layout.
 
 <CardGroup cols={2}>
-  <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">
+  <Card title="Custom pages" href="/docs/advanced/custom-pages" icon="folder">
     Mount the blog index and read from blume:data.
   </Card>
   <Card title="Discoverability" href="/docs/discoverability" icon="file">

package/docs/advanced/changelog.mdx

@@ -1,9 +1,11 @@
 ---
-title: Changelog
+title: Changelogs
+sidebar:
+  label: Changelog
 description: Author release notes as ordinary content files or source them from GitHub Releases, and Blume builds a timeline page and an RSS feed automatically.
 ---
 
-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. Or skip the files entirely and [source your changelog from GitHub Releases](#from-github-releases).
+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 index 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
 
@@ -25,11 +27,11 @@ A big batch of components landed this release — columns, frames, trees, and to
 - `CodeGroup` tabs with flush code blocks
 ```
 
-Give every entry a `date` so the timeline and feed sort newest-first. An unquoted YAML date is fine — Blume normalizes it.
+Give every entry a `date` so the index and feed sort newest-first. An unquoted YAML date is fine — Blume normalizes it.
 
 ### The `changelog` object
 
-The optional `changelog` object adds richer metadata for the timeline and feed:
+The optional `changelog` object adds richer metadata for the index and feed:
 
 <TypeTable
   type={{
@@ -46,58 +48,44 @@ The optional `changelog` object adds richer metadata for the timeline and feed:
     "changelog.date": {
       type: "string",
       description:
-        "Publish date. May live here or at the top level — both feed the timeline and RSS feed.",
+        "Publish date. May live here or at the top level — both feed the index and RSS feed.",
     },
   }}
 />
 
-## The timeline page
+## The index page
 
-Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. It renders as a focused, full-width timeline — no sidebar or table of contents — with each entry newest-first, showing its date, label, and `category` tag in a left rail beside its content:
+Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. It's a focused, full-width index — no sidebar or table of contents — that lists every release as one row, newest-first and grouped by year, so a long history stays a short page (well under the size an agent can read in a single context window):
 
-- The entry **title** becomes its label — or `v{version}` when there's no title. It links to that entry's own page, so a release is both a line in the timeline and a shareable permalink.
-- The `category` renders as a tag next to the date.
+- The entry **title** is the row's label — or `v{version}` when there's no title. It links to that entry's own page, which is where the release notes render in full.
+- The `category` renders as a tag beside the title, so a reader can tell a release from a prerelease, or features from fixes, at a glance.
+- The date follows the configured [`dateFormat`](/docs/configuration#date-format), minus the year the row's group already shows.
 - Drafts and `sidebar.hidden` entries are skipped.
 
-The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default timeline.
+The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default index. The `<Update>` component the previous timeline was built from is still available for a hand-authored page that wants inline release notes.
 
-Because this page is generated rather than authored, it isn't part of the content tree — so a header [tab](/docs/content/navigation#tabs) pointing at `/changelog` resolves to the newest entry instead. Give the tab an `href` to land on the index itself:
-
-```ts blume.config.ts
-navigation: {
-  tabs: [
-    { label: "Changelog", path: "/changelog", href: "/changelog" },
-  ],
-}
-```
-
-### Grouped by major version
-
-When your versions follow [semver](https://semver.org) and span more than one major, Blume paginates the timeline by major version. Only the newest major line is shown, with a **Show N.x releases** button at the bottom that reveals the next-oldest major one click at a time:
-
-- Detection is automatic — no configuration. It kicks in only when every listed release parses as `major.minor.patch` and there is more than one major; otherwise the timeline stays flat.
-- It tolerates the scoped tags monorepos publish, so `pkg@2.0.0` groups under `2.x` and `pkg@1.4.0` under `1.x`.
-- It's progressive enhancement: every release is still in the page's HTML (and its RSS feed and search index), so readers without JavaScript — and crawlers — see the complete history. The button only collapses older majors once the page hydrates.
+A header [tab](/docs/content/navigation#tabs) pointing at `/changelog` opens this index — no `href` needed.
 
 ## 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. Blume's own [changelog](/changelog) is built this way:
+Rather than authoring entries by hand, point the built-in [`githubReleases()` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish. Blume's own [changelog](/changelog) is built this way:
 
 ```ts blume.config.ts
+import { filesystem, githubReleases } from "blume/sources";
+
 content: {
   sources: [
-    { type: "filesystem", root: "content" },
-    {
-      type: "github-releases",
+    filesystem({ root: "content" }),
+    githubReleases({
       prefix: "changelog",
       owner: "acme",
       repo: "sdk",
-    },
+    }),
   ],
 }
 ```
 
-The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/reference/cli#auditing-the-built-site) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
+The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/cli/audit) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
 
 ## The RSS feed
 
@@ -124,12 +112,12 @@ When [structured data](/docs/discoverability/structured-data) is on, each change
 <CardGroup cols={2}>
   <Card
     title="Frontmatter"
-    href="/docs/reference/frontmatter#changelog"
+    href="/docs/content/frontmatter#changelog"
     icon="file"
   >
     The full changelog frontmatter schema.
   </Card>
-  <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">
+  <Card title="Custom pages" href="/docs/advanced/custom-pages" icon="folder">
     Replace the generated timeline with your own layout.
   </Card>
 </CardGroup>