blume 0.3.0 → 0.4.0

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 zero client JavaScript. :::
 
 ```md
-:::info
-The core theme ships zero client JavaScript.
-:::
+:::info The core theme ships zero client JavaScript. :::
 ```
 
-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 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.
 
 ### 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`.
+- **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.
+- **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
 

package/docs/reference/cli.mdx

@@ -9,19 +9,19 @@ blume <command> [options]
 
 ## Commands
 
-| Command                | Description                                            |
-| ---------------------- | ------------------------------------------------------ |
-| `blume init`           | Scaffold a minimal project.                            |
-| `blume dev`            | Start the dev server with hot reload.                  |
-| `blume build`          | Build the static (or server) site.                     |
-| `blume preview`        | Preview the last build.                                |
-| `blume add <item>`     | Install a source component from the registry.          |
+| Command | Description |
+| --- | --- |
+| `blume init` | Scaffold a minimal project. |
+| `blume dev` | Start the dev server with hot reload. |
+| `blume build` | Build the static (or server) site. |
+| `blume preview` | Preview the last build. |
+| `blume add <item>` | Install a source component from the registry. |
 | `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
-| `blume sync`           | Re-fetch remote content sources and regenerate.        |
-| `blume eject`          | Promote the runtime into a standalone Astro app.       |
-| `blume check`          | Type-check the site with `astro check`.                |
-| `blume doctor`         | Diagnose config and content problems.                  |
-| `blume validate`       | Validate links across your content.                    |
+| `blume sync` | Re-fetch remote content sources and regenerate. |
+| `blume eject` | Promote the runtime into a standalone Astro app. |
+| `blume check` | Type-check the site with `astro check`. |
+| `blume doctor` | Diagnose config and content problems. |
+| `blume validate` | Validate links across your content. |
 
 ## Common flags
 
@@ -45,17 +45,11 @@ blume <command> [options]
 - `blume eject --yes` — skip the confirmation prompt.
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
-- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on
-  stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI
-  and editor integrations.
+- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI and editor integrations.
 
 ## Type-checking
 
-`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)
-over your project. It regenerates the `.blume` runtime, syncs Astro's content
-types, then reports any TypeScript errors — in your `blume.config.ts`, in custom
-`.astro` pages, and in the components they import. It exits non-zero when there
-are errors, so it works as a `typecheck` step in CI:
+`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) over your project. It regenerates the `.blume` runtime, syncs Astro's content types, then reports any TypeScript errors — in your `blume.config.ts`, in custom `.astro` pages, and in the components they import. It exits non-zero when there are errors, so it works as a `typecheck` step in CI:
 
 ```json title="package.json"
 {
@@ -65,8 +59,7 @@ are errors, so it works as a `typecheck` step in CI:
 }
 ```
 
-Add a `tsconfig.json` extending Astro's config to your project root so authored
-pages resolve `blume/*` imports and virtual modules like `blume:data`:
+Add a `tsconfig.json` extending Astro's config to your project root so authored pages resolve `blume/*` imports and virtual modules like `blume:data`:
 
 ```json title="tsconfig.json"
 {
@@ -81,11 +74,7 @@ Without a project `tsconfig.json`, only the generated runtime is checked.
 
 `blume validate` checks every link discovered in your content:
 
-- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real
-  page — broken ones are reported as errors.
-- **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on
-  the target page — misses are warnings.
+- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors.
+- **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on the target page — misses are warnings.
 - **Asset links** (`/logo.png`) are checked against the `public/` directory.
-- **External links** are only checked with `--external` (off by default since it
-  requires the network); dead links (404/410/unreachable) are errors, while
-  rate-limited or transient responses (403/429/5xx/timeout) are warnings.
+- **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.

package/docs/reference/frontmatter.mdx

@@ -64,8 +64,7 @@ search:
 
 ## Changelog
 
-Changelog entries (`type: changelog`) accept an optional `changelog` object for
-richer feed and display metadata:
+Changelog entries (`type: changelog`) accept an optional `changelog` object for richer feed and display metadata:
 
 ```yaml lineNumbers
 type: changelog
@@ -75,8 +74,6 @@ changelog:
   category: Features
 ```
 
-`date` may live here or at the top level — both feed the
-[changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the
-generated timeline page and feed.
+`date` may live here or at the top level — both feed the [changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the generated timeline page and feed.
 
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/integration.ts

@@ -1,10 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
 
+import type { AssetMount } from "../core/assets.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
+import { copyAssetMounts, serveAssetMounts } from "./static-assets.ts";
 
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
@@ -72,6 +75,13 @@ export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
   /** Page routes that have a raw-Markdown variant (the content manifest). */
   contentRoutes: string[];
