blume 0.3.0 → 0.4.0

package/dist/types/migrate/mintlify/assets.d.ts

@@ -0,0 +1,8 @@
+import type { BlumeConfig } from "../../core/schema.ts";
+/**
+ * Top-level path segments referenced as static assets by a Mintlify config
+ * (the conventional `/images`, plus logo/favicon/background paths). These are
+ * the root-served folders Mintlify exposes at the site root; Blume serves them
+ * via `content.assets` (bridge) or relocates them under `public/` (migrator).
+ */
+export declare const assetSegments: (config: BlumeConfig) => string[];

package/docs/01-quickstart.mdx

@@ -6,9 +6,7 @@ sidebar:
   order: 1
 ---
 
-Go from an empty folder to a running docs site in a few commands. Blume needs
-**Node.js 22 or newer** and a `docs/` folder with at least one `.md` or `.mdx`
-file — there's nothing else to set up.
+Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
 
 ## Install and run
 
@@ -53,16 +51,11 @@ file — there's nothing else to set up.
   </Step>
 </Steps>
 
-:::tip
-Blume works with any package manager and never requires you to set up Astro or
-Tailwind yourself.
-:::
+:::tip Blume works with any package manager and never requires you to set up Astro or Tailwind yourself. :::
 
 ## Write your first page
 
-Every page is Markdown or MDX with a little frontmatter — the `title` and
-`description` render as the page heading and intro automatically. Drop this into
-`docs/index.mdx`:
+Every page is Markdown or MDX with a little frontmatter — the `title` and `description` render as the page heading and intro automatically. Drop this into `docs/index.mdx`:
 
 ```mdx docs/index.mdx lineNumbers
 ---
@@ -72,14 +65,10 @@ description: Welcome to my docs.
 
 Welcome! Use **Markdown** and built-in components — no imports required:
 
-:::note
-Blume ships callouts, cards, tabs, steps, and more.
-:::
+:::note Blume ships callouts, cards, tabs, steps, and more. :::
 ```
 
-Save it, and the dev server reloads instantly. Navigation, search, and page
-metadata are inferred from your files as you add them — keep writing, and the
-site keeps up.
+Save it, and the dev server reloads instantly. Navigation, search, and page metadata are inferred from your files as you add them — keep writing, and the site keeps up.
 
 ## Next steps
 

package/docs/02-deployment.mdx

@@ -8,8 +8,7 @@ sidebar:
 
 ## Deploy anywhere (static)
 
-`blume build` compiles your docs to plain HTML, CSS, and a local search index in
-`dist/`. There's no server to run — point any static host at the folder.
+`blume build` compiles your docs to plain HTML, CSS, and a local search index in `dist/`. There's no server to run — point any static host at the folder.
 
 | Setting          | Value         |
 | ---------------- | ------------- |
@@ -17,9 +16,7 @@ sidebar:
 | Output directory | `dist`        |
 | Node version     | 22 or newer   |
 
-These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon
-S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the
-host can run the build.
+These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.
 
 A static build includes:
 
@@ -32,12 +29,9 @@ A static build includes:
 
 ### Set your site URL
 
-Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On
-**Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the
-platform's environment at build time — no config required.
+Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the platform's environment at build time — no config required.
 
-Set `deployment.site` to override the detected value, or to provide one on hosts
-that don't expose it (GitHub Pages, S3, a custom CDN):
+Set `deployment.site` to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN):
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -45,18 +39,13 @@ deployment: {
 }
 ```
 
-When detecting automatically, Blume prefers your stable production domain over
-per-deploy preview URLs, so the canonical origin stays put across deploys.
+When detecting automatically, Blume prefers your stable production domain over per-deploy preview URLs, so the canonical origin stays put across deploys.
 
-During `blume dev`, the site URL falls back to your local dev server (e.g.
-`http://localhost:4321`) when none is set, so site-gated features — Open Graph
-images, canonicals, the sitemap — work out of the box. Builds never use this
-fallback, so production output is never pointed at localhost.
+During `blume dev`, the site URL falls back to your local dev server (e.g. `http://localhost:4321`) when none is set, so site-gated features — Open Graph images, canonicals, the sitemap — work out of the box. Builds never use this fallback, so production output is never pointed at localhost.
 
 ## Preview locally
 
