--- changelog: category: Release version: blume@2.0.2 date: '2026-09-25T03:12:19Z' seo: description: >- Only a reader opening an or writes its id to the URL hash. A defaultOpen item on the page a client-side navigation lands on no… title: blume@2.0.2 type: changelog --- ## Patch Changes - e80b141: Only a reader opening an `` or `` writes its id to the URL hash. A `defaultOpen` item on the page a client-side navigation lands on no longer replaces the hash the reader arrived with. - 4f9d1bf: `llms.txt`, `agent-readability.json`, the API and AI catalogs, and the `_headers` and `vercel.json` rules now list the agent skills index only when the build published a skill, and the MCP server only when it was generated, rather than whenever `agents.skills` or `agents.mcp` is set. The API catalog is now served as `application/linkset+json` with the RFC 9727 `profile` parameter, in its `Content-Type` and in the homepage `Link` header. - 4f9d1bf: Root-relative links in the agent Markdown (`.md` and `.mdx` mirrors, `llms-full.txt`, MCP `get_page`) now match the rendered page: `[Install](/guides/install)` and `` gain the site's `deployment.base` and `basePath`, and on a translated page they point at that locale's copy of the page when it exists. A paragraph written straight after a converted ``, ``, or `` now stays its own paragraph instead of joining the quote or list, and `` markup inside inline code or an indented code block (in a tab or step) is left as written. - a70a0f1: GraphQL references build from schemas that use directives they don't declare, such as Apollo Federation subgraphs (`@key`, `@link`) and AppSync schemas (`@aws_*`); syntax errors and unknown types still fail the build. A custom scalar's `@specifiedBy` URL is a link only when it's a safe web address, so a `javascript:` URL from a remote schema shows as text. OpenAPI overview pages list tag sections in the order the spec's `tags` declares them, code spans in description lines that start with HTML keep their braces, and the build warns that OpenAPI 3.1 `webhooks` aren't rendered instead of dropping them silently. - f2ebe6f: `blume init --template api` now writes a small example spec, `openapi.json`, beside `blume.config.ts` and points `openapi()` at it, so a new project's first build no longer depends on the public Petstore server. Its operation pages carry descriptions that a fresh `blume audit` accepts. - 591c39e: The assistant shows its error message when an answer comes back empty, which is how a provider failure after the response starts (a bad key, a rate limit, an unknown model) arrives, instead of leaving a pulsing placeholder that never resolves. `useAssistant` from `blume/hooks` does the same. - 4f9d1bf: On a versioned site, the assistant now grounds its answers in the docs version the reader is viewing, the current docs unless they're on an archived page, instead of retrieving from every archived copy of each page. - 0befec9: `blume audit` passes on Blume's own output for multilingual and versioned sites. The hreflang checks and the non-canonical page check skip i18n fallback copies, which canonicalize to the page they copy on purpose; the hreflang checks also accept archived pages that canonicalize to the latest docs, and match non-ASCII slugs. The sitemap and llms.txt checks no longer flag pages those files leave out on purpose: fallback copies, archived pages that canonicalize elsewhere, and pages with `ai: { exclude: true }`, which the llms.txt fix now names. A sitemap index, which Blume writes past 50,000 URLs, is read through its child sitemaps, and the size limits apply to each file. Other checks no longer report what the config asked for. Noindex pages aren't asked for a canonical, robots.txt isn't expected to name a sitemap when `seo.sitemap` is off or to be reachable when `seo.robots` is off, `/_vercel/image` URLs aren't reported as broken images, and a locale prefix such as `pt-BR` doesn't count as an uppercase URL. - 0befec9: The `blume audit` report labels each check with the number of distinct pages it affects and previews each page once, while `--verbose` still lists every finding. A check's glyph follows its findings' actual severity, so an external link downgraded to a warning no longer shows as an error. Each distinct fix in a group is printed, and length findings on pages generated from an API spec point at the spec's summary or description instead of front matter. On a site with `deployment.base`, links, assets, and `og:image` URLs that leave out the base are reported, since the deployed site doesn't serve them. `blume audit --url` rejects a value with no scheme, such as `example.com`, with a message suggesting the `https://` form instead of failing with an internal error. - e80b141: `` shows the right type for properties inherited from an interface in another file (`interface Props extends Base`, with `Base` imported). Those rows read their type from the file that declares them, where they used to show a slice of unrelated text from the documented file. - e80b141: A `` with a `variant` it doesn't recognize, such as `info`, renders as the default gray badge instead of failing the page build. - 591c39e: The banner's link is written as if the site were mounted at root, like a featured link: with `basePath` set it lands under the base, and on a multi-locale site it points at the reader's locale when that locale serves the page. A link to a route served outside the docs (a custom page, the generated changelog) keeps its own path. A `` entry's `typeDescriptionLink` gets the base too. - 351d6ab: `blume build` reports a page Astro can't compile or render (MDX that doesn't parse, say) as a `BLUME_BUILD_FAILED` error at that file and position, instead of an internal error asking you to report a Blume bug. After a `vercel()` or `netlify()` server build, `blume preview` explains that the adapter has no local preview server and suggests `blume dev` or the host's preview deploy, and in an ejected app `blume check`, `blume sync`, and `blume preview` now stop like `dev` and `build` do, naming the app's own command to run instead. - 3b5e90a: A `notion()` source saves a downloaded asset only when the server reports an image or video type, or when the response names no type and the URL has an image or video extension. An "image" that links to an HTML page keeps its original URL with a warning instead of being served as a page from `/blume-assets/`, and an image whose caption holds a bracket or whose URL holds spaces or parentheses is now downloaded too, instead of keeping a signed Notion URL that expires. `/blume-assets/` publishes only the images and videos a source downloaded, so a file an earlier build saved under another extension is no longer served, and a downloaded video carries its video type in dev. - 3b5e90a: Content imported from a CMS or GitHub releases can no longer run script on the docs site. A Sanity code span keeps its text as code however many backticks or braces it holds, and a `javascript:` link keeps only its label wherever it comes from: a Sanity link, a scheme hidden behind an escape (`javascript:`, `javascript:`), a release note's footnote, or a Contentful, Payload, or Strapi Markdown field. A link's URL can't close it early to start a second link, a code block whose language holds a backtick still opens its fence, and an unsupported block's type can't end its comment. Lowered rich text also keeps `## text`, indented text, and an `import` followed by code in the next run as prose, instead of rendering a heading or code block or failing the MDX page. - 3b5e90a: Sanity bold and italic spans keep their edge spaces outside the markers, so `Hello ` in bold before `world` renders as bold text instead of literal asterisks, and nested list items indent to their parent item's text, so an item under a numbered one nests instead of joining the parent's line. Notion video captions show `<` and `>` as typed rather than as `<` and `>`, and a rate-limited Notion request waits for the `Retry-After` the API sends. - f2ebe6f: A config error now points at the line that holds the problem: an invalid `redirects[2].status` at the third redirect rather than the first, and a missing key such as `github.repo` or `i18n.locales[1].label` at its parent object or array entry rather than at a same-named key later in the file, so issues also list in the order they appear. A `blume.config.ts` without a default export (a bare `defineConfig({ … })` call, `export const config`, or `export default null`) now fails with one diagnostic naming the file and the missing `export default`, where it used to build a default site or fail with an unrelated error. The `defineConfig` hover docs no longer list `markdown.math` or inline-highlighting options the config doesn't accept. - f2ebe6f: Config paths and URLs are checked up front. `deployment.site` must be an absolute `http://` or `https://` URL, so `localhost:4321`, `mailto:`, and `javascript:` values fail with a hint instead of prefixing every sitemap entry and canonical link. Redirects need a leading slash on `from` and on a relative `to`, since a path without one never gained the base path. `basePath` rejects a full URL, query, or fragment. A navigation tab's `path` is normalized to one leading slash and no trailing slash, so `/guides/` marks its tab and scopes the sidebar, and `api` links to `/api`. - 5f5c72a: With `basePath: "/docs"`, a content folder named `docs/` now publishes beneath the base (`docs/guide.md` at `/docs/docs/guide`) instead of colliding with the root pages. Folder `meta.ts` discovery now honors the content source's `include` and `exclude` globs, so an unrelated `src/lib/meta.ts` in a `.`-rooted project is no longer imported, and meta in a lowercase locale folder (`pt-br/`) now applies to its configured locale (`pt-BR`). - abb982a: Only file and folder names lose an ordering prefix (`01-intro.mdx` → `/intro`, and an Obsidian note `01 Intro` → `/intro`). A frontmatter `slug`, a GitHub release tag, and a CMS slug keep their leading numbers, so releases `1.0.0` and `2.0.0` publish at `/changelog/1-0-0` and `/changelog/2-0-0` instead of colliding on `/changelog/0-0`. A version (`1.2.0.md`) or an ISO date (`2024-01-05-first-post.md`) is part of a name rather than an order, which also stops posts from the same year raising a duplicate sidebar order warning. A source `prefix` written with slashes (`sanity({ prefix: "/guides" })`) now names the source `guides`, so its pages no longer 404 and its asset URLs no longer carry a double slash. - abb982a: Remote sources keep one snapshot per preview mode and set of options under `.blume/cache//`. A plain `blume dev` after `blume dev --preview` no longer serves unpublished drafts, a build whose fetch fails no longer falls back to them, `--preview` fetches drafts even when a published snapshot is cached, and editing a source's `query` or `fields` refetches in dev. Contentful's `--preview` without a Preview API token now fails with a clear error instead of serving the cached snapshot with a warning, and a source passed to `custom()` from one of Blume's engine factories (`sanitySource`, `contentfulSource`, …) now honors `--preview` and caches in the runtime directory like the built-in adapter. - a6401cf: Add a `databuddy()` analytics adapter. It renders Databuddy's tracker tag with `clientId` as `data-client-id` and forwards any other option as a `data-` attribute, and page feedback events reach `window.databuddy.track`. - f2ebe6f: A `dateFormat` that sets only `timeZone`, `calendar`, or `numberingSystem` keeps the long date form (`July 21, 2026`) instead of falling back to a bare numeric date (`7/21/2026`). Setting `dateStyle` or a component field such as `year` still picks the shape. - 8d88600: `blume eject` now adds `tailwindcss` and `@tailwindcss/typography` to the project's dependencies, so the ejected stylesheets resolve under pnpm and other strict linkers, and the ejected `features.ts` names `epub-gen-memory` only when EPUB export is on. The ejected app also serves colocated images from its raw Markdown at `/blume-assets/content/…`, and renders the Open Graph card its `/changelog` page points at. With `playground: { proxy: true }` on a reference, the ejected app serves the API playground's built-in proxy at `{basePath}/_api-proxy`, with the same origin allowlist, instead of every Send returning a 404. - 5f5c72a: English pages (`en`, `en-GB`, and other `en-*` codes) on a site whose default locale isn't English now show Blume's built-in English interface strings, plus their own `i18n.ui` overrides, instead of the default locale's translation. - 351d6ab: Blume no longer takes `NODE_ENV` from `.env` files, so a monorepo root `.env` that sets it for another app can't turn `blume build` into a development build or `blume dev` into a production one. Set it in the shell when you need to. - 0befec9: A `severity: warning` question in `blume eval` now warns instead of failing CI, as documented: its miss doesn't count against the gate or `--threshold`, so the exit code agrees with the JSON summary's error count. When an agent CLI exits before reading its prompt, `blume eval` and `blume translate` report the agent's exit code and stderr for that item instead of aborting the whole run with an internal error. - aa325a8: A header tab's `icon` now shows beside its label in the header, on a dropdown tab, and in the mobile navigation drawer. Before, `navigation.tabs[].icon` was accepted but never rendered. - aa325a8: On a multilingual site, a sidebar group with no `meta.ts` in a locale now mirrors the fallback locale's: that folder's `meta.ts` (title, order, `collapsed`, `display`) and the `sidebar.display` its index page sets. Groups set to collapsible no longer render flat on pages that fall back to the default language. - 351d6ab: `blume init` inside a pnpm workspace that doesn't list the new folder under `packages` now skips the install (pnpm would exit without installing Blume) and tells you to add the folder, instead of saying the project joined the workspace. The `cd` line in its next steps is quoted when the directory needs it (`cd "my docs"`), and when `init --eject` can't eject after an install that ran, it reports the actual error rather than blaming missing dependencies. - aa325a8: A `` caption and a `` description keep code spans (`` `Array` ``) and autolinks (``) intact, while raw HTML in them still shows as text. Before, their `<` and `>` rendered as `<`/`>` in code and as stray brackets around links. - 5f5c72a: Links now resolve the same way in the built site and in `blume validate`: relative links on a page named `Index.md` resolve beside it, as its `/…/Index` route does, and links to dotted page routes such as `/releases/v1.2` move into the reader's locale and under `basePath`, in content and in component `href`s alike; only a link no page is served at counts as a public asset. `blume version` also rewrites unprefixed links (`/guides/setup`) into the snapshot when the default locale keeps its URL prefix, and for pages that exist only in another locale. - 591c39e: More of the reader-facing chrome follows the page's language: the `` column and row labels, ``'s Preview and Code tabs, untitled `` panels and the tab picker, ``'s default toggle, ``'s default heading, ``'s count labels, the search dialog's "latest" version tag, and the header on API reference pages. Each has a new `i18n.ui` key with a translation in every built-in locale. In right-to-left locales the sidebar's indents and badges, the assistant's close button, and the arrows on cards, tiles, and the banner link now mirror. - 65edd91: With a `basePath`, the `_headers` and `vercel.json` rules that pin `charset=utf-8` on raw Markdown now cover every mirror, not only those under `basePath`: the section home's `/.md` and the generated `/index.md`, `/changelog.md`, and `/404.md` went out without a charset, so browsers showed their non-ASCII text as mojibake. - 4f9d1bf: The MCP endpoint now reads a request body only up to 64 KB and answers anything larger with `413`. A call to a tool that doesn't exist, or with `arguments` that aren't an object, now gets the JSON-RPC Invalid params error (`-32602`) with a short message. The `/mcp` operation in `openapi.json` now lists `text/event-stream` beside `application/json`, so a generated client sends the `Accept` header the endpoint requires. - 5f5c72a: Header and sidebar links now land where they should across versions, locales, and base paths: - On an archived version's pages, a tab links into that version's section (`/v1.0/guides/…`) instead of the current docs' path, which 404ed when the section had no index page. - On a non-default locale, a `/changelog` tab opens the changelog timeline instead of the newest entry, and a tab whose path is a custom page opens that page. - With a `basePath`, the logo in a non-default locale links inside the base (`/docs/fr`) instead of to `/fr`. - Internal `href` links in an explicit `navigation.sidebar` move into the reader's locale, as featured links do. - An explicit `navigation.sidebar` item that can't render as written now reports a warning: a route that matches no page, a `root` that matches no page, or an item with no route, `href`, `root`, or `items`. - A featured or header link with a query or fragment (`/guides?tab=cli`) is no longer reported as `BLUME_NAV_MISSING_PAGE` when its page exists. - aa325a8: A `netlify()` server build now serves the header rules a static build puts in `_headers` — the homepage `Link` header, `charset=utf-8` on the raw Markdown and text files, and the `.well-known` discovery files' media types and CORS header — by writing them into Netlify's `.netlify/v1/config.json`, which a server build reads instead of `_headers`. - 8d88600: The default 404 page now switches to the reader's locale under a `deployment.base` or `basePath` too, and its localized home link includes the `basePath`. `` preview frames now follow the OS color scheme when browser storage is blocked, instead of rendering without a theme. - abb982a: Broken-link diagnostics in an Obsidian vault note now name the line in the note itself, rather than a line counted from the frontmatter Blume rewrites when it drops Obsidian-only properties. - f2ebe6f: Open Graph cards for non-Latin locales now render their text instead of empty boxes. Each configured locale whose script the card's built-in font can't draw adds a Google Noto fallback for it (`Noto Sans JP` for `ja`, `Noto Sans Devanagari` for `hi`, `Noto Sans` for Cyrillic, Greek, and accented Latin, and so on), with no config needed. Latin text keeps the built-in font, so English cards look the same, and an explicit `seo.og.fonts` still replaces the whole list. - a70a0f1: API reference samples now use the examples an OpenAPI 3.0 or Swagger 2.0 spec declares on parameters, request bodies, and responses, which the 3.1 upgrade had moved out of reach, so a path parameter with `example: "pet_123"` renders `/pets/pet_123` instead of `/pets/string`. Response examples keep `readOnly` fields and leave out `writeOnly` ones, and the curl, JavaScript, and Python samples quote header values, URLs, and bodies for their language, so an `If-Match: "33a64df5"` header or a `$` in a token comes through intact. Schema rows label a nullable `$ref` as `Pet | null` rather than `Pet | any`, and a type array like `["string", "integer"]` as `string | integer`. - a70a0f1: API reference schema tables stay a manageable size for specs whose schemas reference each other densely. A named schema expands wherever it appears in the first two levels of nesting, as before, and below that only where it first appears; later mentions show its name. A request body of twelve schemas that each reference four others went from tens of thousands of nested tables to a few dozen at most. - a70a0f1: API reference code samples, the Try it panel, and the AsyncAPI composer fill server `{variables}` with their declared defaults, so `https://{region}.api.example.com` becomes a real URL, and the built-in playground proxy allows the resulting origin instead of refusing it with a 403. An operation's own `servers`, or its path's, now replace the document's servers in its samples and panel, and the proxy allows those origins too. - 5f5c72a: A heading inside a multi-line HTML (``) or MDX (`{/* … */}`) comment no longer becomes the page title, a table of contents entry, or a link anchor. Titles derived from file names spell acronyms the way sidebar groups do (`faq.md` is "FAQ"), and an untitled folder `index` page takes its folder's label instead of "Index". A root file named like a version (`v3-migration.md`) no longer triggers the unconfigured-version warning, and the missing content root hint now names the `filesystem()` source's `root` for projects that list `content.sources`. - 8d88600: The API playground's built-in proxy (`playground: { proxy: true }`) now works under a `basePath` or a `deployment.base`: the endpoint mounts under `basePath` at `{basePath}/_api-proxy`, and the Send button targets it with the deployment base included. - a70a0f1: The Try it panel no longer blocks Send on valid request bodies: it doesn't ask for `readOnly` properties the spec marks required, accepts `null` in nullable fields, and doesn't check one type of a field that allows several. The panel also works when the browser blocks storage (Safari's "Block All Cookies", sandboxed iframes), where it now simply doesn't remember credentials, and the AsyncAPI composer closes its WebSocket when a client-side navigation leaves the page. The request and response tabs move with the arrow keys, Home, and End, and the reference's spacing follows right-to-left layouts. - 0befec9: The `posthog()` analytics adapter only sends its own `$pageview` on client-router navigations while PostHog captures page loads alone. With `capture_pageview: "history_change"` or a `defaults` date such as `"2025-05-24"`, PostHog tracks navigations itself and each one is no longer counted twice, and `capture_pageview: false` now means no pageviews at all. - 591c39e: Export → PDF (and any print of a page) keeps callouts, panels, and changelog update headings. The print stylesheet now hides only the site chrome (banner, header, sidebar, table of contents, assistant panel) instead of every `
` and `