blume 0.3.0 → 0.5.0

package/dist/types/core/types.d.ts

@@ -44,6 +44,13 @@ export interface ProjectContext {
     pagesRoot: string | null;
     /** Absolute path to the generated runtime (`<root>/.blume`). */
     outDir: string;
+    /**
+     * Absolute path to the Astro build output. `<root>/dist` normally; for a
+     * relocated runtime (isolated verify build) it lives under the runtime dir so
+     * it never empties the real `dist/`. Optional so hand-built test contexts and
+     * older callers still typecheck; `resolveProjectContext` always sets it.
+     */
+    distDir?: string;
     /** Absolute path to the user `theme.css`, if present. */
     themeFile: string | null;
     /** Absolute path to the user `components.ts`/`.tsx`, if present. */

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

@@ -1,13 +1,9 @@
 ---
 title: OpenAPI / AsyncAPI
-description: Drop in an OpenAPI or AsyncAPI spec and get an interactive reference, rendered by Scalar.
+description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-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 spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
 
 ```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` (an overview page) with each operation at `/reference/<tag>/<operation>`, and adds a header tab. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
 
-:::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 Operations are indexed for search by their **summary and tag**. The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title and section, then links to its own page. :::
 
 ## 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 read at build time. Both JSON and YAML work:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -38,25 +27,34 @@ openapi: {
 }
 ```
 
-Both JSON and YAML specs work; Scalar auto-detects the format.
-
 ## Route
 
-`route` controls where the reference mounts (and the header link's target):
+`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the header tab's target):
 
 ```ts blume.config.ts lineNumbers
 openapi: {
   enabled: true,
-  route: "/api",
+  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
   spec: "./openapi.yaml",
 }
 ```
 
+## Code samples and schemas
+
+`codeSamples` picks which languages render per operation (built in: `curl`, `js`, `python`); `expandSchemas` starts nested schema rows expanded rather than collapsed:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+  codeSamples: ["curl", "js"],
+  expandSchemas: true,
+}
+```
+
 ## 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 overview route, operation pages, and header tab. Give each a `label` (used for the tab and to derive its route), or set an explicit `route`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -68,47 +66,32 @@ 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
+## The Scalar renderer
 
-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`):
+The native renderer is the default. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference — its own sidebar, search, theme, and "Try it" playground on a single route — set `renderer: "scalar"`:
 
 ```ts blume.config.ts lineNumbers
-asyncapi: {
+openapi: {
   enabled: true,
-  spec: "./asyncapi.yaml",
+  renderer: "scalar",
+  spec: "./openapi.yaml",
+  theme: "purple",   // a Scalar theme name (Scalar renderer only)
 }
 ```
 
-:::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.
-:::
+A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
 
-## Theming
+## AsyncAPI
 
-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`:
+Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
-openapi: {
+asyncapi: {
   enabled: true,
-  spec: "./openapi.yaml",
-  theme: "purple",
+  spec: "./asyncapi.yaml",
 }
 ```
 
-## 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.
+:::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. :::

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/bridge.mdx

@@ -0,0 +1,74 @@
+---
+title: Bridge
+description: Run blume dev directly on a Mintlify codebase — no config, no migration, no file changes. Blume detects docs.json and serves it in place.
+---
+
+Bridge mode lets you point Blume at a **Mintlify** project and run it as-is. There's no config to write and no migration to commit: drop `blume dev` into a directory that has a `docs.json` (or legacy `mint.json`) and Blume detects it, synthesizes an equivalent config in memory, and serves your existing MDX — transformed to Blume idiom on the fly, on disk untouched.
+
+```bash
+cd my-mintlify-docs
+npx blume dev
+```
+
+```txt
+ℹ Detected docs.json — running in Mintlify bridge mode (no migration).
+  Run "blume migrate mintlify" to convert permanently.
+```
+
+It's the zero-commitment way to see what your docs look like on Blume — you can keep running `mintlify dev` in one terminal and `blume dev` in another, side by side, and decide later.
+
+## When it activates
+
+Bridge mode is entirely automatic, gated on two conditions:
+
+- **No Blume config.** There's no `blume.config.{ts,js,mjs}` at the project root. An explicit Blume config always wins — the moment one exists, Blume runs a normal project and bridge mode never triggers.
+- **A Mintlify config is present.** A `docs.json` or `mint.json` sits at the root.
+
+With both true, Blume treats the Mintlify config as its source of truth for that run.
+
+:::note Bridge mode applies to `blume build` too, not just `blume dev` — you can produce a static site from an unconverted Mintlify project. Only `blume dev` prints the detection notice. :::
+
+## What happens under the hood
+
+Bridge mode is the **read-only twin** of [`blume migrate mintlify`](/docs/advanced/migrate#mintlify): the same translation, without writing anything back.
+
+- **Config is synthesized in memory.** `docs.json` is translated to a Blume config — navigation, theme, and chrome mapped across — exactly as the migrator would, but nothing is written to disk.
+- **Content is served through a Mintlify source.** The config's content block is rewired to a single [`mintlify` content source](/docs/content/sources) rooted at the project. Each MDX page is transformed to Blume markup **at scan time** as it's read, so your files never change.
+- **Variables are inlined at scan time.** `docs.json` `variables` (`{{name}}`) are substituted into content as it's scanned — Blume has no runtime substitution.
+- **Assets are served in place.** Referenced folders like `images/` are served through [`content.assets`](/docs/content/sources) rather than moved to `public/`, so nothing is relocated.
+- **Languages map to i18n.** A multi-language `docs.json` maps to Blume's [`i18n`](/docs/content/i18n), with the language switch handled by Blume's locale routing instead of a nav selector.
+
+Because it reads the same `docs.json` and runs the same transforms, what you see in bridge mode is what you'd get from a full migration.
+
+## Bridge vs. migrate
+
+<CardGroup cols={2}>
+  <Card title="Bridge mode" icon="cable">
+    **Try Blume with zero changes.** Nothing is written; your Mintlify project
+    stays exactly as it is. Ideal for evaluating Blume, running both dev servers
+    side by side, or a reversible spike.
+  </Card>
+  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
+    **Convert for good.** [`blume migrate mintlify`](/docs/advanced/migrate)
+    rewrites your pages, config, and assets in place so Blume becomes the source
+    of truth. Do this once you've decided to switch.
+  </Card>
+</CardGroup>
+
+Everything you can do in bridge mode, you can do permanently by migrating — bridge is the preview, migrate is the commit.
+
+## Limitations
+
+- **Mintlify only.** Bridge detection is Mintlify-specific. The other frameworks — Fumadocs, Nextra, Starlight — need a [one-shot migration](/docs/advanced/migrate).
+- **Same idiom gaps as the migrator.** Components without a Blume equivalent are transformed on a best-effort basis; when you hit one, [migrate](/docs/advanced/migrate) and address the warnings, or switch that page to a Blume-native equivalent such as the [OpenAPI reference](/docs/advanced/api-reference).
+- **No runtime variables.** As with a migration, `{{variable}}` values are inlined at scan time rather than substituted at runtime.
+
+<CardGroup cols={2}>
+  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
+    Convert a Mintlify, Fumadocs, Nextra, or Starlight project permanently.
+  </Card>
+  <Card title="Content sources" href="/docs/content/sources" icon="folder-tree">
+    How the `mintlify` source and `content.assets` fit into Blume's content
+    graph.
+  </Card>
+</CardGroup>

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