-Before you ship, preview the production build exactly as a static host would
-serve it:
+Before you ship, preview the production build exactly as a static host would serve it:
 
 ```bash
 blume build
@@ -65,9 +54,7 @@ blume preview
 
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `deployment.base` — common
-for GitHub Pages project sites. Internal links and assets are rewritten to
-include the base path.
+Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. Internal links and assets are rewritten to include the base path.
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -77,8 +64,7 @@ deployment: {
 
 ## Server rendering
 
-Static output covers most docs. Switch to server output when you need
-request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:
+Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -96,19 +82,11 @@ Choosing an adapter pulls in the matching Astro adapter automatically:
 | `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
 | `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |
 
-On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching
-adapter automatically for server output — set `output: "server"` and deploy. Set
-`adapter` explicitly to override the detected value, or when self-hosting with
-`node`.
+On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy. Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
 
-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.
+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.
 
-:::note
-Server features have their own configuration — for example, Ask AI needs a model
-API key. See the [AI guide](/docs/configuration/ai) for setup.
-:::
+:::note Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup. :::
 
 ## Redirects
 
@@ -118,31 +96,20 @@ 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
-handle redirects at request time. Static builds emit redirect pages **and**
-platform files so your host issues a real HTTP redirect: `_redirects` (Netlify,
-Cloudflare Pages), `vercel.json` (Vercel), and `blume-redirects.json` — a
-structured manifest for anything else (nginx/Apache rules, an edge worker). A
-`_redirects` or `vercel.json` you ship in `public/` is left untouched.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds handle redirects at request time. Static builds emit redirect pages **and** platform files so your host issues a real HTTP redirect: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel), and `blume-redirects.json` — a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
 
 ## Environment variables
 
-When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's
-missing — so the problem surfaces early instead of at the first request:
+When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's missing — so the problem surfaces early instead of at the first request:
 
-| Feature                                 | Variable                              |
-| --------------------------------------- | ------------------------------------- |
-| Ask AI (AI Gateway)                     | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
-| Ask AI (OpenRouter / OpenAI-compatible) | the provider's `apiKeyEnv`            |
-| Mixedbread search                       | `MIXEDBREAD_API_KEY`                  |
+| Feature | Variable |
+| --- | --- |
+| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
+| Ask AI (OpenRouter / OpenAI-compatible) | the provider's `apiKeyEnv` |
+| Mixedbread search | `MIXEDBREAD_API_KEY` |
 
-Set them in `.env.local` for local dev and in your host's environment for
-production. Build-time secrets for search-index sync (Algolia, Orama Cloud,
-Typesense) are warned about separately during the sync step.
+Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.
 
 ## Build summary
 
-Every build prints a summary — output mode, adapter, resolved site URL, search
-provider, redirect count, sitemap and `llms.txt` status, and any enabled server
-features — so you can confirm what shipped (including anything auto-detected)
-before you deploy.
+Every build prints a summary — output mode, adapter, resolved site URL, search provider, redirect count, sitemap and `llms.txt` status, and any enabled server features — so you can confirm what shipped (including anything auto-detected) before you deploy.

package/docs/advanced/api-reference.mdx

@@ -3,11 +3,7 @@ title: OpenAPI / AsyncAPI
 description: Drop in an OpenAPI or AsyncAPI spec and get an interactive reference, rendered by Scalar.
 ---
 
-Point Blume at an OpenAPI or AsyncAPI spec and it generates an interactive API
-reference — schemas, authentication, examples, and a request playground — on its
-own route. The reference is rendered by [Scalar](https://scalar.com), not by
-Blume: API reference isn't core to Blume, so the whole surface is delegated to a
-tool that has already solved its large edge-case space.
+Point Blume at an OpenAPI or AsyncAPI spec and it generates an interactive API reference — schemas, authentication, examples, and a request playground — on its own route. The reference is rendered by [Scalar](https://scalar.com), not by Blume: API reference isn't core to Blume, so the whole surface is delegated to a tool that has already solved its large edge-case space.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -16,20 +12,13 @@ openapi: {
 }
 ```
 
