blume 0.3.0 → 0.5.0

package/docs/content/sources.mdx

@@ -3,16 +3,11 @@ title: Content sources
 description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
 ---
 
-By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let
-you pull pages from somewhere else — a remote repository, a CMS, or any custom
-backend — and mix several sources into a single site. Sources are read at
-build time; Blume stays static-first.
+By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.
 
 ## The default
 
-With no configuration, Blume scans your content root (`docs` by default) as one
-implicit filesystem source. The top-level `content.root`/`include`/`exclude`
-options still work exactly as before — nothing to change.
+With no configuration, Blume scans your content root (`docs` by default) as one implicit filesystem source. The top-level `content.root`/`include`/`exclude` options still work exactly as before — nothing to change.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -24,10 +19,7 @@ export default defineConfig({
 
 ## Multiple sources
 
-Add a `content.sources` array to compose sources. Each entry is namespaced by an
-optional `prefix`, so its routes nest under `/<prefix>/…`. When `sources` is
-present it replaces the implicit default, so include a `filesystem` entry for
-your local docs.
+Add a `content.sources` array to compose sources. Each entry is namespaced by an optional `prefix`, so its routes nest under `/<prefix>/…`. When `sources` is present it replaces the implicit default, so include a `filesystem` entry for your local docs.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -49,14 +41,11 @@ export default defineConfig({
 });
 ```
 
-If two sources resolve to the same route, Blume reports a `BLUME_DUPLICATE_ROUTE`
-build error — give each source a distinct `prefix`.
+If two sources resolve to the same route, Blume reports a `BLUME_DUPLICATE_ROUTE` build error — give each source a distinct `prefix`.
 
 ## Remote MDX
 
-The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate
-files either from a GitHub repo subtree (`github`) or explicitly against a raw
-base URL (`url` + `files`):
+The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate files either from a GitHub repo subtree (`github`) or explicitly against a raw base URL (`url` + `files`):
 
 ```ts blume.config.ts
 {
@@ -67,34 +56,19 @@ base URL (`url` + `files`):
 }
 ```
 
-A private repo's token is read from the `GITHUB_TOKEN` environment variable — it
-is never inlined into your config or generated output.
+A private repo's token is read from the `GITHUB_TOKEN` environment variable — it is never inlined into your config or generated output.
 
-Remote pages are rendered with full MDX-plus-component fidelity: their bodies are
-materialized into a hidden staging directory and rendered through Astro
-alongside your local docs, so callouts, tabs, and every other Blume component
-keep working.
+Remote pages are rendered with full MDX-plus-component fidelity: their bodies are materialized into a hidden staging directory and rendered through Astro alongside your local docs, so callouts, tabs, and every other Blume component keep working.
 
 ### Caching and offline builds
 
-Each remote source keeps a snapshot under `.blume/cache/<source>/`. If a fetch
-fails — a network blip or a CMS outage — Blume serves the last-known-good
-snapshot with a warning rather than failing the build. The cache lives inside
-`.blume/` and is regenerated, never committed.
+Each remote source keeps a snapshot under `.blume/cache/<source>/`. If a fetch fails — a network blip or a CMS outage — Blume serves the last-known-good snapshot with a warning rather than failing the build. The cache lives inside `.blume/` and is regenerated, never committed.
 
-In dev, remote content is fetched once and frozen for the session; restart the
-dev server to refresh it. Local filesystem sources hot-reload as usual. To poll
-a remote source for changes instead, set `pollInterval` (seconds) on it — the
-dev server re-fetches on that interval and reloads only when the content
-actually changes. Leave it unset to avoid hitting the API while you work.
+In dev, remote content is fetched once and frozen for the session; restart the dev server to refresh it. Local filesystem sources hot-reload as usual. To poll a remote source for changes instead, set `pollInterval` (seconds) on it — the dev server re-fetches on that interval and reloads only when the content actually changes. Leave it unset to avoid hitting the API while you work.
 
 ## GitHub Releases
 
-The built-in `github-releases` source turns a repo's releases into a changelog:
-each release becomes a `type: changelog` entry, so your release notes _are_ your
-changelog — nothing to write twice. Combined with the generated
-[changelog timeline](/docs/advanced/changelog), publishing a GitHub release
-ships a changelog entry.
+The built-in `github-releases` source turns a repo's releases into a changelog: each release becomes a `type: changelog` entry, so your release notes _are_ your changelog — nothing to write twice. Combined with the generated [changelog timeline](/docs/advanced/changelog), publishing a GitHub release ships a changelog entry.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -117,25 +91,13 @@ export default defineConfig({
 });
 ```
 
-Each release maps to the changelog fields automatically: its name (or tag)
-becomes the title, its published date drives the timeline order, the tag becomes
-`changelog.version`, and prereleases are tagged `Prerelease` (others `Release`).
-The notes render as the entry body. Give the source a `prefix` so its release
-pages nest under a route like `/changelog/v1-2-0`.
+Each release maps to the changelog fields automatically: its name (or tag) becomes the title, its published date drives the timeline order, the tag becomes `changelog.version`, and prereleases are tagged `Prerelease` (others `Release`). The notes render as the entry body. Give the source a `prefix` so its release pages nest under a route like `/changelog/v1-2-0`.
 
-A private repo authenticates with the `GITHUB_TOKEN` environment variable — the
-same token the other GitHub features use, never inlined into your config. Like
-every remote source it's cached under `.blume/cache/<source>/` and served
-offline if the API is unreachable. Because a changelog is supplementary, a fetch
-failure with no cache (say a CI build without a token) degrades to an empty
-changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in
-your CI and deploy environments to populate it.
+A private repo authenticates with the `GITHUB_TOKEN` environment variable — the same token the other GitHub features use, never inlined into your config. Like every remote source it's cached under `.blume/cache/<source>/` and served offline if the API is unreachable. Because a changelog is supplementary, a fetch failure with no cache (say a CI build without a token) degrades to an empty changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in your CI and deploy environments to populate it.
 
 ## Sanity
 
-The built-in `sanity` source runs a GROQ query and maps each document's fields
-to frontmatter and its Portable Text body to Markdown. The `@sanity/client`
-package is an optional peer dependency — install it only if you use this source.
+The built-in `sanity` source runs a GROQ query and maps each document's fields to frontmatter and its Portable Text body to Markdown. The `@sanity/client` package is an optional peer dependency — install it only if you use this source.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -158,17 +120,11 @@ export default defineConfig({
 });
 ```
 
-A read token for a private dataset comes from the `SANITY_TOKEN` environment
-variable. Custom Portable Text block types map to Blume components through the
-adapter's `serializers` option, available when you construct `sanitySource`
-directly via a [custom source](#custom-sources).
+A read token for a private dataset comes from the `SANITY_TOKEN` environment variable. Custom Portable Text block types map to Blume components through the adapter's `serializers` option, available when you construct `sanitySource` directly via a [custom source](#custom-sources).
 
 ## Notion
 
-The built-in `notion` source turns a Notion database into a collection: each row
-becomes a page, its properties become frontmatter, and its block tree becomes
-MDX. Callouts, toggles, columns, and code blocks map to the matching Blume
-components. `@notionhq/client` is an optional peer dependency.
+The built-in `notion` source turns a Notion database into a collection: each row becomes a page, its properties become frontmatter, and its block tree becomes MDX. Callouts, toggles, columns, and code blocks map to the matching Blume components. `@notionhq/client` is an optional peer dependency.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -190,29 +146,14 @@ export default defineConfig({
 });
 ```
 
-The integration token comes from the `NOTION_TOKEN` environment variable (share
-the database with your integration). By default every page is imported; set
-`publishedValue` to make the `Status` property a publish gate — any other value
-then maps to `draft: true`, which production builds drop. **Notion image URLs
-are signed and expire**, so the adapter downloads them at build time into the
-site's assets and rewrites the references — a CMS image never rots a static
-build.
+The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build.
 
 ## Preview and sync
 
 Two flags control how remote content is fetched and what's included:
 
-- **`--preview`** on `blume dev` or `blume build` renders drafts and pulls
-  unpublished CMS content — Sanity switches to its `previewDrafts` perspective,
-  and Notion stops filtering by `Status`. Production builds without the flag
-  exclude drafts as usual, so a preview build is a safe way to review
-  unpublished work before it ships.
-- **`blume sync`** re-fetches every remote source and regenerates the runtime.
-  Dev is cache-first — a remote source is fetched once and served from
-  `.blume/cache` on restart (fast and offline-tolerant), so `blume sync` is how
-  you pull the latest CMS content without restarting the dev server (a running
-  server hot-reloads). Add `--force` to drop the cache first, or set
-  `pollInterval` on a source to refresh automatically.
+- **`--preview`** on `blume dev` or `blume build` renders drafts and pulls unpublished CMS content — Sanity switches to its `previewDrafts` perspective, and Notion stops filtering by `Status`. Production builds without the flag exclude drafts as usual, so a preview build is a safe way to review unpublished work before it ships.
+- **`blume sync`** re-fetches every remote source and regenerates the runtime. Dev is cache-first — a remote source is fetched once and served from `.blume/cache` on restart (fast and offline-tolerant), so `blume sync` is how you pull the latest CMS content without restarting the dev server (a running server hot-reloads). Add `--force` to drop the cache first, or set `pollInterval` on a source to refresh automatically.
 
 ```sh
 blume dev --preview      # author workflow: see drafts live
@@ -223,9 +164,7 @@ blume sync --force        # ...ignoring any cached snapshot
 
 ## Custom sources
 
-Any object implementing the `ContentSource` interface can be passed directly,
-which is how an adapter with custom serializers — or any backend not built in —
-plugs in without its SDK touching the core install:
+Any object implementing the `ContentSource` interface can be passed directly, which is how an adapter with custom serializers — or any backend not built in — plugs in without its SDK touching the core install:
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -254,6 +193,4 @@ export default defineConfig({
 });
 ```
 
-A source normalizes its native shape (Portable Text, Notion blocks, remote HTML)
-to Markdown/MDX text, so the same components and markdown features apply no
-matter where a page comes from.
+A source normalizes its native shape (Portable Text, Notion blocks, remote HTML) to Markdown/MDX text, so the same components and markdown features apply no matter where a page comes from.

package/docs/content/syntax.mdx

@@ -3,19 +3,11 @@ title: Syntax
 description: Every Markdown and MDX feature Blume renders — formatting, lists, tables, callouts, code blocks, package installs, and math.
 ---
 
-Blume renders standard Markdown and MDX with a curated, GitHub-flavored feature
-set — no imports, no configuration. Write content the way you already do; this
-page shows everything that's supported, with a live preview and the source for
-each.
+Blume renders standard Markdown and MDX with a curated, GitHub-flavored feature set — no imports, no configuration. Write content the way you already do; this page shows everything that's supported, with a live preview and the source for each.
 
 ## Headings
 
-Structure a page with headings. Blume renders your frontmatter `title` as the
-page heading, so start your content at `##` — `##` and `###` become entries
-in the table of contents. Every `##`–`######` heading is also wrapped in a link
-to its own anchor, so readers can click a heading to copy, bookmark, or share a
-permalink straight to that section (hover to reveal the `#`). Turn this off with
-`markdown: { headingAnchors: false }` in `blume.config.ts`.
+Structure a page with headings. Blume renders your frontmatter `title` as the page heading, so start your content at `##` — `##` and `###` become entries in the table of contents. Every `##`–`######` heading is also wrapped in a link to its own anchor, so readers can click a heading to copy, bookmark, or share a permalink straight to that section (hover to reveal the `#`). Turn this off with `markdown: { headingAnchors: false }` in `blume.config.ts`.
 
 ```md
 ## Section
@@ -27,8 +19,7 @@ permalink straight to that section (hover to reveal the `#`). Turn this off with
 
 ## Emphasis
 
-Inline formatting for stressing words, marking deletions, and showing code or
-keystrokes mid-sentence.
+Inline formatting for stressing words, marking deletions, and showing code or keystrokes mid-sentence.
 
 **Bold**, _italic_, ~~strikethrough~~, and `inline code`.
 
@@ -48,8 +39,7 @@ E = mc^2^ and H~2~O.
 
 ## Blockquotes
 
-Set off a quotation, callout aside, or an editorial note from the surrounding
-text.
+Set off a quotation, callout aside, or an editorial note from the surrounding text.
 
 > Documentation that's fast, AI-ready, and zero-config — down to the template.
 
@@ -59,8 +49,7 @@ text.
 
 ## Lists
 
-Use unordered lists for unordered sets, ordered lists for sequences, and task
-lists for checklists and roadmaps.
+Use unordered lists for unordered sets, ordered lists for sequences, and task lists for checklists and roadmaps.
 
 - Markdown-first authoring
 - Static by default
@@ -90,8 +79,7 @@ lists for checklists and roadmaps.
 
 ## Tables
 
-Tabulate structured data — config options, comparison matrices, parameter lists.
-Use colons in the divider row to align columns.
+Tabulate structured data — config options, comparison matrices, parameter lists. Use colons in the divider row to align columns.
 
 | Command       | Description           | Output  |
 | ------------- | --------------------- | :-----: |
@@ -107,8 +95,7 @@ Use colons in the divider row to align columns.
 
 ## Links and images
 
-Link to other pages or external sites. Images accept any path under `public/` or
-a remote URL.
+Link to other pages or external sites. Images accept any path under `public/` (or another directory listed in [`content.assets`](/docs/configuration#content)) or a remote URL.
 
 Read the [quickstart](/docs/quickstart) to get started.
 
@@ -118,9 +105,7 @@ Read the [quickstart](/docs/quickstart) to get started.
 ![Alt text](/screenshot.png)
 ```
 
-Content images are click-to-zoom by default — readers can click any image to open
-it in a lightbox. Turn this off with `markdown: { imageZoom: false }` in
-`blume.config.ts`, or opt a single image out with `data-no-zoom`.
+Content images are click-to-zoom by default — readers can click any image to open it in a lightbox. Turn this off with `markdown: { imageZoom: false }` in `blume.config.ts`, or opt a single image out with `data-no-zoom`.
 
 ## Horizontal rule
 
@@ -134,10 +119,7 @@ Separate major shifts in topic within a long page.
 
 ## Code blocks
 
-Fenced code blocks are syntax-highlighted with a header showing the language —
-with a brand icon for recognized languages — and a copy button. Add a **title**
-after the language — typically a filename — and it replaces the language label in
-the header.
+Fenced code blocks are syntax-highlighted with a header showing the language — with a brand icon for recognized languages — and a copy button. Add a **title** after the language — typically a filename — and it replaces the language label in the header.
 
 ```ts blume.config.ts
 import { defineConfig } from "blume";
@@ -157,14 +139,11 @@ export default defineConfig({
 ```
 ````
 
-Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span
-and it's colored like a tiny code block — `useState(){:js}` or
-`T extends object{:ts}`. Turn it on with `markdown: { code: { inline: true } }`.
+Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. Turn it on with `markdown: { code: { inline: true } }`.
 
 ### Line numbers
 
-Append `lineNumbers` to render a line-number gutter — on its own or alongside a
-title:
+Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:
 
 ```ts server.ts lineNumbers
 import { serve } from "blume";
@@ -182,9 +161,7 @@ serve({ port: 3000 });
 
 ### Highlighting
 
-Annotate code with GitHub-style comments to draw attention to lines, words, and
-changes. The comments are stripped from the rendered output, so the code stays
-copy-paste clean. All four are on by default — no configuration.
+Annotate code with GitHub-style comments to draw attention to lines, words, and changes. The comments are stripped from the rendered output, so the code stays copy-paste clean. All four are on by default — no configuration.
 
 Mark a line with `// [!code highlight]` to give it a highlighted background:
 
@@ -194,8 +171,7 @@ const config = defineConfig({
 });
 ```
 
-Show changes with `// [!code ++]` for additions and `// [!code --]` for
-removals, rendered as a green/red diff:
+Show changes with `// [!code ++]` for additions and `// [!code --]` for removals, rendered as a green/red diff:
 
 ```ts
 export default defineConfig({
@@ -212,8 +188,7 @@ import { serve } from "blume"; // [!code word:serve]
 serve({ port: 3000 });
 ```
 
-Dim everything except the lines you mark with `// [!code focus]` (the rest
-sharpens on hover):
+Dim everything except the lines you mark with `// [!code focus]` (the rest sharpens on hover):
 
 ```ts
 export default defineConfig({
@@ -222,9 +197,7 @@ export default defineConfig({
 });
 ```
 
-Or highlight lines by **number** instead of comments — useful when you can't edit
-the code. Put a brace range after the language; single lines, comma lists, and
-`start-end` spans all work:
+Or highlight lines by **number** instead of comments — useful when you can't edit the code. Put a brace range after the language; single lines, comma lists, and `start-end` spans all work:
 
 ```ts {1,4-5}
 import { defineConfig } from "blume";
@@ -248,10 +221,7 @@ export default defineConfig({
 
 ### Display types
 
-Mark a TypeScript block `twoslash` to display real types straight from the
-compiler — powered by [Twoslash](https://shiki.style/packages/twoslash). Hover
-any token to see its inferred type, and add an inline `^?` query to pin a type
-below the line.
+Mark a TypeScript block `twoslash` to display real types straight from the compiler — powered by [Twoslash](https://shiki.style/packages/twoslash). Hover any token to see its inferred type, and add an inline `^?` query to pin a type below the line.
 
 ```ts twoslash
 const config = {
@@ -272,15 +242,11 @@ config.title;
 ```
 ````
 
-:::note
-Hide the language icons or wrap long lines instead of scrolling with
-`markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`.
-:::
+:::note Hide the language icons or wrap long lines instead of scrolling with `markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`. :::
 
 ## Package install
 
-A `package-install` block turns a single install command into a tabbed snippet
-for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup.
+A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup.
 
 ```package-install
 npm i blume
@@ -294,9 +260,7 @@ npm i blume
 
 ## Diagrams
 
-A `mermaid` block renders a [Mermaid](https://mermaid.js.org) diagram — flowcharts,
-sequence diagrams, and more — straight from text. Diagrams follow the active color
-theme and re-render when it changes.
+A `mermaid` block renders a [Mermaid](https://mermaid.js.org) diagram — flowcharts, sequence diagrams, and more — straight from text. Diagrams follow the active color theme and re-render when it changes.
 
 ```mermaid
 flowchart LR
@@ -314,105 +278,77 @@ flowchart LR
 ```
 ````
 
-Diagrams render on the client, so this is an MDX-only feature, and the Mermaid
-library loads only on pages that include one.
+Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one.
 
 ## Callouts
 
-Callouts pull a reader's attention to context, advice, or risk. Write them as
-`:::type` directives; add a title in brackets, like `:::warning[Heads up]`.
+Callouts pull a reader's attention to context, advice, or risk. Write them as `:::type` directives; add a title in brackets, like `:::warning[Heads up]`.
 
 ### Note
 
 Neutral, supporting context the reader should keep in mind.
 
-:::note
-Blume regenerates `.blume/` on every run — never edit it by hand.
-:::
+:::note Blume regenerates `.blume/` on every run — never edit it by hand. :::
 
 ```md
-:::note
-Blume regenerates `.blume/` on every run — never edit it by hand.
-:::
+:::note Blume regenerates `.blume/` on every run — never edit it by hand. :::
 ```
 
 ### Tip
 
 A helpful shortcut or best practice that isn't required but makes life easier.
 
-:::tip
-Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
-:::
+:::tip Set `deployment.site` so sitemaps and Open Graph images use absolute URLs. :::
 
 ```md
-:::tip
-Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
-:::
+:::tip Set `deployment.site` so sitemaps and Open Graph images use absolute URLs. :::
 ```
 
 ### Success
 
 Confirm a positive outcome or that a step completed as expected.
 
-:::success
-Your docs built successfully and are ready to deploy.
-:::
+:::success Your docs built successfully and are ready to deploy. :::
 
 ```md
-:::success
-Your docs built successfully and are ready to deploy.
-:::
+:::success Your docs built successfully and are ready to deploy. :::
 ```
 
 ### Warning
 
 Flag something that needs care to avoid a mistake or surprising behavior.
 
-:::warning[Heads up]
-Switching to `output: "server"` requires an adapter before you can deploy.
-:::
+:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy. :::
 
 ```md
-:::warning[Heads up]
-Switching to `output: "server"` requires an adapter before you can deploy.
-:::
+:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy. :::
 ```
 
 ### Danger
 
 Call out a destructive or breaking action that can't easily be undone.
 
-:::danger
-`blume eject` is a one-way step — the generated Astro project becomes yours.
-:::
+:::danger `blume eject` is a one-way step — the generated Astro project becomes yours. :::
 
 ```md
-:::danger
-`blume eject` is a one-way step — the generated Astro project becomes yours.
-:::
+:::danger `blume eject` is a one-way step — the generated Astro project becomes yours. :::
 ```
 
 ### Info
 
 An informational aside; an alias-friendly default that reads as neutral.
 
-:::info
-The core theme ships zero client JavaScript.
-:::
+:::info The core theme ships no client framework JS. :::
 
 ```md
-:::info
-The core theme ships zero client JavaScript.
-:::
+:::info The core theme ships no client framework JS. :::
 ```
 
-The names `caution`, `error`, `important`, and `warn` are accepted as aliases for
-`warning`, `danger`, `note`, and `warning` respectively.
+The names `caution`, `error`, `important`, and `warn` are accepted as aliases for `warning`, `danger`, `note`, and `warning` respectively.
 
 ## Math
 
-Render LaTeX with KaTeX for formulas in prose or as centered blocks — useful for
-math-heavy or scientific docs. Inline math goes in `$…$`; block math in `$$…$$`.
+Render LaTeX with KaTeX for formulas in prose or as centered blocks — useful for math-heavy or scientific docs. Inline math goes in `$…$`; block math in `$$…$$`.
 
 The Pythagorean theorem is $a^2 + b^2 = c^2$.
 
@@ -428,15 +364,11 @@ $$
 $$
 ```
 
-:::note
-Math is opt-in because `$` is common in prose and code. Enable it with
-`markdown: { math: true }` in `blume.config.ts`.
-:::
+:::note Math is opt-in because `$` is common in prose and code. Enable it with `markdown: { math: true }` in `blume.config.ts`. :::
 
 ## Smart punctuation
 
-Blume converts straight quotes and dashes to typographic equivalents as you
-write, so prose reads like it was typeset — no special characters required.
+Blume converts straight quotes and dashes to typographic equivalents as you write, so prose reads like it was typeset — no special characters required.
 
 "Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
 

package/docs/index.mdx

@@ -6,9 +6,7 @@ sidebar:
   order: 0
 ---
 
-Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade
-docs site — navigation, search, theming, Open Graph images, and a rich component
-library — with no app boilerplate to write or maintain.
+Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade docs site — navigation, search, theming, Open Graph images, and a rich component library — with no app boilerplate to write or maintain.
 
 <CardGroup cols={2}>
   <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
@@ -29,61 +27,34 @@ Blume takes the best of both worlds. The framework is the template, so the only
 
 ### Fast by default
 
-Blume builds on Astro and Vite and renders static HTML by default — fast,
-cacheable, and cheap to host. The core theme is React-free and ships **zero
-client JavaScript**, so pages score well on Core Web Vitals out of the box. Dev
-startup and hot reload feel Vite-native, and you opt into server features only
-when you need them.
+Blume builds on Astro and Vite and renders static HTML by default — fast, cacheable, and cheap to host. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. Dev startup and hot reload feel Vite-native, and you opt into server features only when you need them.
 
 ### AI-ready out of the box
 
-Every Blume site speaks fluent machine. It emits [`llms.txt` and
-`llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by
-appending `.md` to its URL, and gives readers **Copy as Markdown** and **Open in
-chat** actions on every page. Add an optional in-page **Ask AI** assistant, or
-host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like
-Claude Code and Cursor can search and read your docs directly — no scraping, no
-hosted service. Your Markdown is the source of truth for both humans and models.
+Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by appending `.md` to its URL, and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
 
 ### Zero configuration — even the template
 
-A folder of docs is a complete project. There's no starter to clone, no Astro or
-Tailwind to set up, and no template to maintain. Navigation is inferred from your
-files, [search](/docs/configuration/search) works in dev and production without a hosted
-service, and theming is a handful of tokens. Everything has a sensible default;
-configuration is something you reach for, not something you start with.
+A folder of docs is a complete project. There's no starter to clone, no Astro or Tailwind to set up, and no template to maintain. Navigation is inferred from your files, [search](/docs/configuration/search) works in dev and production without a hosted service, and theming is a handful of tokens. Everything has a sensible default; configuration is something you reach for, not something you start with.
 
 ### Type-safe to the core
 
-Your [`blume.config.ts`](/docs/configuration) and every
-[`meta.ts`](/docs/content/meta) are real TypeScript — validated by a schema and
-authored with `defineConfig` and `defineMeta`. Your editor autocompletes every
-option and catches typos, invalid values, and missing fields as you type, long
-before a build. Configuration is code you can refactor, compute, and trust — not
-loosely-typed YAML.
+Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/content/meta) are real TypeScript — validated by a schema and authored with `defineConfig` and `defineMeta`. Your editor autocompletes every option and catches typos, invalid values, and missing fields as you type, long before a build. Configuration is code you can refactor, compute, and trust — not loosely-typed YAML.
 
 ## Everything included
 
-- **Components** — callouts, cards, steps, tabs, accordions, badges, file trees,
-  and parameter tables, usable in MDX with [no imports](/docs/content/components).
-- **Local search** — Orama works in dev and production; Pagefind is one flag away
-  for large sites. No hosted index.
-- **AI** — [`llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an
-  Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
+- **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with [no imports](/docs/content/components).
+- **Local search** — Orama works in dev and production; Pagefind is one flag away for large sites. No hosted index.
+- **AI** — [`llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
-- **Customization** — component overrides, React islands, custom pages, theme
-  tokens, and a source-component registry via `blume add`.
-- **Migration** — `blume migrate mintlify | starlight | nextra | fumadocs`.
-- **Eject** — `blume eject` produces a standalone Astro project that still uses
-  the `blume` package.
+- **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
+- **Migration** — [`blume migrate mintlify | starlight | nextra | fumadocs`](/docs/advanced/migrate), or run `blume dev` on a Mintlify project as-is with [bridge mode](/docs/advanced/bridge).
+- **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
 
 ## How it works
 
-The Blume CLI discovers your content, builds a content graph, and generates a
-hidden Astro project under `.blume/` that it drives for dev and build. The
-generated runtime is an implementation detail — you write Markdown, Blume handles
-the rest — until you choose to eject and own it.
+The Blume CLI discovers your content, builds a content graph, and generates a hidden Astro project under `.blume/` that it drives for dev and build. The generated runtime is an implementation detail — you write Markdown, Blume handles the rest — until you choose to eject and own it.
 
 ## Next steps