--- changelog: category: Release version: blume@2.0.3 date: '2026-09-25T05:25:16Z' seo: description: >- Operation links in the agent-facing Markdown of an API reference overview (/.md, llms-full.txt, and MCP get_page) now include deployment.base. With a… title: blume@2.0.3 type: changelog --- ## Patch Changes - 090211e: Operation links in the agent-facing Markdown of an API reference overview (`/.md`, `llms-full.txt`, and MCP `get_page`) now include `deployment.base`. With a base of `/sub`, they used to point at `/api/pets/list-pets`, which 404s. In `llms.txt`, page and feed titles with square brackets (`[Beta] Webhooks`) are escaped, so their lines stay links. - ad20661: With `deployment.base` set, root-relative images and file links in the agent-facing Markdown (`/.md`, `llms-full.txt`, and MCP `get_page`) now gain the base the way the rendered page's do: `![logo](/logo.png)` becomes `/sub/logo.png` and `[spec](/spec.pdf)` becomes `/sub/spec.pdf`. They used to keep the bare root path, which 404s on a subpath deploy. - be607f9: A file path longer than 100 bytes inside a published agent skill no longer fails `blume build`: the skill's `.tar.gz` stores it in the ustar `prefix` field up to 255 bytes and in a PAX extended header beyond that, so standard `tar` readers unpack it at its full path. Two skill directories that declare the same `name` now publish one index entry, from the directory that sorts first, with a build warning naming both, instead of two entries for one artifact whose digest could not match what was served. - 090211e: A schema with both properties and a `oneOf`/`anyOf` now shows its shared properties above the variants. Before, `{ properties: { amount, currency }, oneOf: [Card, BankAccount] }` showed only "One of Card | BankAccount". An OpenAPI spec whose `operationId`, tag, summary, or description YAML reads as a number (`operationId: 404`, `tags: [2024]`) now loads, using the number as text, where it used to fail with "text.normalize is not a function". The request and response tabs' Left and Right arrow keys follow the reading direction on right-to-left pages, as `` does. - 4f7785c: An OpenAPI, AsyncAPI, or GraphQL description that ends inside an unclosed code fence no longer swallows the reference UI rendered after it. The fence used to run to the end of the page, so an operation page lost its parameters, responses, and playground, and an overview page lost its operation lists. Blume now closes the fence where the description ends. - af7c4c9: ArkType schemas now work in `frontmatter.extend` and `content.types..frontmatter`. ArkType types are callable functions, and Blume only accepted Standard Schemas that were plain objects, so config validation rejected them. - 08219a2: Closing the assistant panel mid-answer now stops the model call. The generated assistant route passes the request's abort signal to the model, which used to keep generating, and billing, the rest of the answer after the reader left. - 6933892: With the assistant panel docked open on desktop, moving to another page keeps the page laid out beside the panel. Each navigation used to replay the page's slide to make room for the panel. - 090211e: AsyncAPI operations whose bindings are a `$ref` to `#/components/*Bindings` now resolve it. Before, the protocol read as "$ref", so a WebSocket operation got no samples and the composer said "Live sending isn't possible for $ref". Channel parameters are URL-encoded only for URL-based protocols (WebSocket, HTTP), so a Kafka or MQTT topic reads `sensors/sensor 1` rather than `sensors/sensor%201`. The message composer no longer hangs on "Connecting…" when the browser refuses a malformed WebSocket URL: it shows the error and lets you connect again. - b6992c0: `blume audit` no longer counts an inline SVG's `` as a page title, so an accessible icon doesn't raise `BLUME_AUDIT_TITLE_MULTIPLE` (an error) or stand in for a missing head `<title>`. Text-fragment links (`#:~:text=…`) aren't reported as broken anchors, and only the id in front of a fragment's `:~:` has to exist. An i18n fallback copy of a page is no longer reported as an orphan, which failed `--strict`. A failing audit now delivers its whole report through a pipe; it used to exit before a long report finished writing, cutting the CI log off partway. - 6933892: `<Badge variant="accent">` now uses your theme accent, as documented, instead of a fixed blue. Its label mixes the accent toward the text color, so it stays readable over the accent tint in light and dark mode. - ad20661: A header link, featured link, or other configured link that already carries `deployment.base` followed by a fragment or query, like `/sub#install` under `base: "/sub"`, is no longer prefixed a second time. It used to render as `/sub/sub#install`. - 3311cee: A link that already carries `basePath` followed by a fragment or query, like `[Install](/docs#install)` under `basePath: "/docs"`, is no longer prefixed a second time. It used to render as `/docs/docs#install`, a 404 the link checker didn't catch. - f373654: A page whose body starts with a `---` horizontal rule, right below its front matter, no longer loses everything up to the next `---` line. The renderer read that stretch as a second front matter block and dropped it; both rules and the text between them now render, in `.md` and `.mdx` pages alike. Headings in that stretch are now anchors `blume validate` accepts and title an untitled page, the same as any other heading. - 7258f30: `blume translate`, `blume validate`, and `blume doctor` now let their whole report reach a piped stderr before exiting with a failure. Before, they exited immediately after writing, so a long list of findings could be cut off in CI logs and `| tee` output — the same fix `blume audit` and `blume eval` got. - 3311cee: A `cloudflare()` server build with a `base` now writes its `_headers` rules into `dist/client/_headers`, where Cloudflare reads them, next to the adapter's own. They used to land in `dist/client/<base>/_headers`, which Cloudflare never reads and served publicly, so the Markdown and text charset, the discovery files' media types and CORS header, and the agent skills media types were dropped. The Markdown and JSON 404 answers are wired up under a base too, and a `base` written without a leading slash (`cloudflare({ base: "docs" })`) no longer stops `Accept: text/markdown` negotiation from running. - f373654: Rich text from a CMS source (Notion, Contentful, Sanity, Strapi, Payload) renders neighboring runs with the same formatting as one: two bold runs side by side used to show `****` between them, and two italic runs `**`. Neighboring runs under the same link in Notion and Sanity now form one link. A bare URL containing `_`, `~`, or `*` stays a working link instead of gaining backslashes in its address, and struck-through text in a Contentful table cell no longer shows `~~~~`. - 4f7785c: Rich text from a CMS source (Notion, Contentful, Sanity, Strapi, Payload) renders more faithfully. A `^` no longer turns text like "2^10 and 2^20" into superscript, `$$` no longer starts math, and a colon before a word (`10:30`, `pets:read`) stays text. Two struck-through runs side by side now render as one strikethrough instead of showing `~~~~`, and a heading that ends in " #" keeps its `#`. A Notion page with no Slug property is now routed by its whole title, with slashes turned into hyphens: "CI/CD Setup" publishes at `ci-cd-setup` instead of at `cd-setup` in an invented `ci` group. A Slug property still sets a nested path. A Notion video URL that contains a double quote or a backslash no longer breaks the page. - af7c4c9: An unknown `dateFormat.timeZone` (`Asia/Tokio`) is now a config error that points at the key, instead of a `RangeError` thrown later while rendering a page's "last updated" date or the changelog. - af7c4c9: Blume now warns when a content folder is named after the default locale (`docs/en/` with `defaultLocale: "en"`). The default locale's pages live at the content root, so such a folder is ordinary content that publishes at `/en/…` (`/en/en/…` when the default locale keeps its prefix, and `/fr/en/…` as fallbacks); before, it did so silently. - 08219a2: The homepage `Link` header `blume dev` sends now lists only what the dev server serves: the JSON API's OpenAPI description and the homepage's Markdown mirror. It used to also advertise `/llms.txt`, `/agent-readability.json`, and the API and AI catalogs, which `blume build` writes and the dev server answered with 404s. Built and deployed sites send the same header as before. - b6992c0: Two `blume dev` servers started at the same moment in one project no longer both get the `.blume` lock. The lock file now appears with its content already written, a lock that's still being written is waited on instead of being read as stale, and a stale lock left by a stopped server is cleared by one process at a time, so a starting server can't delete the lock another one claimed a moment earlier. - 1b83039: `blume dev` now shows a body edit to a `.md` page on sites whose content pages render in Astro's `prerender` environment, such as sites deployed with `cloudflare()`. Astro refreshes its content store in the `ssr` environment only, so the page kept rendering its old body until something structural changed or the dev server restarted. - 08219a2: `blume dev` now refreshes Blume's generated data in every Vite environment, not only the ones Vite's legacy module graph covers. On sites whose content pages render in Astro's `prerender` environment, such as sites deployed with `cloudflare()`, a page added while the dev server runs now opens instead of 404ing, sidebar label edits show up, `.md` mirrors follow body edits, and an edit to an included partial reaches the pages that include it. Until now they all kept their startup state until the dev server restarted. - 08219a2: The first search in a fresh `blume dev` session no longer reloads the page. The configured search adapter's browser library (`@orama/orama` for the default search, or the FlexSearch, Algolia, Orama Cloud, or Typesense client) is now pre-bundled when the dev server starts. It used to be discovered only when the search dialog first opened, which re-optimized dependencies and reloaded the page. - be9d98e: `blume dev` reloads on edits under a nested folder that shares a name with an excluded one. With `exclude: ["drafts/**"]`, which leaves out `drafts/` at the content root only, the watcher used to ignore every folder named `drafts`, so edits to pages in `guides/drafts/` never showed up until a restart. - be9d98e: `blume eject` now writes the JSON docs API (`/api/docs/…` and `/openapi.json`) into the ejected app, which its `llms.txt`, homepage `Link` header, and not-found page already pointed to, so those links no longer 404. The ejected `src/generated/includes.json` now lists partials and their pages relative to the project instead of as absolute paths from the machine that ran eject, so editing a partial still refreshes the pages that include it in any checkout. - 1b83039: `blume eject` now writes the not-found page's Markdown and JSON twins (`/404.md` and `/404.json`) beside its `404.astro`, so the ejected app answers the same missing-page URLs as the hidden runtime. Like the page itself, they're left out when the project already owns `/404` with a `pages/404.astro` or a `404.md` content page. - 1b83039: A failing `blume eval` now delivers its whole report through a pipe before exiting non-zero. It used to exit as soon as it wrote the summary, so a long `--verbose` report was cut off partway in CI logs. - b6992c0: `blume eval --threshold` rejects an empty value, which it used to read as `0`, so `--threshold "$EVAL_THRESHOLD"` with the variable unset switched the gate off. An absolute `--file` path is used as given instead of being nested under the project root, for runs and for `blume eval init`, whose "already exists" check missed it. `--timeout` on `blume eval` and `blume translate` refuses values above 2147483 seconds (about 24 days), which used to make every agent time out at once. Durations in their reports round before they split into minutes, so a run prints `2m 0s` rather than `1m 60s`, and `1m 0s` rather than `60.0s`. - af7c4c9: Front matter that opens with a blank line after its `---` fence is now read as front matter, the way Astro reads it. Blume used to treat that `---` as a divider, so the page's `draft`, `slug`, and `hidden` were ignored while Astro stripped the block, and its YAML leaked into search and `llms.txt`. A block that holds no key–value pairs now reads as empty front matter, again matching Astro. - ad20661: Every URL Blume generates for a page now puts `deployment.base` in front, even when the page's route starts with the same segment. With `base: "/guides"`, a page at `guides/setup.md` is served at `/guides/guides/setup`, but its canonical URL, sidebar and tab links, breadcrumbs, previous/next links, search results, JSON-LD, `llms.txt` and `llms-full.txt` entries, JSON API and MCP URLs, and relative links to it (`./setup`) all pointed at `/guides/setup`. They now point where the page is served. A root-relative link you write that already starts with the base is still left as written. The language switcher's links to locales a page has no translation for get the same fix for `basePath`. - be9d98e: With `lastModified: "git"`, a project opened through a symlink (such as `/tmp` on macOS, which links to `/private/tmp`) now gets its "Last updated" dates. Blume compared the project's path against the one git reports with the link resolved, so it treated every content folder as outside the repository and dated no page, without a warning. - af7c4c9: Heading anchors and titles now come from a heading's rendered text rather than its Markdown source, so they match the ids on the page. `## See [the docs](/x)` anchors as `#see-the-docs` (not `#see-the-docsx`), `## An _important_ note` as `#an-important-note`, and entities, code spans, inline HTML, images, reference links, footnote references (`## Setup[^note]` → `#setup1`, numbered in the page's footnote order), and smart punctuation (`A -- B` → `#a--b`) read the way the renderer reads them. `blume validate` no longer reports a correct link to such a heading as a broken anchor, `blume translate` pins the id the page actually has, Obsidian heading links land on the section, and a page without a frontmatter `title` is titled "Using Astro with Blume" instead of the raw "Using [Astro](https://astro.build) with **Blume**". - 6933892: `usePage()` and `useBlume()` now return the page being viewed after a client-side navigation. They used to keep answering with the first page's route, title, and navigation for the rest of the visit, so an island on a page reached by a link, or after switching language, read the wrong page. An island kept across navigations with `transition:persist` now updates too. - 4f7785c: Text in an `.mdx` page that reads as an inline or leaf directive now renders exactly as written. A colon followed by a letter or digit, as in `16:9`, `10:30am`, `og:image`, or `pets:read`, used to drop everything from the colon to the end of the word ("16:9 frame" rendered as "16 frame"), and a `::name[label]{attrs}` line vanished. This also covers headings and their anchors, callout titles and bodies, and API reference descriptions. `:::` callouts work as before, and `.md` pages were never affected. - be9d98e: `mdxRemote()` pages lose their file and folder names' ordering prefixes the way a local content folder's do: `01-getting-started/02-install.mdx` now routes to `/sdk/getting-started/install` instead of `/sdk/01-getting-started/02-install`, while the prefixes still order the sidebar. - f373654: A `:::` block in an `.mdx` page whose name isn't a callout type, like a `:::details` carried over from another docs tool or a typo like `:::warnig`, no longer disappears along with everything inside it. Its content now renders between its `:::` lines, which stay on the page as written, and `blume dev`, `blume build`, and `blume check` warn with `BLUME_UNKNOWN_DIRECTIVE`, naming the callout types. A callout nested inside another (a `::::note` around a `:::tip`) now renders instead of vanishing. Site search now indexes text like `16:9` and `og:image` as the page shows it, instead of as "16" and "og". - be607f9: The `blume-migrate` skill's Mintlify codemod removes a dropped front matter key's list items even when they're written flush at column 0 (`keywords:` then `- one`), instead of leaving them behind as front matter that no longer parses. Its Fumadocs and Nextra guides now map locale file suffixes (`page.cn.mdx`, `index.en.mdx`) to `i18n.parser: "dot"` as-is rather than restructuring them into locale folders. - 3e95f16: OG cards render every script by default. A Noto fallback for each script is now part of the default card font stack, not only for configured locales, so a Japanese, Hindi, or Arabic title renders instead of tofu on any site, including sites with no `i18n` block and ejected projects. A card fetches from Google Fonts only when its text has a glyph the built-in font can't draw, and then only the families and subsets those glyphs need, so English cards fetch nothing and Latin-only sites still build offline. Configured locales move their family to the front, so a `zh` site draws Han in Chinese forms. - 3cd8149: Add a `oneDollarStats()` analytics adapter. It renders the OneDollarStats tracker tag, needs no key, and forwards every option as a `data-` attribute (`hostname`, `devmode`, …). `hostname` must be a bare host name, and `"hash-routing": "false"` leaves the attribute off, since the tracker turns hash routing on whenever it's present. Blume's custom events (page feedback and Ask AI) reach `window.stonks.event` with their property values as strings. - 090211e: The API playground's built-in proxy (`playground: { proxy: true }`) now forwards only the headers the Try it panel sets itself: the credentials and header parameters filled in, and the body's `Content-Type`. It used to forward every request header except a handful, so credentials the browser or the host attached on their own reached the documented API: HTTP Basic credentials for a password-protected docs site, a Cloudflare Access `cf-access-jwt-assertion`, Vercel's `x-vercel-oidc-token`, and `X-Forwarded-For`/`X-Real-IP`. Platform headers are never forwarded, even when a spec declares a header parameter with the same name. - 1b83039: A `trace` operation's Try it panel now says that browsers can't send `TRACE` requests when you press Send, instead of blaming CORS or an unreachable API: `fetch` refuses the method before anything goes out. Its JavaScript sample, which is built on `fetch`, is now a note saying so rather than code that could only throw. The cURL and Python samples still send it. - 090211e: The Try it panel and the code samples now send requests the way the spec describes them. Array and object parameters follow their `style` and `explode`, with OpenAPI's defaults when the spec sets none: `tags: ["dog", "cat"]` becomes `?tags=dog&tags=cat` rather than a URL-encoded JSON array, a path array becomes `1,2`, and a `deepObject` filter becomes `filter[color]=red`, with `spaceDelimited`, `pipeDelimited`, `label`, and `matrix` supported too. An `application/x-www-form-urlencoded` body is sent as `name=value` pairs (following its `encoding`), and a `multipart/form-data` body as form fields: curl uses `--form-string`, JavaScript a `FormData`, and Python `files=`. Before, both were sent as JSON. A `text/plain` or XML body is sent as written, without being blocked as "Invalid JSON", and its string example is no longer wrapped in quotes. Examples that `$ref` an entry under `#/components/examples` now prefill the panel and the response samples instead of being replaced by a generated placeholder. A GraphQL endpoint keeps its trailing slash (`https://host/graphql/` was sent to `…/graphql`). The HEAD curl sample uses `--head` so it no longer waits for a body that never comes, and the Python sample for TRACE uses `requests.request("TRACE", …)`, since `requests.trace` doesn't exist. - 3311cee: With `deployment.base` set, root-relative images and file links in content now gain the base: `![logo](/logo.png)` renders as `/sub/logo.png` and `[spec](/spec.pdf)` (or `<Card href="/spec.pdf">`) as `/sub/spec.pdf`, where Astro serves `public/`. They used to keep the bare root path and 404 on a subpath deploy. Public files still never gain `basePath`, and neither does a redirect whose `to` names one: with `basePath: "/docs"`, a redirect to `/files/whitepaper.pdf` now lands on the file instead of `/docs/files/whitepaper.pdf`. - be9d98e: `mdxRemote()` and `githubReleases()` give up on a request after 30 seconds, like the CMS sources, and the diagnostic names the URL that didn't respond. A server that accepted the connection and never answered used to hang `blume build` and every `blume dev` rescan indefinitely. - af7c4c9: `%` is now dropped from routes the way `:` already was, so `sdks/100%.md` publishes at `/sdks/100` and sidebar and pagination links reach it, where a bare `%` used to break the build's URL decoding; `#` and `?` in a frontmatter `slug` are dropped the same way. A file or folder with `#` or `?` in its name is reported as an error and left out of the site: Astro's content loader can't read such a file, so it used to publish a page that only ever said "Page not found". A frontmatter `slug` with a `.` or `..` segment (`../../etc/escape`, `guides/./x`) is now rejected with an error at the key instead of publishing a page no link could reach. A group folder's numeric prefix now works on either side of the parentheses: `(01-zeta)` sorts first instead of last, and `01-(gamma)` publishes at `/g` as a "Gamma" group instead of at `/(gamma)/g`. - 6933892: On a versioned site, the search dialog shows its "All versions" toggle only with a search provider that scopes results by version: Orama, FlexSearch, Algolia, or Typesense. With Pagefind, Orama Cloud, or Mixedbread the toggle used to show but change nothing, since their results always span every version. - 3311cee: The sitemap and RSS feeds now always put `deployment.base` in front of a page's URL, even when the page's route starts with the same segment. With `base: "/guides"`, a page at `guides/setup.md` is listed at `/guides/guides/setup`, where it's served, instead of `/guides/setup`. - 1b83039: An agent skill's `.tar.gz` now always ends with the two zero blocks that mark the end of a tar archive. A skill whose files filled the archive to within a block of its 10 KB record ended with one zero block or none, and GNU `tar` warned "A lone zero block" while unpacking it. Archives that already ended correctly keep the same bytes and digest. - 6933892: Every tab panel now has the `tabpanel` role its tab points at, including the panels of a `<CodeGroup>`, a TypeScript/JavaScript pair, and a nested tab group, which had none. Panels of `<Tabs dropdown>` no longer claim the `tabpanel` role, since that layout shows a select instead of tabs to label them. - 6933892: The "On this page" highlight now skips headings inside tab panels that aren't selected. Such a heading used to count as already scrolled past, so the table of contents highlighted it from the top of the page. - 1b83039: `blume translate` now looks for `meta.ts` titles only in the folders the content source's `include` globs reach, the same meta files the build reads. A `meta.ts` elsewhere under a project-rooted source (beside tooling, say) configures no sidebar group, and it used to be translated anyway. - b6992c0: `blume translate` rewrites an existing translation where it lives. A stale hand-written `fr/guide.md` for a `guide.mdx` source is updated in place instead of gaining a `fr/guide.mdx` beside it (which failed the next build with a duplicate route), a locale's hand-written `meta.js` or `meta.mjs` is rewritten instead of getting a `meta.ts` next to it, and a locale folder authored in another casing (`pt-br/` for `pt-BR`) now receives the locale's `meta.ts` too, not a second `pt-BR/` folder. A source file saved with a byte order mark keeps its frontmatter in the translation; it used to be written with the body alone. Looking for `meta.ts` titles now skips the content source's `exclude` globs and moves past a meta file that fails to load, where an application file like `src/lib/meta.ts` in a project-rooted source used to crash the run with `BLUME_INTERNAL`. - 3311cee: Redirect `from` paths in the `vercel.json` a static build writes are now escaped, since Vercel reads each `source` as a pattern. A `from` like `/c++-guide` or `/what?` used to make the whole file invalid, and `/faq(old)` never matched. - be9d98e: `blume version` now also rewrites reference-style link definitions (`[setup]: /guides/setup`), single-quoted `href='…'` and `src='…'` attributes, and links that spell out the `basePath` (`/docs/guides/setup` becomes `/docs/v1.0/guides/setup`) inside the snapshot. Those links used to keep pointing at the current docs.