-That mounts the reference at `/reference` and adds a header link to it. The
-`spec` is either an `http(s)` URL or a path to a local file in your project.
+That mounts the reference at `/reference` and adds a header link to it. The `spec` is either an `http(s)` URL or a path to a local file in your project.
 
-:::note
-The reference mounts inside Blume's shell — your navbar stays on top — but the
-body is a **self-contained Scalar embed** with its own sidebar, search, and
-theme. By design it doesn't weave into Blume's content sidebar, site search, or
-`llms.txt`.
-:::
+:::note The reference mounts inside Blume's shell — your navbar stays on top — but the body is a **self-contained Scalar embed** with its own sidebar, search, and theme. By design it doesn't weave into Blume's content sidebar, site search, or `llms.txt`. :::
 
 ## A local spec
 
-A relative path is resolved from your project root and inlined at build time, so
-nothing is copied into your source tree and the page works offline:
+A relative path is resolved from your project root and inlined at build time, so nothing is copied into your source tree and the page works offline:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -54,9 +43,7 @@ openapi: {
 
 ## Multiple specs
 
-Use `sources` to publish more than one spec. Each source gets its own route and
-header link. Give each a `label` (used for the link and to derive its route), or
-set an explicit `route`:
+Use `sources` to publish more than one spec. Each source gets its own route and header link. Give each a `label` (used for the link and to derive its route), or set an explicit `route`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -68,14 +55,11 @@ openapi: {
 }
 ```
 
-`spec` is shorthand for a single-entry `sources`, so you only reach for `sources`
-when you have more than one.
+`spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
 ## AsyncAPI
 
-Event-driven APIs use a sibling `asyncapi` block with the **same shape** — Scalar
-renders AsyncAPI through the same component. Only the default route differs
-(`/events`):
+Event-driven APIs use a sibling `asyncapi` block with the **same shape** — Scalar renders AsyncAPI through the same component. Only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
 asyncapi: {
@@ -84,18 +68,11 @@ asyncapi: {
 }
 ```
 
-:::warning
-Scalar's AsyncAPI support is still a work in progress — it renders channels,
-operations, messages, and a Models section, but there's **no interactive
-playground** for events yet. It improves upstream over time.
-:::
+:::warning Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time. :::
 
 ## Theming
 
-By default Blume layers your [accent and radius](/docs/configuration/theming) onto
-Scalar's theme so the reference doesn't feel jarring. It's best-effort, not
-pixel-identical — Scalar carries its own design system. To pick a specific
-[Scalar theme](https://github.com/scalar/scalar) instead, set `theme`:
+By default Blume layers your [accent and radius](/docs/configuration/theming) onto Scalar's theme so the reference doesn't feel jarring. It's best-effort, not pixel-identical — Scalar carries its own design system. To pick a specific [Scalar theme](https://github.com/scalar/scalar) instead, set `theme`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -107,8 +84,4 @@ openapi: {
 
 ## The playground and CORS
 
-Scalar's "Try it" playground calls your **target API directly from the
-browser** — Blume doesn't proxy the request. For it to succeed, the API must
-allow cross-origin requests from the docs site (send the appropriate
-`Access-Control-Allow-Origin` headers). This is a property of the API being
-documented, not of Blume.
+Scalar's "Try it" playground calls your **target API directly from the browser** — Blume doesn't proxy the request. For it to succeed, the API must allow cross-origin requests from the docs site (send the appropriate `Access-Control-Allow-Origin` headers). This is a property of the API being documented, not of Blume.

package/docs/advanced/blog.mdx

@@ -3,16 +3,11 @@ title: Blog
 description: Publish posts as content, get an RSS feed and article structured data for free, and build a custom index page.
 ---
 
-A blog in Blume is just content with a type. Mark a page `type: blog` and Blume
-gives it an RSS feed and richer article metadata automatically. Unlike the
-[changelog](/docs/advanced/changelog), there's no generated index page — you compose
-the landing page yourself, which keeps the design entirely in your hands.
+A blog in Blume is just content with a type. Mark a page `type: blog` and Blume gives it an RSS feed and richer article metadata automatically. Unlike the [changelog](/docs/advanced/changelog), there's no generated index page — you compose the landing page yourself, which keeps the design entirely in your hands.
 
 ## Write a post
 
-A post is a regular `.md` or `.mdx` page with `type: blog` in its frontmatter. By
-convention posts live under `blog/`, but the type — not the folder — is what
-matters:
+A post is a regular `.md` or `.mdx` page with `type: blog` in its frontmatter. By convention posts live under `blog/`, but the type — not the folder — is what matters:
 
 ```mdx blog/introducing-blume.mdx lineNumbers
 ---
@@ -22,19 +17,14 @@ date: 2026-06-22
 description: Why we built a markdown-first docs framework.
 ---
 
-Documentation should be fast, AI-ready, and zero-config — down to not needing a
-starter template at all. Here's the thinking behind Blume.
+Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
 ```
 
-Give every post a `date` so feed items sort newest-first and carry a `pubDate`,
-and a `description` — it's used for both the feed summary and SEO.
+Give every post a `date` so feed items sort newest-first and carry a `pubDate`, and a `description` — it's used for both the feed summary and SEO.
 
 ## The RSS feed
 
-Blume builds a blog feed at **`/blog/rss.xml`**, sorted newest-first by `date`.
-Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume
-then injects a `<link rel="alternate">` tag on every page so readers discover it
-automatically.
+Blume builds a blog feed at **`/blog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.
 
 The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):
 
@@ -52,14 +42,11 @@ Remove `"blog"` from `rss.types` to skip the feed.
 
 ## Structured data
 
-When [structured data](/docs/configuration/seo#structured-data) is on, each post is
-emitted as a schema.org **`BlogPosting`** with its description and publish date —
-the richer article type search engines expect for blog content.
+When [structured data](/docs/configuration/seo#structured-data) is on, each post is emitted as a schema.org **`BlogPosting`** with its description and publish date — the richer article type search engines expect for blog content.
 
 ## Building an index
 
-Blume doesn't generate a `/blog` landing page, so you build one. The simplest
-option is a content page that links to each post by hand:
+Blume doesn't generate a `/blog` landing page, so you build one. The simplest option is a content page that links to each post by hand:
 
 ```mdx blog/index.mdx lineNumbers
 ---
@@ -74,9 +61,7 @@ description: News and writing from the team.
 </CardGroup>
 ```
 
-To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages)
-at `pages/blog/index.astro` that reads from Astro's `docs` content collection and
-pairs each entry with its route from `blume:data`:
+To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages) at `pages/blog/index.astro` that reads from Astro's `docs` content collection and pairs each entry with its route from `blume:data`:
 
 ```astro pages/blog/index.astro lineNumbers
 ---
@@ -108,8 +93,7 @@ const posts = (await getCollection("docs"))
 </ul>
 ```
 
-See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this
-in the full site layout.
+See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this in the full site layout.
 
 <CardGroup cols={2}>
   <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">

package/docs/advanced/changelog.mdx

@@ -3,16 +3,11 @@ title: Changelog
 description: Author release notes as content, and Blume builds a timeline page and an RSS feed automatically.
 ---
 
-Blume ships a changelog out of the box. Write each release as a normal content
-file, mark it `type: changelog`, and Blume collects every entry into a generated
-timeline page and an RSS feed — no layout to build, no list to maintain. Or skip
-the files entirely and [source your changelog from GitHub Releases](#from-github-releases).
+Blume ships a changelog out of the box. Write each release as a normal content file, mark it `type: changelog`, and Blume collects every entry into a generated timeline page and an RSS feed — no layout to build, no list to maintain. Or skip the files entirely and [source your changelog from GitHub Releases](#from-github-releases).
 
 ## Write an entry
 
-A changelog entry is a regular `.md` or `.mdx` page with `type: changelog` in its
-frontmatter. By convention they live under `changelog/`, but the type — not the
-folder — is what matters:
+A changelog entry is a regular `.md` or `.mdx` page with `type: changelog` in its frontmatter. By convention they live under `changelog/`, but the type — not the folder — is what matters:
 
 ```mdx changelog/v1-2-0.mdx lineNumbers
 ---
@@ -24,15 +19,13 @@ changelog:
   category: Features
 ---
 
-A big batch of components landed this release — columns, frames, trees, and
-tooltips, plus code groups that render as proper language tabs.
+A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.
 
 - New `Accordion`, `Expandable`, and `Tooltip` components
 - `CodeGroup` tabs with flush code blocks
 ```
 
-Give every entry a `date` so the timeline and feed sort newest-first. An
-unquoted YAML date is fine — Blume normalizes it.
+Give every entry a `date` so the timeline and feed sort newest-first. An unquoted YAML date is fine — Blume normalizes it.
 
 ### The `changelog` object
 
@@ -60,25 +53,17 @@ The optional `changelog` object adds richer metadata for the timeline and feed:
 
 ## The timeline page
 
-Once you have at least one `type: changelog` entry, Blume generates a
-**`/changelog`** page automatically. Each entry renders newest-first with its
-date, label, and `category` tag in a left rail beside its content:
+Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. Each entry renders newest-first with its date, label, and `category` tag in a left rail beside its content:
 
 - The entry **title** becomes its label — or `v{version}` when there's no title.
 - The `category` renders as a tag next to the date.
 - Drafts and `sidebar.hidden` entries are skipped.
 
-The page appears only when nothing already occupies the `/changelog` route. To
-replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at
-`pages/changelog.astro` — it takes over and Blume stops generating the default
-timeline.
+The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default timeline.
 
 ## From GitHub Releases
 
-Rather than authoring entries by hand, point the built-in
-[`github-releases` source](/docs/content/sources#github-releases) at a repo and
-every release becomes a `type: changelog` entry — the same timeline and feed,
-fed straight from the releases you already publish:
+Rather than authoring entries by hand, point the built-in [`github-releases` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish:
 
 ```ts blume.config.ts
 content: {
@@ -94,17 +79,11 @@ content: {
 }
 ```
 
-The release name becomes the title, its tag becomes `changelog.version`, and its
-published date sorts the timeline. A private repo authenticates with the
-`GITHUB_TOKEN` environment variable. See
-[Content sources](/docs/content/sources#github-releases) for every option.
+The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
 
 ## The RSS feed
 
-Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted
-newest-first by `date`. Feeds need an absolute site URL, so set
-[`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">`
-tag on every page so readers discover it automatically.
+Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.
 
 The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):
 
@@ -122,9 +101,7 @@ Remove `"changelog"` from `rss.types` to skip the feed while keeping the timelin
 
 ## Structured data
 
-When [structured data](/docs/configuration/seo#structured-data) is on, each changelog
-entry is emitted as a schema.org **`TechArticle`** with its description and
-publish date, so search engines can index releases as dated articles.
+When [structured data](/docs/configuration/seo#structured-data) is on, each changelog entry is emitted as a schema.org **`TechArticle`** with its description and publish date, so search engines can index releases as dated articles.
 
 <CardGroup cols={2}>
   <Card