+  /** Configured `deployment.base`, stripped from dev URLs before matching. */
+  base?: string;
+  /**
+   * `content.assets` mounts: top-level dirs served at the site root in dev and
+   * copied into the build output, so root-served assets need no relocation.
+   */
+  assets?: AssetMount[];
 }
 
 /**
@@ -83,13 +93,13 @@ export interface BlumeIntegrationOptions {
  * keep serving HTML.
  */
 const negotiateMarkdown =
-  (routes: ReadonlySet<string>) =>
+  (routes: ReadonlySet<string>, base?: string) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
     if (
       (req.method === "GET" || req.method === "HEAD") &&
       prefersMarkdown(req.headers.accept)
     ) {
-      const variant = markdownVariantUrl(req.url, routes);
+      const variant = markdownVariantUrl(req.url, routes, base);
       if (variant) {
         res.setHeader("Vary", "Accept");
         req.url = variant;
@@ -108,6 +118,12 @@ export const blumeIntegration = (
   options: BlumeIntegrationOptions
 ): AstroIntegration => ({
   hooks: {
+    "astro:build:done": async ({ dir }) => {
+      // Copy in-place asset mounts into the build output, mirroring publicDir.
+      if (options.assets?.length) {
+        await copyAssetMounts(options.assets, fileURLToPath(dir));
+      }
+    },
     "astro:config:setup": ({ injectRoute }) => {
       for (const page of options.pages) {
         injectRoute({
@@ -124,9 +140,16 @@ export const blumeIntegration = (
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({
-        handle: negotiateMarkdown(new Set(options.contentRoutes)),
+        handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
         route: "",
       });
+      // Serve `content.assets` mounts (Astro only serves publicDir in dev).
+      if (options.assets?.length) {
+        server.middlewares.stack.unshift({
+          handle: serveAssetMounts(options.assets),
+          route: "",
+        });
+      }
     },
   },
   name: "blume",

package/src/astro/islands.ts

@@ -105,9 +105,13 @@ export const discoverIslands = async (
       continue;
     }
     const name = base.replace(ISLAND_FILE, "");
-    if (!/^[A-Z]/u.test(name)) {
+    // The name is used verbatim as both an MDX tag and an unquoted object key
+    // in the generated island map, so it must be a plain PascalCase identifier
+    // — a `-`, `.`, or space (e.g. `Time-Picker.tsx`) would otherwise emit a
+    // syntax-error module and fail the whole build with no pointer to the file.
+    if (!/^[A-Z][A-Za-z0-9_]*$/u.test(name)) {
       warnings.push(
-        `Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`
+        `Island "${file}" must have a PascalCase identifier filename to be used in MDX (letters, digits, and underscores only, e.g. Counter.tsx → <Counter />); skipping it.`
       );
       continue;
     }

package/src/astro/markdown-negotiation.ts

@@ -50,7 +50,8 @@ export const prefersMarkdown = (accept: string | null | undefined): boolean => {
  */
 export const markdownVariantUrl = (
   rawUrl: string | null | undefined,
-  routes: ReadonlySet<string>
+  routes: ReadonlySet<string>,
+  base?: string
 ): string | null => {
   if (!rawUrl) {
     return null;
@@ -58,11 +59,24 @@ export const markdownVariantUrl = (
   const queryIndex = rawUrl.indexOf("?");
   const query = queryIndex === -1 ? "" : rawUrl.slice(queryIndex);
   const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+
+  // A non-root `deployment.base` prefixes the dev-server URL but not the logical
+  // content routes, so strip it before matching and re-add it to the variant.
+  const prefix = base && base !== "/" ? base.replace(/\/$/u, "") : "";
+  let path = rawPath;
+  if (prefix) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) {
+      path = path.slice(prefix.length) || "/";
+    } else {
+      return null;
+    }
+  }
+
   const pathname =
-    rawPath !== "/" && rawPath.endsWith("/") ? rawPath.slice(0, -1) : rawPath;
+    path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
   if (!routes.has(pathname)) {
     return null;
   }
   const target = pathname === "/" ? "/index" : pathname;
-  return `${target}.md${query}`;
+  return `${prefix}${target}.md${query}`;
 };

package/src/astro/pages.ts

@@ -21,7 +21,12 @@ export const discoverPages = async (
   return files.map((file) => {
     const rel = relative(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
-    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const parts = withoutExt.split("/");
+    // Only a trailing `index` maps to its parent dir; a folder literally named
+    // `index` (e.g. `index/foo.astro`) must keep its segment.
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });