blume 0.0.0 → 0.1.0

package/docs/advanced/custom-pages.mdx

@@ -0,0 +1,187 @@
+---
+title: Custom Pages
+description: Mount fully custom .astro routes alongside your docs and read your site's config, navigation, and content from the blume:data module.
+---
+
+Most of a Blume site is Markdown, but sometimes you need a route that _isn't_ a
+doc — a landing page, a pricing page, a hand-built blog or changelog index, or an
+interactive dashboard. Drop an `.astro` file under your **pages** folder and
+Blume mounts it as a real route, right alongside your content.
+
+## Add a page
+
+Create a `pages/` folder at your project root and add an `.astro` file:
+
+```astro pages/pricing.astro lineNumbers
+---
+import data from "blume:data";
+---
+
+<h1>Pricing for {data.config.title}</h1>
+```
+
+`blume dev` picks it up immediately and `blume build` prerenders it to static
+HTML. The folder name is configurable with [`content.pages`](/docs/configuration#content)
+(default `"pages"`).
+
+Custom pages keep their original location on disk, so relative imports, component
+imports, and [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths)
+all work exactly as they do in a plain Astro project — Blume mounts each file
+where it sits rather than copying it.
+
+## Files and routes
+
+Each file's path under the pages folder becomes its route. `index` maps to the
+parent folder, and dynamic `[param]` segments are preserved:
+
+| File                      | Route         |
+| ------------------------- | ------------- |
+| `pages/pricing.astro`     | `/pricing`    |
+| `pages/blog/index.astro`  | `/blog`       |
+| `pages/blog/[slug].astro` | `/blog/:slug` |
+| `pages/changelog.astro`   | `/changelog`  |
+
+A custom page **wins** over a generated route at the same path. Adding
+`pages/changelog.astro`, for example, replaces Blume's
+[generated changelog timeline](/docs/advanced/changelog) with your own.
+
+## Reading site data
+
+Import `blume:data` to read the same resolved config, navigation, routes, and
+feeds the rest of the site uses:
+
+```astro pages/all-pages.astro lineNumbers
+---
+import data from "blume:data";
+---
+
+<h1>All pages</h1>
+<ul>
+  {
+    data.routes
+      .filter((route) => route.indexable)
+      .map((route) => (
+        <li>
+          <a href={route.path}>{route.title}</a>
+        </li>
+      ))
+  }
+</ul>
+```
+
+The module exposes:
+
+<TypeTable
+  type={{
+    config: {
+      type: "object",
+      required: true,
+      description:
+        "Resolved site config — title, description, logo, banner, theme, site URL, repoUrl, and search settings.",
+    },
+    navigation: {
+      type: "object",
+      required: true,
+      description: "The sidebar and tab tree inferred from your content.",
+    },
+    routes: {
+      type: "Route[]",
+      required: true,
+      description:
+        "Every content page: { id, path, title, indexable, hidden, draft, editUrl }.",
+    },
+    feeds: {
+      type: "Feed[]",
+      required: true,
+      description: "Generated RSS feeds: { href, title }.",
+    },
+  }}
+/>
+
+`routes` carries page metadata but not frontmatter like `type` or `date`. To
+build a list filtered by content type — a blog or changelog index — pair it with
+Astro's `docs` content collection, which holds the frontmatter:
+
+```astro pages/blog/index.astro lineNumbers
+---
+import { getCollection } from "astro:content";
+import data from "blume:data";
+
+// Each route's id matches its collection entry id.
+const routeById = new Map(data.routes.map((route) => [route.id, route.path]));
+
+const posts = (await getCollection("docs"))
+  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
+  .map((entry) => ({
+    description: entry.data.description,
+    href: routeById.get(entry.id),
+    title: entry.data.title,
+  }));
+---
+
+<ul>
+  {
+    posts.map((post) => (
+      <li>
+        <a href={post.href}>{post.title}</a>
+        <p>{post.description}</p>
+      </li>
+    ))
+  }
+</ul>
+```
+
+## Using the site layout
+
+To give a custom page the full Blume chrome — header, sidebar, search, and theme
+— wrap it in `RootLayout`, the same layout the generated pages use. Pull the
+required props straight from `blume:data`:
+
+```astro pages/pricing.astro lineNumbers
+---
+import RootLayout from "blume/components/layout/RootLayout.astro";
+import data from "blume:data";
+---
+
+<RootLayout
+  site={{ title: data.config.title, description: data.config.description }}
+  logo={data.config.logo}
+  banner={data.config.banner}
+  navigation={data.navigation}
+  page={{ title: "Pricing", route: "/pricing" }}
+  headings={[]}
+  themeMode={data.config.theme.mode}
+  searchEnabled={data.config.search.enabled}
+  searchProvider={data.config.search.provider}
+  indexable={true}
+>
+  <h1>Pricing</h1>
+</RootLayout>
+```
+
+:::note
+`RootLayout` is part of the generated runtime, so its props can change between
+releases. When you want a layout that's fully yours,
+[`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a
+standard Astro project you own outright.
+:::
+
+## Interactive pages
+
+Custom pages are ordinary Astro, so you can drop in React (or any framework)
+[islands](/docs/configuration/customization#react-islands) with a hydration directive.
+React switches on automatically the moment your project contains a `.tsx` or
+`.jsx` file.
+
+<CardGroup cols={2}>
+  <Card
+    title="Customization"
+    href="/docs/configuration/customization"
+    icon="file"
+  >
+    Component overrides, React islands, the registry, and eject.
+  </Card>
+  <Card title="Blog" href="/docs/advanced/blog" icon="book-open">
+    Author posts and build a custom blog index.
+  </Card>
+</CardGroup>

package/docs/advanced/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  order: 5,
+  pages: ["custom-pages", "changelog", "blog", "api-reference"],
+  title: "Advanced",
+});

package/docs/changelog/v0-1-0.mdx

@@ -0,0 +1,12 @@
+---
+title: v0.1.0
+type: changelog
+date: 2026-06-01
+changelog:
+  version: 0.1.0
+  category: Release
+---
+
+The first public release of Blume — a markdown-first docs framework on Astro and
+Vite. Drop in Markdown or MDX, run `blume dev`, and ship a production-grade docs
+site with search, theming, and AI-ready output.

package/docs/changelog/v0-2-0.mdx

@@ -0,0 +1,16 @@
+---
+title: v0.2.0
+type: changelog
+date: 2026-06-24
+changelog:
+  version: 0.2.0
+  category: Features
+---
+
+A big batch of built-in components landed: **columns**, **frames**, **trees**,
+**tooltips**, **code groups**, **panels**, **tiles**, and **fields**. Code groups
+now render as proper language tabs, and the changelog gets this timeline.
+
+- New `Accordion` / `AccordionItem`, `Expandable`, `Tooltip`, `Frame`, `Color`
+- `CodeGroup` tabs with flush code blocks
+- Redesigned `Prompt` with a copy-to-clipboard button

package/docs/configuration/ai.mdx

@@ -0,0 +1,228 @@
+---
+title: AI
+description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
+---
+
+Blume has several opt-in AI features: machine-readable docs for external tools
+(`llms.txt`), an in-page **Ask AI** assistant, and a hosted **MCP server** for
+coding agents. Everything is off by default, and static docs stay fully static
+until you turn a feature on.
+
+## llms.txt
+
+Emit machine-readable versions of your docs that coding agents and chat
+assistants can consume:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  llmsTxt: true,
+}
+```
+
+With this on, `blume build` writes two files to the root of your site:
+
+- **`/llms.txt`** — a compact index: your site title and description, then a
+  linked list of every page with its summary.
+- **`/llms-full.txt`** — the entire corpus: each page's full Markdown body, with
+  its source URL, in one file.
+
+Draft pages are excluded. Set [`deployment.site`](/docs/deployment) so the links and
+source URLs resolve to absolute addresses.
+
+## Raw Markdown
+
+Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source —
+perfect for LLMs, coding agents, and "copy as Markdown" workflows. It's available
+for every page, in dev and production, with no configuration.
+
+| URL               | Returns                 |
+| ----------------- | ----------------------- |
+| `/quickstart`     | The rendered page       |
+| `/quickstart.md`  | The raw Markdown source |
+| `/quickstart.mdx` | The raw Markdown source |
+
+Nested routes work the same way (`/content/syntax.md`), and the home page is
+served at `/index.md`.
+
+## Copy as Markdown
+
+Every page carries a **Copy as Markdown** action — in the [page
+actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the
+page's raw Markdown to the clipboard. It's the same source served at the [`.md`
+URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes.
+It's available on every page, in dev and production, with no configuration.
+
+## Open in chat
+
+The **Open in chat** action opens the current page in an AI assistant — v0,
+ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points
+it at the page's raw Markdown so it can answer questions about what you're
+reading:
+
+> Read `https://your-site/this-page.md` so I can ask you questions about this
+> page.
+
+Like Copy as Markdown, it needs no setup. The assistant fetches the page over its
+public URL, so it works as soon as the page is deployed.
+
+To embed a ready-to-copy prompt inline in your content — rather than a whole-page
+action — use the [Prompt component](/docs/content/components#prompt), which renders
+a labelled row with a **Copy prompt** button and an optional open-in-Cursor link.
+
+## Ask AI
+
+Add an assistant that answers reader questions in an in-page chat panel, backed
+by a streaming server endpoint and the [AI SDK](https://ai-sdk.dev):
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "gateway", // default
+    model: "openai/gpt-5.5",
+  },
+}
+```
+
+### Server output required
+
+Ask AI is a server route (`POST /api/ask`), so it can't run on a static build.
+Switch to server output and pick an adapter:
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  output: "server",
+  adapter: "vercel",
+}
+```
+
+A static build with Ask AI enabled fails fast with a message telling you to set
+`deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
+
+### Backends
+
+By default Ask AI routes through the **Vercel AI Gateway**: `model` is a
+`provider/model` string, so you switch models by changing it (`openai/gpt-5.5`,
+`anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The
+gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up
+automatically when you deploy on Vercel.
+
+Set `provider` to point Ask AI somewhere else. Each backend reads its API key
+from an environment variable, and the matching provider SDK is added to your
+project's runtime automatically when you build — only the one you use:
+
+| `provider`          | `model`                                       | API key env var      |
+| ------------------- | --------------------------------------------- | -------------------- |
+| `gateway` (default) | a `provider/model` string via the AI Gateway  | `AI_GATEWAY_API_KEY` |
+| `openrouter`        | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` |
+| `llmgateway`        | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` |
+| `inkeep`            | an [Inkeep](https://inkeep.com) QA model      | `INKEEP_API_KEY`     |
+| `openai-compatible` | whatever your endpoint serves                 | set with `apiKeyEnv` |
+
+For example, to use OpenRouter:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "openrouter",
+    model: "anthropic/claude-sonnet-4-5",
+  },
+}
+```
+
+Any OpenAI-compatible endpoint works through `openai-compatible` — supply the
+`baseUrl` and the env var holding its key:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "openai-compatible",
+    baseUrl: "https://my-gateway.example.com/v1",
+    apiKeyEnv: "MY_GATEWAY_API_KEY",
+    model: "gpt-4o",
+  },
+}
+```
+
+Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point
+at a different env var or proxy.
+
+:::note
+**Inkeep** answers from the content you've indexed in the Inkeep dashboard — it
+runs its own retrieval — rather than from this site's pages. The other backends
+are plain model passthroughs: the endpoint streams the reader's messages straight
+to the model.
+:::
+
+Keys are read with `process.env`, which covers the Node, Vercel, and Netlify
+adapters. On Cloudflare, expose the key through the platform's [runtime
+binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets).
+Enabling Ask AI also turns on React for the in-page island — see
+[Customization](/docs/configuration/customization#react-islands).
+
+## MCP server
+
+Host a [Model Context Protocol](https://modelcontextprotocol.io) server so coding
+agents (Claude Code, Cursor, VS Code, claude.ai connectors) can search and read
+your docs directly — no scraping:
+
+```ts blume.config.ts lineNumbers
+mcp: {
+  enabled: true,
+  route: "/mcp", // where the server is mounted
+}
+```
+
+| Option         | Default | Description                                       |
+| -------------- | ------- | ------------------------------------------------- |
+| `enabled`      | `false` | Generate and host the MCP server.                 |
+| `route`        | `/mcp`  | Path the Streamable-HTTP endpoint is mounted on.  |
+| `name`         | title   | Server name shown to clients (defaults to title). |
+| `instructions` | —       | Optional system hint passed to connecting agents. |
+
+The server exposes four read-only tools — `search_docs`, `get_page`,
+`list_pages`, and `get_navigation` — and publishes discovery documents at
+`/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's
+**Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, and
+VS Code (shown once [`deployment.site`](/docs/deployment) is set).
+
+`search_docs` runs its own full-text index, so it works regardless of your
+[search](/docs/configuration/search) provider — and even when search is set to
+`none`. The MCP server is a separate feature from on-page search.
+
+### Server output required
+
+The MCP server is a live endpoint (`/mcp`), so it can't run on a static build.
+Switch to server output and pick an adapter:
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  output: "server",
+  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
+  site: "https://docs.example.com",
+}
+```
+
+A static build with `mcp.enabled` fails fast with a message telling you to set
+`deployment.output` to `server`. See [Deployment](/docs/deployment) for the
+adapters. Once deployed, connect from Claude Code with:
+
+```bash
+claude mcp add --transport http my-docs https://docs.example.com/mcp
+```
+
+## Agent skill
+
+Building a Blume site with the help of a coding agent? Install the Blume
+[agent skill](https://docs.claude.com/en/docs/claude-code/skills) so it knows
+how Blume works without you explaining it:
+
+```bash
+npx skills add haydenbleasel/blume
+```
+
+The skill teaches the agent what Blume is and how to scaffold, write, and
+configure a site, and points it at the full docs bundled in the installed
+package (`node_modules/blume/docs`).

package/docs/configuration/analytics.mdx

@@ -0,0 +1,98 @@
+---
+title: Analytics
+description: First-party web analytics — Vercel Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
+---
+
+Blume injects analytics for you from a single `analytics` block in
+`blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a
+`scripts` escape hatch covers every other provider — Plausible, Fathom, Google
+Analytics, Umami, and the rest.
+
+Analytics loads in **production builds only**. The scripts are emitted by
+`blume build`, never by `blume dev`, so local traffic never reaches your
+dashboards and you don't need a separate "development" project.
+
+:::note
+Analytics is opt-in. With no `analytics` block, Blume injects nothing.
+:::
+
+## Vercel Web Analytics
+
+Set `vercel: true` to add [Vercel Web Analytics](https://vercel.com/docs/analytics).
+Blume injects Vercel's first-party script, which is served from your own domain
+once Web Analytics is enabled for the project in the Vercel dashboard.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  vercel: true,
+}
+```
+
+No keys are needed — the script reports to the project it's deployed under. This
+only collects data on Vercel deployments, where the `/_vercel/insights` endpoint
+exists.
+
+## PostHog
+
+Provide your **project API key** to add [PostHog](https://posthog.com). The host
+defaults to PostHog Cloud US; set `host` for EU Cloud
+(`https://eu.i.posthog.com`) or a self-hosted instance.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  posthog: {
+    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    host: "https://us.i.posthog.com", // optional, this is the default
+  },
+}
+```
+
+The project API key is safe to ship to the browser — it's a public,
+write-only key.
+
+## Custom scripts
+
+Use `scripts` to load any other analytics provider. Each entry renders one
+`<script>` tag and must set **exactly one** of `src` (external) or `content`
+(inline).
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  scripts: [
+    // Plausible
+    {
+      src: "https://plausible.io/js/script.js",
+      strategy: "defer",
+      attributes: { "data-domain": "example.com" },
+    },
+    // Fathom
+    {
+      src: "https://cdn.usefathom.com/script.js",
+      strategy: "defer",
+      attributes: { "data-site": "ABCDEFG" },
+    },
+    // An inline snippet
+    {
+      content: "console.log('analytics ready')",
+    },
+  ],
+}
+```
+
+`attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto
+the tag, and `strategy` adds `async` or `defer` to external scripts.
+
+## Options
+
+| Option                 | Default                    | Description                                             |
+| ---------------------- | -------------------------- | ------------------------------------------------------- |
+| `vercel`               | `false`                    | Add Vercel Web Analytics (Vercel deployments only).     |
+| `posthog.key`          | —                          | PostHog project API key. Enables PostHog when set.      |
+| `posthog.host`         | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted).       |
+| `scripts[].src`        | —                          | External script URL. Mutually exclusive with `content`. |
+| `scripts[].content`    | —                          | Inline script body. Mutually exclusive with `src`.      |
+| `scripts[].strategy`   | —                          | `async` or `defer` for an external script.              |
+| `scripts[].attributes` | —                          | Extra HTML attributes spread onto the `<script>` tag.   |
+
+All three can be combined — enable Vercel, PostHog, and custom scripts together.
+For deploying your built site, see [Deployment](/docs/deployment).

package/docs/configuration/customization.mdx

@@ -0,0 +1,91 @@
+---
+title: Customization
+description: Override components, add interactive islands, mount custom pages, install registry components, or eject.
+---
+
+## Component overrides
+
+Add a `components.ts` (or `components.tsx`) to your project root and export
+`defineComponents`. The `mdx` map either **replaces** a built-in component or
+**adds** a new one — available in every `.mdx` page with no import.
+
+```ts components.ts lineNumbers
+import { defineComponents } from "blume";
+import Callout from "./components/Callout.astro";
+import Pricing from "./components/Pricing.astro";
+
+export default defineComponents({
+  mdx: {
+    Callout, // replace the built-in Callout
+    Pricing, // add a new <Pricing /> component
+  },
+});
+```
+
+Keys are the names you write in MDX (`<Callout>`, `<Pricing>`). Use the `.tsx`
+filename when you import React components.
+
+## Interactive islands
+
+For interactive UI (React, Vue, or Svelte), drop a component into an `islands/`
+folder and use it in any MDX page — Blume hydrates it for you, no wrapper or
+registration needed:
+
+```tsx islands/Counter.tsx lineNumbers
+import { useState } from "react";
+
+export default function Counter() {
+  const [n, setN] = useState(0);
+  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
+}
+```
+
+```mdx page.mdx
+Use it anywhere: <Counter />
+```
+
+See [Islands](/docs/content/islands) for hydration strategies and framework
+setup.
+
+## Custom pages
+
+Add `.astro` files under your `pages/` folder to mount fully custom routes
+alongside your docs — a landing page, a pricing page, or a hand-built index. They
+keep their location, so relative imports and `getStaticPaths` work as usual, and
+they can read your config, navigation, and routes from the `blume:data` module.
+
+See [Custom Pages](/docs/advanced/custom-pages) for the full guide.
+
+## Registry
+
+`blume add` copies a Blume-maintained component into your project as **source** —
+you own it and can edit it freely. Run it with no arguments to list what's
+available:
+
+```bash
+blume add
+```
+
+Install a widget, or any built-in layout slot you want to customize — the
+header, sidebar, breadcrumbs, table of contents, or pagination:
+
+```bash
+blume add pagination
+```
+
+The copy imports the rest of the framework from `blume/*`, so it renders
+exactly like the built-in until you change it. `blume add` prints the
+`defineComponents` snippet to register it under the matching layout slot.
+
+## Eject
+
+When you want full control, eject the generated runtime into a standalone Astro
+project:
+
+```bash
+blume eject --yes
+```
+
+Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app
+you own and can modify directly. The `blume` package stays importable, so you
+keep its components, theme, and Markdown processors.