blume 0.0.0 → 0.1.1

package/docs/advanced/changelog.mdx

@@ -0,0 +1,113 @@
+---
+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.
+
+## 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:
+
+```mdx changelog/v1-2-0.mdx lineNumbers
+---
+title: v1.2.0
+type: changelog
+date: 2026-06-20
+changelog:
+  version: 1.2.0
+  category: Features
+---
+
+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.
+
+### The `changelog` object
+
+The optional `changelog` object adds richer metadata for the timeline and feed:
+
+<TypeTable
+  type={{
+    "changelog.version": {
+      type: "string",
+      description:
+        "Release version. Falls back to a v-prefixed label when there's no title.",
+    },
+    "changelog.category": {
+      type: "string",
+      description:
+        "Shown as a tag beside the entry, e.g. Release, Features, Fixes.",
+    },
+    "changelog.date": {
+      type: "string",
+      description:
+        "Publish date. May live here or at the top level — both feed the timeline and RSS 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:
+
+- 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 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.
+
+The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  rss: {
+    enabled: true,
+    types: ["blog", "changelog"],
+    limit: 50,
+  },
+}
+```
+
+Remove `"changelog"` from `rss.types` to skip the feed while keeping the timeline.
+
+## 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.
+
+<CardGroup cols={2}>
+  <Card
+    title="Frontmatter"
+    href="/docs/reference/frontmatter#changelog"
+    icon="file"
+  >
+    The full changelog frontmatter schema.
+  </Card>
+  <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">
+    Replace the generated timeline with your own layout.
+  </Card>
+</CardGroup>

package/docs/advanced/custom-pages.mdx

@@ -0,0 +1,268 @@
+---
+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>
+```
+
+Inside a Blume project the module is typed automatically. You can also pull the
+shape in explicitly — for typed helpers, props, or your own tsconfig — with
+`import type { BlumeData } from "blume"`:
+
+```ts
+import type { BlumeData, BlumeRoute } from "blume";
+
+const indexable = (data: BlumeData): BlumeRoute[] =>
+  data.routes.filter((route) => route.indexable);
+```
+
+The module exposes:
+
+<TypeTable
+  type={{
+    config: {
+      type: "BlumeDataConfig",
+      required: true,
+      description:
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, og, analytics, feedback, structuredData, codeWrap, and imageZoom.",
+    },
+    navigation: {
+      type: "Navigation",
+      required: true,
+      description:
+        "The sidebar, tabs, and selectors inferred from your content (default locale).",
+    },
+    navigationByLocale: {
+      type: "Record<string, Navigation>",
+      required: true,
+      description:
+        "Per-locale navigation trees, keyed by locale code. Empty unless i18n is configured.",
+    },
+    routes: {
+      type: "BlumeRoute[]",
+      required: true,
+      description:
+        "Every content page: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }.",
+    },
+    feeds: {
+      type: "BlumeFeed[]",
+      required: true,
+      description: "Generated RSS feeds: { href, title }.",
+    },
+    fontCssVars: {
+      type: "string[]",
+      required: true,
+      description:
+        "CSS variable names for the configured fonts (Astro <Font> integration).",
+    },
+    ui: {
+      type: "UIStrings",
+      required: true,
+      description:
+        "Resolved UI chrome strings for the default locale (search, sidebar, and footer labels).",
+    },
+    uiByLocale: {
+      type: "Record<string, UIStrings>",
+      required: true,
+      description:
+        "Per-locale UI strings, keyed by locale code. Empty unless i18n is configured.",
+    },
+  }}
+/>
+
+`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
+
+`RootLayout` gives a custom page the full docs chrome — header, sidebar, search,
+TOC, and theme — by wrapping it in the same 3-column grid the generated pages
+use. For a landing or marketing page that grid is in the way, so reach for
+**`PageLayout`** instead: it provides the document shell, header, theme, and
+fonts, then a single full-width `<slot />` (no sidebar, no prose, no TOC). An
+optional `footer` slot renders after `<main>`:
+
+```astro pages/index.astro lineNumbers
+---
+import PageLayout from "blume/components/layout/PageLayout.astro";
+import data from "blume:data";
+import Footer from "./_home/Footer.astro";
+
+const { config } = data;
+---
+
+<PageLayout
+  site={{ title: config.title, description: config.description }}
+  logo={config.logo}
+  banner={config.banner}
+  analytics={config.analytics}
+  navigation={data.navigation}
+  favicon={config.favicon}
+  fontCssVars={data.fontCssVars}
+  themeMode={config.theme.mode}
+  searchEnabled={config.search.enabled}
+  siteUrl={config.site}
+  ogEnabled={config.og.enabled}
+  page={{ title: "Acme — the fastest docs", description: config.description }}
+>
+  <section class="mx-auto max-w-5xl px-6 py-24">
+    <h1>Build docs that fly</h1>
+  </section>
+  <Footer slot="footer" />
+</PageLayout>
+```
+
+Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a
+generated `og:image` automatically: Blume renders an Open Graph card for every
+static custom page — the home included, the most-shared URL — served at
+`/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title
+with the description as its eyebrow; a deeper page is titled from its last path
+segment. Set `ogImage` or `canonical` explicitly to override.
+
+`page.title` is used verbatim as the document title (no `- siteTitle` suffix),
+since marketing pages usually set their own. To give a custom page the full docs
+chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the 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`).