blume 2.1.3 → 2.2.0

package/docs/02-deployment.mdx

@@ -14,7 +14,7 @@ sidebar:
 | ---------------- | -------------- |
 | Build command    | `blume build`  |
 | Output directory | `dist`         |
-| Node version     | 22.12 or newer |
+| Node version     | 22.19 or newer |
 
 These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.
 
@@ -68,9 +68,16 @@ blume preview
 
 `blume preview` serves static builds and `node()` and `cloudflare()` server builds. The Vercel and Netlify adapters have no local preview server, so after a `vercel()` or `netlify()` server build it stops with an error instead. Try the site with `blume dev`, or deploy a preview with `vercel deploy` or `netlify deploy`.
 
+On a static build, `blume preview` also answers what the host would, beyond the files in `dist/`. It applies the [redirects](#redirects), patterns included, with their configured status, as the host files the build writes do. It also handles trailing slashes the way static hosts do:
+
+- A page's URL with a trailing slash (`/guide/`) redirects to the page (`/guide`), keeping the query string.
+- A folder of HTML you ship in `public/` (`public/demo/index.html`) is served at `/demo/`, and `/demo` redirects there, so the relative links inside it resolve.
+
+`blume dev` handles trailing slashes the same way.
+
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
+Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it, along with a root-relative `href` or `src` in raw HTML (`<a href="/guide">`, `<img src="/logo.png">`).
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -153,6 +160,8 @@ deployment: netlify({ output: "static" }),
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node()` adapter produces a standalone server you can run directly with `node dist/server/entry.mjs`. It listens on `localhost:4321` unless you set the `HOST` and `PORT` environment variables when you start it (`HOST=0.0.0.0 PORT=8080 node dist/server/entry.mjs`); `host` and `port` passed to `node()` have no effect, because `@astrojs/node` replaces them with Astro's own server settings. Behind a reverse proxy, set `allowedDomains` so the [rate limit](/docs/configuration/rate-limiting#behind-a-reverse-proxy) counts each reader apart. The server resolves its packages through links into your project's `node_modules`, so deploy the project with its installed dependencies, not `dist/` alone. When the site publishes discovery files, serves images a content source downloaded, or configures redirects, Blume puts a small wrapper in front of Astro's entry (moved to `astro-entry.mjs` beside it). It sends the `.well-known` discovery files with their media types and CORS headers and downloaded SVGs sandboxed, which the standalone server's static handler can't do on its own, and answers each redirect with its configured status.
 
+A `vercel()` server build checks the function bundle the adapter traced for packages it imports but didn't copy, which would crash the function on Vercel. A missing import of your own is a warning. A missing Blume dependency stops the build, and the build removes `.vercel/output/config.json`, so `vercel deploy --prebuilt` can't ship the output without the routes Blume adds to it.
+
 A `cloudflare()` server build runs on Cloudflare Workers only, since `@astrojs/cloudflare` dropped Cloudflare Pages in version 13; a static build doesn't load the package, so its `dist/` still deploys to Pages. The server build deploys with `npx wrangler deploy` from the project root after `blume build`: Blume writes the redirected Wrangler config to `.wrangler/deploy/` (and adds `.wrangler/` to `.gitignore`), and names the Worker after your project — the `package.json` `name`, else the site's hostname, else the folder — unless a `wrangler.jsonc` of your own at the project root sets `name`.
 
 On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and points `assets.run_worker_first` at every path except the fingerprinted build assets and the raw `.md`, `.txt`, `.json`, and `.well-known` files, since the platform would otherwise serve the prerendered pages — and its `404.html` for a URL no page backs — before any server code runs; those exempted files keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
@@ -190,9 +199,13 @@ 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`). Server builds answer redirects at request time with the configured status, and so does `blume dev`. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `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.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds answer redirects at request time with the configured status, and so do `blume dev` and `blume preview`. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `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.
 
-A redirect that moves one page to another moves the page's [raw Markdown](/docs/discoverability/markdown#raw-markdown) with it: `/old.md` and `/old.mdx` redirect to `/new.md` and `/new.mdx` with the same status, in `blume dev` and every build.
+A redirect that moves one page to another moves the page's [raw Markdown](/docs/discoverability/markdown#raw-markdown) with it: `/old.md` and `/old.mdx` redirect to `/new.md` and `/new.mdx` with the same status, in `blume dev` and every build. A redirect from an `.html` URL, like `/old.html` from a site you migrated, doesn't, since that URL never had a Markdown copy. Nor does one whose Markdown URL already serves a copy: `/index.md` is the home page's, so a redirect from `/index` to `/` leaves it alone.
+
+A redirect from a page's own `index.html` URL, like `/guide/index.html` to `/guide`, gets no redirect page in a static build, because the page itself is written to that file. Hosts that read the redirect files answer it with the redirect. Any other host serves the page at that URL.
+
+Blume adds one kind of redirect itself: a date-named page that an earlier version published under a shorter URL, like `changelog/12-05-2022.mdx` at `/changelog/05-2022`, redirects from that URL to its own (see [ordering with numeric prefixes](/docs/content#ordering-with-numeric-prefixes)). It adds none where another page lives at the old URL or a redirect you configured already starts there.
 
 Two hosts need more than the file:
 
@@ -217,14 +230,16 @@ redirects: [
 ```
 
 - `:name` matches one whole segment: `/blog/:slug` covers `/blog/hello`, not `/blog/a/b`.
-- `:name*` as the last segment matches the rest of the path, any number of segments: `/beta/:slug*` sends `/beta/guides/setup` to `/v2/guides/setup`, and `/beta` itself to `/v2`. A last segment of `*` does the same.
+- `:name*` as the last segment matches the rest of the path, any number of segments: `/beta/:slug*` sends `/beta/guides/setup` to `/v2/guides/setup`, and `/beta` itself to `/v2`. A last segment of `*` does the same. Every host gets that bare path as a rule of its own (`/beta /v2` in `_redirects`), so all of them send it to the same place. `blume audit` checks where it lands, and reports `/beta` going to a `/v2` the build doesn't serve as a broken redirect.
 - `*` at the end of a segment matches the rest of the path from there: `/articles/concepts-*` covers `/articles/concepts-overview`.
 
 `to` reads a capture by name, as a whole segment (`/:slug*`, `/:slug`), or a `*` for what the `*` in `from` matched (`:splat`, the way `_redirects` spells it, reads it too). A `to` that reads no capture sends every path the pattern covers to one page. An exact redirect wins over a pattern that covers the same path, and patterns are tried in the order you list them.
 
-Each host gets the patterns in its own syntax: splats in `_redirects`, `path-to-regexp` sources in `vercel.json`, and the routing config of a `vercel()` or `netlify()` server build. The `node()` and `cloudflare()` servers match them themselves, and so does `blume dev`. A static build writes no redirect page for a pattern, since it would need one for every path the pattern covers, so a host that reads none of these files (GitHub Pages, say) applies only the exact redirects; `blume-redirects.json` lists patterns as you wrote them.
+Each host gets the patterns in its own syntax: splats in `_redirects`, `path-to-regexp` sources in `vercel.json`, and the routing config of a `vercel()` or `netlify()` server build. The `node()` and `cloudflare()` servers match them themselves, and so do `blume dev` and `blume preview`. A static build writes no redirect page for a pattern, since it would need one for every path the pattern covers, so a host that reads none of these files (GitHub Pages, say) applies only the exact redirects; `blume-redirects.json` lists patterns as you wrote them.
+
+[`blume validate`](/docs/cli/validate) checks where each redirect leads. An exact `to` must be a page, a file in `public/` or one Blume generates, or another redirect's `from`; for a pattern, something must be served under the literal part of `to` before its first capture (`/v2/` in `/v2/:slug*`). One that leads nowhere warns `BLUME_BROKEN_REDIRECT` at its `to`. [`blume audit`](/docs/cli/audit) follows every redirect through the built site.
 
-A pattern can't also match a page: hosts disagree on which of the two answers, so the build stops with `BLUME_REDIRECT_MATCHES_PAGE`, naming the page. Narrow the pattern to the paths that moved. An exact redirect from a page's own URL answers the same way on every host, taking the URL over so the page never publishes, so the same code is a warning there: delete the page if it moved, or drop the redirect.
+A pattern can't also match a page: hosts disagree on which of the two answers, so the build stops with `BLUME_REDIRECT_MATCHES_PAGE`, naming the page. Narrow the pattern to the paths that moved. An exact redirect from a page's own URL answers the same way on every host, taking the URL over so the page never publishes, so the same code is a warning there: delete the page if it moved, or drop the redirect. So is one from a page's Markdown copy, like `/guide.md` or the home page's `/index.md`, which takes that copy away from agents: drop the redirect.
 
 ## Content types
 
@@ -254,7 +269,7 @@ When a feature needs a secret, Blume warns at `blume dev`/`build` if it's missin
 | [Rate limiting](/docs/configuration/rate-limiting) (`upstash()`) | `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
 | [Narration](/docs/configuration/narration) (generated voices) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) for `gateway()`, `OPENAI_API_KEY` for `openai()` (none with a `baseUrl`, unless you name one), or the `apiKeyEnv` you passed to either |
-| [Content sources](/docs/content/sources) | `NOTION_TOKEN` (`notion()`), `SANITY_TOKEN` (`sanity()`), `CONTENTFUL_ACCESS_TOKEN` (`contentful()`, plus `CONTENTFUL_PREVIEW_TOKEN` for `--preview`, which fails without it), `PAYLOAD_API_KEY` (`payload()`), `STRAPI_API_TOKEN` (`strapi()`), `GITHUB_TOKEN` (`githubReleases()`, and `mdxRemote()` reading from GitHub) |
+| [Content sources](/docs/content/sources) | `NOTION_TOKEN` (`notion()`), `SANITY_TOKEN` (`sanity()`), `CONTENTFUL_ACCESS_TOKEN` (`contentful()`, plus `CONTENTFUL_PREVIEW_TOKEN` for `--preview`, which fails without it), `PAYLOAD_API_KEY` (`payload()`), `STRAPI_API_TOKEN` (`strapi()`), `GITHUB_TOKEN` (`githubReleases()`, and `mdxRemote()` with `github`) |
 
 Set them in `.env.local` for local dev and in your host's environment for production. A content source reads its token when it fetches, during `blume dev` and `blume build`, and narration reads its key during `blume build`, so set those where your site builds. Build-time secrets for search-index sync (`ALGOLIA_ADMIN_API_KEY`, `ORAMA_PRIVATE_API_KEY`, `TYPESENSE_ADMIN_API_KEY`) are checked by the sync step itself: when one is unset, the build warns and skips the sync, and when it's set, a failed sync [fails the build](/docs/configuration/search#adapters). The [GitHub info](/docs/content/components#github-info) card also sends `GITHUB_TOKEN`, when it's set, to lift GitHub's API rate limit.
 

package/docs/04-migrating.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrate to Blume
-description: Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with one command that hands the migration to Codex or Claude Code.
+description: Move a Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, or other docs site to Blume with one command that hands the migration to Codex or Claude Code.
 sidebar:
   label: Migrate to Blume
   order: 2.4
@@ -29,8 +29,20 @@ Name the framework you're migrating from, or leave it out and Blume detects it f
 | `docusaurus` | `docusaurus.config.*` | [Migrate from Docusaurus](/guides/migrate-from-docusaurus) |
 | `starlight` | `@astrojs/starlight` in `package.json` | [Migrate from Starlight](/guides/migrate-from-starlight) |
 | `nextra` | `nextra` in `package.json` | [Migrate from Nextra](/guides/migrate-from-nextra) |
-
-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. The [MkDocs Material guide](/guides/migrate-from-mkdocs-material) walks through a migration that way.
+| `vitepress` | `.vitepress/config.ts` (or `.mts`, `.js`, `.mjs`) at the root or in `docs/`, or `vitepress` in `package.json` | [Migrate from VitePress](/guides/migrate-from-vitepress) |
+| `vuepress` | `.vuepress/config.ts` (or `.js`, `.mjs`, `.yml`, `.toml`) at the root or in `docs/`, `vuepress.config.*`, or `vuepress` (or `vuepress-vite`, `vuepress-webpack`) in `package.json` | [Migrate from VuePress](/guides/migrate-from-vuepress) |
+| `docus` | `docus` (Docus 3 and later) or `@nuxt-themes/docus` (Docus 1) in `package.json`; run it from the docs package in a workspace | [Migrate from Docus](/guides/migrate-from-docus) |
+| `mkdocs` | `mkdocs.yml`, `mkdocs.yaml`, `zensical.toml`, `properdocs.yml`, or `properdocs.yaml` | [Migrate from MkDocs Material](/guides/migrate-from-mkdocs-material) |
+| `mdbook` | `book.toml` at the root or in `docs/` or `book/` | [Migrate from mdBook](/guides/migrate-from-mdbook) |
+| `fern` | `fern/docs.yml` | [Migrate from Fern](/guides/migrate-from-fern) |
+| `gitbook` | `.gitbook.yaml`, `.gitbook.yml`, or `gitbook-docs.yaml`, or `honkit` or `gitbook-cli` in `package.json`; never `SUMMARY.md` alone | [Migrate from GitBook](/guides/migrate-from-gitbook) |
+| `redocly` | `sidebars.yaml`, or `@redocly/realm` or another Realm-family package in `package.json`; never `redocly.yaml` alone | [Migrate from Redocly](/guides/migrate-from-redocly) |
+| `readme` | `_order.yaml` in `docs/`, `reference/`, `recipes/`, or `custom_pages/`; a repository that uploads with `rdme` needs the source named | [Migrate from ReadMe](/guides/migrate-from-readme) |
+| `docsify` | `docsify-cli` or `docsify` in `package.json`; a site without a `package.json` needs the source named | [Migrate from Docsify](/guides/migrate-from-docsify) |
+| `jekyll` | `_config.yml` at the root or in `docs/`, checked after every other source Blume detects | [Migrate from Just the Docs](/guides/migrate-from-jekyll) |
+| `github-wiki` | Never detected: a wiki has no config file, so name the source | [Migrate from a GitHub wiki](/guides/migrate-from-github-wiki) |
+
+Detection checks the folder you run the command in. Each source has its own mapping reference in the playbook, and several also have a codemod the agent runs first for the mechanical rewrites, so its own effort goes to the judgment calls. 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
 
@@ -39,7 +51,7 @@ The agent follows the playbook's workflow from the source's config to a passing
 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.
+4. Adds a [redirect](/docs/deployment#redirects) for every URL that moves, so no link breaks. Docsify's `#/` URLs never reach the server, so for those it adds a small script that sends each one to its new page. A GitHub wiki's URLs stay on github.com, which can't redirect, so the agent maps each page to its new route and prepares link stubs you can push to the old wiki.
 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.
 

package/docs/advanced/changelog.mdx

@@ -73,7 +73,33 @@ changelog: {
 
 Each takes a map of locale code to text too, like a [header tab label](/docs/content/i18n#per-locale-navigation). The index renders in the default locale, so it shows that locale's entry. Leave either unset and it keeps the built-in text, which a [UI string override](/docs/content/i18n#translated-ui) (`changelog.title` and `changelog.description` under `i18n.ui`) replaces.
 
-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 still ships for a custom page that wants inline release notes. It isn't one of the MDX components, so import it in the `.astro` page itself: `import Update from "blume/components/content/Update.astro";`.
+The page appears only when nothing already occupies the `/changelog` route.
+
+### Writing your own index
+
+To put something above the list — an introduction, a link to the feed, a note about your release cadence — write the page yourself and place `<Changelog />` where the list belongs. Blume still owns the list, so you only write the parts it has no slot for:
+
+```mdx changelog/index.mdx
+---
+title: Changelog
+description: Every Acme SDK release, newest first.
+mode: center
+---
+
+Every release, newest first. Subscribe to the [RSS feed](/changelog/rss.xml) to follow along.
+
+<Changelog />
+```
+
+A content page at `/changelog` takes over the route, so the generated page steps aside and yours renders instead. Put it at `changelog/index.mdx`, beside your entries, so the sidebar's Changelog group links to it — a `changelog.mdx` next to the folder adds a second Changelog item to the sidebar. [`mode: center`](/docs/content/frontmatter#layout) gives it the generated page's layout — no sidebar, no table of contents, a wider centered column — and the generated page renders the same component, so the two can't drift apart. The list downlevels to Markdown on the agent surfaces (`/changelog.md`, llms-full.txt, MCP `get_page`, search) exactly as the generated page's does.
+
+The list is always the default locale's entries, wherever the tag sits — the rule every surface that publishes it already follows, so a translated page lists the same releases rather than disagreeing about which exist. Its dates read in the page's own language.
+
+### Replacing the page entirely
+
+For a design the component can't express, 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 still ships for a custom page that wants inline release notes. It isn't one of the MDX components, so import it in the `.astro` page itself: `import Update from "blume/components/content/Update.astro";`.
+
+Building the list yourself means reproducing what `<Changelog />` does, including one thing that fails quietly: entries from a non-filesystem source (such as [GitHub Releases](#from-github-releases)) render through a parallel `staged` collection, so a page that reads `getCollection("docs")` alone lists none of them, with no warning. Prefer `<Changelog />` in a content page unless you genuinely need different markup.
 
 ## From GitHub Releases
 

package/docs/advanced/skills.mdx

@@ -15,7 +15,7 @@ npx skills add haydenbleasel/blume
 
 ## Migration
 
-`blume-migrate` moves an existing docs site to Blume: Mintlify, Fumadocs, Docusaurus, Starlight, Nextra, or any other framework. It targets idiomatic Blume rather than a line-by-line port, with a mapping reference for each named framework, a redirect for every URL that moves, and a report of anything it drops. The quickest way to run it is [`blume migrate`](/docs/migrating), which detects your framework and opens Codex or Claude Code on the copy bundled in the package. To use it from another agent, install it:
+`blume-migrate` moves an existing docs site to Blume from Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, the [other named sources](/docs/migrating#sources), or any other framework. It targets idiomatic Blume rather than a line-by-line port, with a mapping reference for each named framework, a redirect for every URL that moves, and a report of anything it drops. The quickest way to run it is [`blume migrate`](/docs/migrating), which detects your framework and opens Codex or Claude Code on the copy bundled in the package. To use it from another agent, install it:
 
 ```bash
 npx skills add haydenbleasel/blume --skill blume-migrate

package/docs/cli/audit.mdx

@@ -28,7 +28,7 @@ Findings are grouped by check rather than listed per page, so the report reads a
 - `--url <origin>` — also probe a live deployment for status codes, response headers, and configured redirects.
 - `--external` — probe outbound links over the network.
 - `--ignore <glob>` — with `--external`, don't probe an outbound link whose URL matches the glob, like `--ignore "https://api.acme.example/**"`. Repeat the flag for more patterns. It matches the way [`blume validate --ignore`](/docs/cli/validate#flags) does, and internal links are always checked.
-- `--only <check|category>` / `--skip <check|category>` — narrow the report to, or away from, these checks or categories (comma-separated). A term that names no check or category is an error that suggests the closest one, so a typo can't quietly empty the report.
+- `--only <check|category>` / `--skip <check|category>` — narrow the report to, or away from, these checks or categories (comma-separated). The audit count in the summary counts only the checks left in. A term that names no check or category is an error that suggests the closest one, so a typo can't quietly empty the report.
 - `--list-checks` — print every check the audit can report, then exit.
 - `--verbose` — list every affected page with each finding's full detail, instead of the first few.
 - `--json` — emit the report as JSON on stdout.

package/docs/cli/doctor.mdx

@@ -15,8 +15,8 @@ blume doctor
 
 - **The Node version** against the range the installed `blume` package supports, read from its own `engines` field. A version outside it is a warning: things may work, but it isn't a combination Blume tests.
 - **`blume.config.ts`**, with the same validation a build runs. A removed or renamed key fails with a hint naming its replacement rather than a bare "unrecognized key".
-- **Every content page and folder meta**: the diagnostics `blume dev` and `blume build` print as they load the project — invalid frontmatter, navigation problems, missing include targets, and the rest — collected in one report.
-- **Navigation that leads nowhere**: a tab, selector item, featured link, header action, or call to action whose path matches no page, custom `.astro` page, generated route, or reference: a warning (`BLUME_NAV_MISSING_PAGE`), the same one `blume dev` and `blume build` print.
+- **Every content page and folder meta**: the diagnostics `blume dev` and `blume build` print as they load the project — invalid frontmatter, `.mdx` that doesn't [parse](/docs/content#markdown-and-mdx), navigation problems, missing include targets, and the rest — collected in one report.
+- **Navigation that leads nowhere**: a tab, selector item, featured link, header action, or call to action whose path matches no page, custom `.astro` page, generated route, reference, `public/` file, or file Blume generates: a warning (`BLUME_NAV_MISSING_PAGE`), the same one `blume dev` and `blume build` print. A tab is checked where it links: its `href` when it has one, else its `path`.
 - **[`<Component>`](/docs/content/components#component) examples that don't exist**: a `path` that names no file under `examples`, which the page would show as a "No example found" box: a warning (`BLUME_EXAMPLE_NOT_FOUND`) at its line, as `blume dev` and `blume build` print it. A `components.ts` override or island named `Component` replaces the built-in, and isn't checked.
 - **Features that need a server** on a site configured for static output — the assistant, the MCP server, the Try it playground's built-in proxy, or server-mode search (Mixedbread): an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to `output: "static"`, telling you to drop that option).
 - **Packages your config needs** that aren't installed — the SDK a search, content source, assistant, or narration adapter imports, a deployment adapter's `@astrojs/*` package, or the renderer for Vue or Svelte islands: an error naming each package, with the install command for your package manager. `blume build` stops on the same check.

package/docs/cli/evals.mdx

@@ -49,7 +49,7 @@ questions:
   - id: install-node-version
     question: What is the minimum Node.js version required?
     expected:
-      - Node 22.12 or newer
+      - Node 22.19 or newer
     routes: /docs/quickstart
   - id: deploy-vercel
     question: How do I deploy to Vercel?

package/docs/cli/index.mdx

@@ -26,7 +26,7 @@ blume <command> [options]
 | [`blume translate`](/docs/cli/translate) | Translate docs into the configured locales with a local agent CLI. |
 | [`blume version [id]`](/docs/cli/version) | Freeze the current docs as an archived version (no id lists configured versions). |
 | [`blume skill`](/docs/discoverability/agent-discovery#your-sites-skill) | Write your docs' agent skill with Codex or Claude Code, in place of the generated one. |
-| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with Codex or Claude Code. |
+| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, or other docs site to Blume with Codex or Claude Code. |
 | [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Codex or Claude Code. |
 
 ## Common flags
@@ -42,7 +42,7 @@ blume <command> [options]
 - `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 --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
+- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation, and `.mdx` pages that don't [parse](/docs/content#markdown-and-mdx), are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. A failure only the build itself finds, such as a page that throws while it renders, still fails it. `blume dev --strict` opts dev into the same fail-fast behavior.
 - `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 build --isolated` — build into a throwaway `.blume-verify/` runtime (and its own `dist/`) instead of `.blume/`, so a running `blume dev` server and your real `dist/` are left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
@@ -107,3 +107,5 @@ Add a `tsconfig.json` extending Astro's config to your project root so authored
 ```
 
 Without a project `tsconfig.json`, only the generated runtime is checked.
+
+The build reads this file too, to resolve imports, so an `extends` or `references` entry that doesn't resolve (a package that isn't installed, a file that was moved, a framework's generated tsconfig that doesn't exist yet) stops `blume build`, `blume dev`, and `blume check` with `BLUME_TSCONFIG_EXTENDS`, at the line that names it. Install, restore, or generate the file, or remove the entry.

package/docs/cli/validate.mdx

@@ -9,14 +9,16 @@ description: blume validate checks every link in your content — pages, anchors
 blume validate
 ```
 
-- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors. Every link form Markdown and MDX render is read: inline links, including one whose label wraps onto the next line; reference-style links, checked at their `[label]: /target` definition; autolinks (`<https://…>`, in `.md`); and a component's string `href` (`<Card href="./install">`). A lowercase HTML `<a href>` ships exactly as written, so it's checked the way a browser reads it: a relative path resolves against the page's URL, and no [`basePath`](/docs/deployment#mount-the-docs-under-a-path) is added. An `href={…}` expression isn't checked.
-- **Anchor links** (`#section`, `/guides/intro#setup`) must match an anchor on the target page — a heading's id (generated or [pinned](/docs/content/syntax#custom-anchors)) or a raw HTML element's `id` attribute — with misses reported as warnings. Ids inside code blocks, inline code, HTML comments, and `<Prompt>` blocks don't count.
-- **Asset links** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`) against the page's own folder. A plain link to a relative path still resolves as a site route — only image embeds go through the image pipeline.
+- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors. Every link form Markdown and MDX render is read: inline links, including one whose label wraps onto the next line; reference-style links, checked at their `[label]: /target` definition (the first one, when a label is defined twice, since that's the one that renders); autolinks (`<https://…>`, in `.md`); and a component's string `href` (`<Card href="./install">`). A root-relative link to a Markdown file in your content (`/guides/setup.md`) is checked at the page that file publishes, where the build points it; one naming no file there is checked as the page's [Markdown copy](/docs/discoverability/markdown#raw-markdown). A link's target is read the way the renderer reads it, so `[x](<https://example.com/a(b>)` points at `https://example.com/a(b` and `![](image\(1\).png)` at `image(1).png`, with any spaces around it and a title in any of its quotes (`"…"`, `'…'`, or `(…)`) after it. Links in code (fenced, including a fence inside a block quote, or inline) and in comments (`<!-- … -->` in `.md`, `{/* … */}` in `.mdx`) never render, so they aren't checked. A lowercase HTML `<a href>` to a page ships as written, so it's checked the way a browser reads it: a relative path resolves against the page's URL, and no [`basePath`](/docs/deployment#mount-the-docs-under-a-path) is added (a root-relative one gains a [deployment `base`](/docs/deployment#subpath-deploys), as every link does). An `href={…}` expression isn't checked.
+- **Anchor links** (`#section`, `/guides/intro#setup`) must match an anchor on the target page — a heading's id (generated or [pinned](/docs/content/syntax#custom-anchors)), a raw HTML element's `id` attribute, or an `<a name>` — with misses reported as warnings. Ids inside code blocks, inline code, HTML comments, and `<Prompt>` blocks don't count.
+- **Other link schemes** (`mailto:`, `tel:`, an app's `vscode:` deep link) aren't checked: whether a reader's browser or an installed app handles one can't be known. ReadMe's own link schemes are the exception: `doc:`, `ref:`, `page:`, `changelog:`, and `blog:` only resolve on ReadMe and ship as dead links anywhere else, so each is reported as a warning. Link the page by its path instead.
+- **Asset links** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`, or a card's `<Card img="./cover.png">`) against the page's own folder. A relative link to any other file (`[spec](./spec.pdf)`, or an `<a href>` or a component's `href`) is checked against the page's own folder too, since Blume [publishes a file there](/docs/content/syntax#links-and-images) with the page; one that names no file beside the page resolves as a site route against `public/`. A media element's `src` (`<img>`, `<source>`, `<video>`, or `<audio>`, as raw HTML in `.md` or an element in `.mdx`) is checked the same way: a relative one is found beside the page, or else where the browser requests it, against `public/`. A project with no `public/` folder ships no public files, so an absolute asset path there is reported missing. An `.html` link (`./setup.html`, `/guides/setup.html`) is a file link too: Blume serves pages at their routes, never at `.html` URLs, so unless `public/` has that file, the link is reported, with the page's route as the fix when a page matches it.
+- **Redirect targets** in [`redirects`](/docs/deployment#redirects) must lead somewhere: an exact internal `to` to a page, a file, or another redirect, and a [pattern](/docs/deployment#pattern-redirects) `to` to a path with something served under its literal start (`/v2/` in `/v2/:slug*`). One that leads nowhere is a warning, located at its `to` in `blume.config.ts`. A link to a redirect's `from` is valid either way. External targets aren't checked.
 - **External links** are only checked with [`--external`](#flags) (off by default since it requires the network). A dead link is an error: a 404 or 410, or a host name that doesn't resolve. Anything else that fails is a warning, since it's more often the other site or the network than the link: any other error status (a 401 or 403 from a site that turns bots away, a 429 rate limit, a 5xx outage), a refused or dropped connection, or no answer within 10 seconds. To leave out URLs that can't be checked from where the command runs, like a placeholder domain, a local server, or a site that turns bots away, pass [`--ignore`](#flags). A bare URL that GitHub-flavored Markdown links on its own, with no link syntax around it, isn't read; [`blume audit --external`](/docs/cli/audit) checks it in the built site.
 
 ## What counts as a page
 
-Links resolve against everything the built site serves, not just Markdown pages: custom [`.astro` pages](/docs/advanced/custom-pages), the generated [changelog](/docs/advanced/changelog) index, every configured [redirect](/docs/deployment#redirects), and, on a [multi-language site](/docs/content/i18n), an untranslated page's fallback URL under each locale. A page that fails to parse is reported alongside the link findings, because a page that never loads is a link-validation blind spot rather than a clean result.
+Links resolve against everything the built site serves, not just Markdown pages: custom [`.astro` pages](/docs/advanced/custom-pages), [API reference](/docs/references/openapi) pages, the generated [changelog](/docs/advanced/changelog) index, every configured [redirect](/docs/deployment#redirects), and, on a [multi-language site](/docs/content/i18n), an untranslated page's fallback URL under each locale. The files Blume writes beside your pages count too, while the config has them on: `/llms.txt` and `/llms-full.txt`, the sitemap, `/robots.txt`, the RSS feeds, `/openapi.json`, `/agent-readability.json`, `/skill.md`, and the `.well-known` discovery files such as `/.well-known/agent-skills/index.json`. So does a folder in `public/` with an `index.html`, at `/demo` or `/demo/` for `public/demo/index.html`, as a static host serves it. A page that fails to load, with invalid front matter or `.mdx` that doesn't [parse](/docs/content#markdown-and-mdx) (`BLUME_MDX_SYNTAX`), is reported alongside the link findings, because a page that never loads is a link-validation blind spot rather than a clean result.
 
 ## Flags
 
@@ -29,10 +31,11 @@ Links resolve against everything the built site serves, not just Markdown pages:
 
 | Code | Severity | Meaning |
 | --- | --- | --- |
-| `BLUME_BROKEN_LINK` | error | An internal link points at a route no page serves. |
+| `BLUME_BROKEN_LINK` | error | An internal link points at a route no page serves. When it's a relative link to a file that exists but whose name, or a folder's, starts with `_`, the fix says so: that file is a [partial](/docs/content/includes#partials), which isn't published. |
 | `BLUME_BROKEN_ANCHOR` | warning | The page exists but has no anchor matching the fragment. |
-| `BLUME_BROKEN_ASSET` | warning | An absolute path isn't in `public/`, or a relative image embed isn't beside the page. |
-| `BLUME_ASSETS_UNCHECKED` | info | There is no `public/` directory, so absolute asset paths weren't checked. |
+| `BLUME_BROKEN_ASSET` | warning | An absolute path isn't in `public/`, a relative image embed isn't beside the page, an `.html` link names no file in `public/`, or a media `src` names a file the site doesn't serve at that URL. |
+| `BLUME_BROKEN_REDIRECT` | warning | A redirect's internal `to` leads to no page, file, or other redirect. |
+| `BLUME_UNSUPPORTED_LINK_SCHEME` | warning | A link uses one of ReadMe's link schemes (`doc:`, `ref:`, `page:`, `changelog:`, `blog:`), which browsers can't follow. |
 | `BLUME_DEAD_LINK` | error or warning | An external link (with `--external`) returned 404/410 or its host doesn't resolve (error), or it got any other error status, no connection, or no answer in time (warning). |
 
 The exit code is the contract: errors exit non-zero, and `--strict` makes warnings do the same.

package/docs/configuration/analytics.mdx

@@ -393,6 +393,8 @@ analytics: [
 
 `attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto the tag, and `strategy` adds `async` or `defer` to external scripts.
 
+A root-relative `src` points at a file in `public/` (`src: "/js/redirects.js"` for `public/js/redirects.js`), so under a [`deployment.base`](/docs/deployment#subpath-deploys) it gets the base, like a link does: with `base: "/docs"`, the tag loads `/docs/js/redirects.js`. A `src` that already starts with the base is left as written, and an absolute or protocol-relative URL passes through, so a script served outside the site's base takes its full URL.
+
 ## Options
 
 | Adapter | Option | Default | Description |

package/docs/configuration/customization.mdx

@@ -22,6 +22,8 @@ export default defineComponents({
 
 Keys are the names you write in MDX (`<Callout>`, `<Pricing>`). Use the `.tsx` filename when you import React components.
 
+A capitalized tag that's neither a built-in, an [island](/docs/content/islands), nor an override fails the page when it renders, so `blume dev`, `blume build`, and `blume check` warn about it first as `BLUME_UNKNOWN_COMPONENT`, once per tag, naming every page that uses it.
+
 ### Reference form
 
 Every override — in `mdx` or `layout` — accepts three forms:
@@ -104,7 +106,7 @@ Wired slots (names are case-sensitive; any other key under `layout` renders nowh
 
 The `mobile` variant also receives the [page actions](/docs/content/navigation#page-actions) as its children (an empty element the actions move into from the right rail below 1,280px), so render a `<slot />` in it to keep them on narrower screens. It renders on a page with no headings as well, with `headings` empty, so the actions still show there.
 
-`PageHeader` and `PageFooter` have no built-in component — they render nothing until you set them, which makes them handy injection points for a promo banner or a "last updated" note. The built-in `Footer` holds the only links to your repository and social profiles, so a `Footer` override (the place for a marketing footer the config can't express) should keep them. With `consent` set, also keep a way to reopen it: any element with `data-blume-consent-open` works as the [Cookie settings](/docs/configuration/consent#changing-an-answer) link.
+`PageHeader` and `PageFooter` have no built-in component — they render nothing until you set them, which makes them handy injection points for a promo banner or a "last updated" note. `PageFooter` renders at the foot of every page Blume builds from your content, API operation pages included, with `Feedback` and `Pagination` after it. A page in [`custom` or `frame` mode](/docs/content/frontmatter#layout) drops that page-end area along with its title and breadcrumbs. A [custom page](/docs/advanced/custom-pages) under `pages/` renders the layout it wraps itself in: `RootLayout` takes slot overrides through its `layout` prop, and `PageLayout` has no page-end area. The built-in `Footer` holds the only links to your repository and social profiles, so a `Footer` override (the place for a marketing footer the config can't express) should keep them. With `consent` set, also keep a way to reopen it: any element with `data-blume-consent-open` works as the [Cookie settings](/docs/configuration/consent#changing-an-answer) link.
 
 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.
 

package/docs/configuration/index.mdx

@@ -238,7 +238,7 @@ content: {
 | --- | --- | --- |
 | `root` | `"docs"` | Folder Blume scans for content. Shorthand for a single `filesystem()` source; not allowed beside `sources`. |
 | `include` | `["**/*.{md,mdx}"]` | Globs that match content files. Shorthand, like `root`. |
-| `exclude` | `["**/_*", "**/.*"]` | Globs to ignore (underscore- and dot-files). Shorthand, like `root`. |
+| `exclude` | `["**/_*", "**/.*"]` | Globs to ignore. Yours add to the defaults, which skip underscore- and dot-files; a `!` entry drops a pattern, so `"!**/_*"` publishes `_`-prefixed files. Shorthand, like `root`. |
 | `sources` | one `filesystem()` | Content source adapters from `blume/sources`, replacing the shorthand. See [Content sources](/docs/content/sources). |
 | `pages` | `"pages"` | Folder for custom `.astro` pages. |
 | `defaultType` | `"doc"` | Page `type` used when frontmatter omits it. |
@@ -365,7 +365,7 @@ lastModified: "git",
 | `"git"` | Read the date from git history (commit dates). |
 | `"frontmatter"` | Never run git — use only the `lastModified` frontmatter field. |
 
-The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time. CI platforms usually check out a shallow clone, which silently drops most dates (the build warns with `BLUME_SHALLOW_GIT_HISTORY` when that happens): on Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable; with `actions/checkout`, set `fetch-depth: 0`. A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
+The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time. It follows renames, as `git log --follow` does: renaming `page.md` to `page.mdx`, or moving a file to another folder under the same content root, keeps the page's date as long as the commit leaves its content unchanged. A rename that also edits the file dates the page at that commit, and so does moving a file in from outside the content root. CI platforms usually check out a shallow clone, which silently drops most dates (the build warns with `BLUME_SHALLOW_GIT_HISTORY` when that happens): on Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable; with `actions/checkout`, set `fetch-depth: 0`. A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
 
 ```mdx page.mdx
 ---

package/docs/configuration/theming.mdx

@@ -36,6 +36,8 @@ Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and
 
 A string applies to both color modes; pass an object for [a different accent per mode](#dark-mode-colors).
 
+A value that's neither a preset nor a CSS color, like `"deep purple"` or a hex value without its `#`, warns `BLUME_THEME_COLOR_INVALID` at the line in `blume.config.ts` that sets it, since browsers ignore the styles that use it. The same check covers `action`, `background`, and the [Open Graph card's](/docs/discoverability/open-graph) `seo.og.palette`. Custom properties (`var(--brand)`), `color-mix()`, and the other color functions pass as written.
+
 Text on an accent or action fill, like a button label or a step number, is white while white meets AA on that color, and dark otherwise. A light accent gets dark labels without any extra config. [`blume audit`](/docs/cli/audit#theme-contrast-low) checks a custom accent, action, or background against the same bar.
 
 ### Radius
@@ -231,6 +233,8 @@ Set a token under `:root` for light mode and under `:root[data-theme="dark"]` fo
 | `--blume-code-highlight`, `--blume-code-highlight-border` | Background and left rule of a highlighted code line (`// [!code highlight]` or a `{1,4-5}` range) |
 | `--blume-code-add`, `--blume-code-add-border` | Background and left rule of an added line (`// [!code ++]`) |
 | `--blume-code-remove`, `--blume-code-remove-border` | Background and left rule of a removed line (`// [!code --]`) |
+| `--blume-code-error`, `--blume-code-error-border` | Background and left rule of an error line (`// [!code error]`) |
+| `--blume-code-warning`, `--blume-code-warning-border` | Background and left rule of a warning line (`// [!code warning]`) |
 | `--blume-code-word`, `--blume-code-word-border` | Background and outline of a highlighted word (`// [!code word:…]`) |
 | `--blume-content-width` | Max width of the prose column — article, breadcrumb, table of contents, feedback, and pagination (default `42rem`) |
 | `--blume-radius` | Corner radius |
@@ -248,7 +252,7 @@ Set a `--blume-font-*` token to any font stack to use a font outside the curated
 
 ## Tailwind utilities
 
-Blume's theme is built with Tailwind v4 internally, and your project's `.astro`, `.tsx`, and `.jsx` files are scanned too — so you can style custom components and pages with utility classes, no Tailwind setup required. Every token is exposed as a utility, so your components track the theme automatically:
+Blume's theme is built with Tailwind v4 internally, and your project's `.astro`, `.jsx`, `.mdx`, `.ts`, and `.tsx` files are scanned too — so you can style custom components and pages with utility classes, no Tailwind setup required. Every token is exposed as a utility, so your components track the theme automatically:
 
 | Token                       | Utilities                  |
 | --------------------------- | -------------------------- |

package/docs/content/components.mdx

@@ -5,6 +5,8 @@ description: Cards, steps, tabs, accordions, badges, code groups, frames, trees,
 
 Blume ships an accessible, themeable component set available in any `.mdx` page with **no imports**. Each one is shown below with a live preview and its source. Components are vanilla and React-free; React switches on only when your project uses it — any `.tsx` or `.jsx` file in the project, a React [island](/docs/content/islands), [`<Component>`](#component) example, or [component override](/docs/configuration/customization) — or when the [assistant](/docs/configuration/assistant) is enabled.
 
+A component ignores props it doesn't take. Most show their children, so other docs tools' spellings can render empty: VitePress's `<Badge type="tip" text="beta" />` is a Badge with no children, which shows nothing. Blume warns about a childless component given props it doesn't take as `BLUME_UNKNOWN_PROP`, with the props it does take. Write the content between the tags instead: `<Badge>beta</Badge>`.
+
 ## Card and CardGroup
 
 Cards link to a destination with an icon, title, and short blurb. Group them with `CardGroup` for a responsive grid. Reach for them on landing pages, section indexes, and “next steps” — anywhere you’re guiding the reader onward.
@@ -31,7 +33,7 @@ Cards link to a destination with an icon, title, and short blurb. Group them wit
 
 `Card` takes `title`, an optional `href` (omit it for a non-clickable card), and an `icon` from Blume's built-in icon set. `CardGroup` takes `cols` (default `2`).
 
-A card also takes `img`, an image across its top (or beside the text from the `sm` breakpoint up, with `horizontal`); `cta`, a call-to-action line in the accent color beneath the text; `arrow`, an arrow after the title and the CTA (shown by default only for external links); `type`, which tints the card and picks a matching icon the way a callout does (`note`, `info`, `tip`, `check`, `warning`, or `danger`); and `color`, any CSS color for the icon.
+A card also takes `img`, an image across its top (or beside the text from the `sm` breakpoint up, with `horizontal`), given like a Markdown image's path: a file next to the page (`./cover.png`), a path under `public/`, or a URL; `cta`, a call-to-action line in the accent color beneath the text; `arrow`, an arrow after the title and the CTA (shown by default only for external links); `type`, which tints the card and picks a matching icon the way a callout does (`note`, `info`, `tip`, `check`, `warning`, or `danger`); and `color`, any CSS color for the icon.
 
 ## Steps
 
@@ -119,6 +121,22 @@ pip install acme-commerce
 
 The first view shows until the reader picks another. Blume remembers that pick across pages written in views, and writes it to the URL as `?view=Python`, so a link opens on the same view. A link to a heading inside a view opens that view. Use `<View>` when most of the page changes with the choice, and [Tabs](#tabs) when only one part of the page does. The agent-facing Markdown includes every view, each under its name.
 
+## Callout
+
+`<Callout>` is the component behind [callout directives](/docs/content/syntax#callouts): `:::warning[Heads up]` renders `<Callout type="warning" title="Heads up">`. Write the component itself when a callout needs its own icon or color, which a directive can't set.
+
+<Callout type="tip" title="Ship it" icon="rocket">
+  Run `blume build` before you deploy.
+</Callout>
+
+```astro
+<Callout type="tip" title="Ship it" icon="rocket">
+  Run `blume build` before you deploy.
+</Callout>
+```
+
+`type` sets the tint and the default icon: `note`, `info` (the default), `tip`, `success` (or `check`), `warning`, or `danger`. The aliases `caution`, `error`, `important`, and `warn` work only in the `:::` form. `title` adds a bold first line. `icon` replaces the type's icon and takes the same inputs as [`<Icon>`](#icon): a Lucide name, an image path or URL, or an inline SVG. `color`, any CSS color, replaces the type's tint: the border, the icon, and the body text take that color over the page background.
+
 ## Badge
 
 A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning.
@@ -225,7 +243,7 @@ Illustrate a project or folder layout. Wrap a normal Markdown list and Blume sty
 
 ## Accordion
 
-Stack related collapsibles in a single bordered container with dividers between them — FAQs, optional steps, or long examples. Each child is an `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). For a single standalone disclosure, use [Expandable](#expandable).
+Stack related collapsibles in a single bordered container with dividers between them — FAQs, optional steps, or long examples. Each child is an `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). The `title` renders inline Markdown, so code spans, emphasis, and links in it show as they would in a sentence; raw HTML in it shows as text. For a single standalone disclosure, use [Expandable](#expandable).
 
 <Accordion>
   <AccordionItem title="Does it support MDX?">
@@ -249,7 +267,7 @@ Stack related collapsibles in a single bordered container with dividers between
 
 ## Expandable
 
-A lightweight inline disclosure for nested detail — expanding a field's sub-properties or an optional aside. `title` labels the toggle (defaults to “Show more”); set `defaultOpen` to start expanded.
+A lightweight inline disclosure for nested detail — expanding a field's sub-properties or an optional aside. `title` labels the toggle (defaults to “Show more”) and renders inline Markdown, as an accordion item's does; set `defaultOpen` to start expanded.
 
 <Expandable title="Show advanced options">
   These settings are optional and rarely need changing.
@@ -295,7 +313,7 @@ Lay cards or blocks out in a responsive grid of equal columns that reflows on mo
 
 ## CodeGroup
 
-Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language), and the group's copy button sits in the tab bar and copies the block that is showing. Add `dropdown` to switch with a menu instead of a tab bar.
+Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language), or its language's name (`TypeScript`, `Python`) for a block without one, and the group's copy button sits in the tab bar and copies the block that is showing. Add `dropdown` to switch with a menu instead of a tab bar.
 
 <CodeGroup>
 
@@ -367,7 +385,7 @@ Wrap an image or any visual in a centered, bordered frame with an optional `capt
 
 ## YouTube
 
-Embed a YouTube video in a responsive, privacy-friendly (`youtube-nocookie.com`) 16:9 frame that ships no client JavaScript. Pass a video `id` or a full `url`, plus an optional `title` (for accessibility) and a `start` time in seconds.
+Embed a YouTube video in a responsive, privacy-friendly (`youtube-nocookie.com`) 16:9 frame that ships no client JavaScript. Pass a video `id` or a full `url`, plus an optional `title` (for accessibility) and a `start` time in seconds. A playlist `url` (`youtube.com/playlist?list=…` or `youtube.com/embed/videoseries?list=…`) embeds the whole playlist.
 
 <YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
 
@@ -468,7 +486,7 @@ A clickable preview that leads with a visual — an icon or image — above a ti
 
 ## Prompt
 
-A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard as Markdown, with its links, lists, and code intact, when the **Copy prompt** button is pressed. `actions` controls the buttons (e.g. `["copy", "cursor"]`).
+A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard as Markdown, with its links, lists, and code intact, when the **Copy prompt** button is pressed. Its punctuation copies as you typed it: straight quotes, `--`, and `...` stay as written, though prose elsewhere on the page shows them as curly quotes, dashes, and ellipses. `actions` controls the buttons (e.g. `["copy", "cursor"]`).
 
 <Prompt
   description="Ask the model to **document** an endpoint."
@@ -781,6 +799,8 @@ import CodeBlock from "blume/components/content/CodeBlock.astro";
 
 `title` sets the header label — a filename, say — which otherwise shows the language, and `icons={false}` hides the language's brand icon, as [`markdown.code.icons`](/docs/content/syntax#code-blocks) does for fences.
 
+Without `code`, `CodeBlock` renders its children as written, so a fenced block wrapped in `<CodeBlock>…</CodeBlock>` (the way Fern and Mintlify write code) shows as that fence. `title` and the other props don't apply to it then: give the fence its [title](/docs/content/syntax#code-blocks) after the language instead.
+
 To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:
 
 ```ts

package/docs/content/frontmatter.mdx

@@ -148,7 +148,7 @@ sidebar:
   display: page
 ```
 
-`hidden` removes the page from the sidebar and from previous/next pagination. On a folder's `index` page it removes only the page's own row: the group row keeps linking to the page, and previous/next links still pass through it.
+`hidden` removes the page from the sidebar and from previous/next pagination, and so from the sitemap, search, and `llms.txt` (see [Hidden pages](/docs/content/navigation#hidden-pages)). On a folder's `index` page it removes only the page's own row: the group row keeps linking to the page, so previous/next links still pass through it and the page stays in the sitemap, search, and `llms.txt`. On the home page, the root `index` page, it also removes only the row: the page stays in the sitemap, search, and `llms.txt`.
 
 `display` sets the render mode of the page's folder group ([per-group overrides](/docs/content/navigation#per-group-overrides)) and is only meaningful on a folder's `index` page under the generated sidebar — anywhere else (a non-index page, the content root's own `index` page, or any page under an explicit `navigation.sidebar`) it has no group to configure, and Blume warns with `BLUME_SIDEBAR_DISPLAY_IGNORED`.
 

package/docs/content/includes.mdx

@@ -23,7 +23,7 @@ Here it is live — this next callout is spliced from a shared snippet:
 
 ## Partials
 
-Any file whose name (or folder) starts with an underscore is excluded from routing, navigation, search, and sitemaps by default — that convention is the natural home for shared snippets:
+Any file whose name (or folder) starts with an underscore is excluded from routing, navigation, search, and sitemaps — that convention is the natural home for shared snippets. Patterns you add to [`content.exclude`](/docs/configuration#content) add to this rule rather than replacing it; to publish underscore files after all, add `"!**/_*"` to `exclude`:
 
 ```text
 docs/
@@ -37,7 +37,9 @@ docs/
 
 A partial is a normal Markdown or MDX file. Its front matter is stripped when spliced (the including page's front matter wins), and everything else — callouts, code fences, components, math — renders exactly as it would inline. Partials can include other partials; a circular include is reported as an error.
 
-Relative image references inside a partial keep working: they're rebased onto the including page, so a colocated `![diagram](./diagram.png)` next to the partial resolves wherever the partial is spliced.
+Link reference definitions (`[pep 508]: https://peps.python.org/pep-0508/`) cross includes too, so a partial can hold a site's shared link definitions: the page and its other partials can cite a partial's (`[PEP 508]`), and a partial can cite the page's. When the page and a partial both define a label, each uses its own.
+
+Relative image references inside a partial keep working: they're rebased onto the including page, so a colocated `![diagram](./diagram.png)` or `<Card img="./cover.png">` next to the partial resolves wherever the partial is spliced. An image's path is rebased in whatever form it's written: in angle brackets (`![diagram](<./my diagram.png>)`), with escaped parentheses, or followed by a title in any of its quotes. A link to another file next to the partial (`[spec](./spec.pdf)`, or an `<img src>` or `<a href>` naming one) moves with it too. A link to a page resolves from the including page, as if it were written there.
 
 Editing a partial while `blume dev` is running reloads every page that includes it.
 
@@ -77,6 +79,8 @@ Targets must live inside your content root: a file outside it would be silently
 
 Broken links inside a partial are reported against the partial file, not the pages that splice it, so you fix them where they live.
 
+A partial is read in the including page's format, so a `.md` partial that an `.mdx` page includes is read as MDX. MDX has no HTML comments, so the partial's `<!-- … -->` comments are spliced as MDX comments (`{/* … */}`) and stay hidden. Other HTML there has to be valid JSX: an `<img …>` or `<br>` without a closing slash takes in everything after it in the partial, with no error. Blume warns about it as `BLUME_MDX_UNCLOSED_ELEMENT` at the partial's line; close it as `<br />`. Anything else in the partial that MDX can't parse once it's spliced in, like a stray `{`, is a [`BLUME_MDX_SYNTAX`](/docs/content#markdown-and-mdx) warning at the partial's line, and when it fails the build, the build reports it there too, not at the page that includes it.
+
 :::note
 Partials are shared across locales and are not translated by `blume translate` — keep partials language-neutral (code, tables, diagrams), or create per-locale partials and include them from each locale's pages.
 :::

package/docs/content/index.mdx

@@ -16,6 +16,10 @@ Blume renders two kinds of file:
 
 Reach for `.md` when a page is just prose, and `.mdx` when it needs components or directives. Switching is as simple as renaming the file.
 
+In `.mdx`, `{` starts a JavaScript expression and `<` a JSX tag, so text that's fine in `.md` can break a page: a literal brace, an HTML comment (write `{/* … */}`), or an element left open (write `<br />`). Blume parses every `.mdx` page when it reads the project, so `blume dev`, `blume validate`, `blume doctor`, and `blume check` report one that doesn't parse as `BLUME_MDX_SYNTAX`, an error at the line and column where MDX stopped, and `blume build` stops there before it compiles anything. With `--no-strict`, the build leaves the page out and builds the rest of the site. `blume dev` keeps the page, and opening it shows the error.
+
+An expression can parse and still fail when the page renders, like `{user.name}` on a page where nothing defines `user`. `blume build` reports that as `BLUME_MDX_UNDEFINED_NAME` at the expression's line, in the page or in the [partial](/docs/content/includes) that holds it. To show braces as text, escape each opening brace (`\{`) or put the text in inline code. For a value every page shares, define a [variable](/docs/content/variables).
+
 ## Files and routes
 
 Each file maps to a route by its path under the content root:
@@ -40,7 +44,13 @@ Prefix a file or folder with a number and a `-`, `_`, or `.` to control its orde
 02-installation.mdx  ->  /installation
 ```
 
-A version or an ISO date at the start of a name is part of the name, not an order: `1.2.0.mdx` routes to `/1.2.0`, and `2024-01-05-launch.mdx` to `/2024-01-05-launch`. Only file and folder names lose a prefix (an Obsidian vault's notes count as files). A frontmatter `slug`, and a page from a [content source](/docs/content/sources) such as a CMS or GitHub Releases, keep the name they were given.
+A version or a date at the start of a name is part of the name, not an order: `1.2.0.mdx` routes to `/1.2.0`, and `2024-01-05-launch.mdx` to `/2024-01-05-launch`. Blume reads these as dates:
+
+- An ISO date, `YYYY-MM-DD`: `2024-01-05.mdx` routes to `/2024-01-05`.
+- A day or month first, then a four-digit year, `D-M-YYYY` or `M-D-YYYY` with one or two digits for the day and month: `12-05-2022.mdx` routes to `/12-05-2022`.
+- A year and a month, `YYYY-MM`: `2024-01.mdx` routes to `/2024-01`.
+
+A date ends the name or is followed by a `-`, `_`, or `.`, like the rest of a name (`2024-01-recap.mdx`). Earlier Blume versions read the first number of the last two forms as an ordering prefix, so `12-05-2022.mdx` published at `/05-2022` and `2024-01.mdx` at `/01`. Those old URLs now redirect to the new ones, unless another page lives there. Only file and folder names lose a prefix (an Obsidian vault's notes count as files). A frontmatter `slug`, and a page from a [content source](/docs/content/sources) such as a CMS or GitHub Releases, keep the name they were given.
 
 Ordering has several layers — see [Navigation](/docs/content/navigation) for the full precedence rules.
 

package/docs/content/islands.mdx

@@ -28,6 +28,8 @@ The filename is the component name, so it **must be a PascalCase identifier**
 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.
 :::
 
+An island is the only way to run code in the browser from a page. A JavaScript event handler on a plain HTML element in MDX, like `<button onClick={() => open()}>`, never runs: the page is static HTML, so the function is written into the attribute as text. Blume warns about one as `BLUME_MDX_EVENT_HANDLER` at its line. Move that markup into an island and use the island in the page.
+
 ## Registering islands in `components.ts`
 
 If you'd rather keep islands next to the rest of your components — or give them a different name than the file — register them with `defineComponents` as an `mdx` entry with a `client` mode. That's all an island is: an MDX component that hydrates. Each entry is available in every MDX page, and an entry with the same name as an `islands/` file replaces it.