blume 0.0.0 → 0.1.0

package/docs/01-quickstart.mdx

@@ -0,0 +1,99 @@
+---
+title: Quickstart
+description: Install Blume, scaffold a project, and ship your first page in minutes.
+sidebar:
+  label: Quickstart
+  order: 1
+---
+
+Go from an empty folder to a running docs site in a few commands. Blume needs
+**Node.js 22 or newer** and a `docs/` folder with at least one `.md` or `.mdx`
+file — there's nothing else to set up.
+
+## Install and run
+
+<Steps>
+  <Step title="Install Blume">
+    Add the package to a new or existing project.
+
+    ```package-install
+    npm i blume
+    ```
+
+  </Step>
+  <Step title="Scaffold a project">
+    `blume init` creates the minimum surface: a content folder and a config file.
+
+    ```bash
+    blume init
+    ```
+
+    ```txt
+    docs/
+      index.mdx
+    blume.config.ts
+    ```
+
+  </Step>
+  <Step title="Start the dev server">
+    Blume generates the runtime and serves your docs with hot reload.
+
+    ```bash
+    blume dev
+    ```
+
+  </Step>
+  <Step title="Build for production">
+    Static HTML is written to `dist/`, with a local search index built over it.
+
+    ```bash
+    blume build
+    ```
+
+  </Step>
+</Steps>
+
+:::tip
+Blume works with any package manager and never requires you to set up Astro or
+Tailwind yourself.
+:::
+
+## Write your first page
+
+Every page is Markdown or MDX with a little frontmatter — the `title` and
+`description` render as the page heading and intro automatically. Drop this into
+`docs/index.mdx`:
+
+```mdx docs/index.mdx lineNumbers
+---
+title: Introduction
+description: Welcome to my docs.
+---
+
+Welcome! Use **Markdown** and built-in components — no imports required:
+
+:::note
+Blume ships callouts, cards, tabs, steps, and more.
+:::
+```
+
+Save it, and the dev server reloads instantly. Navigation, search, and page
+metadata are inferred from your files as you add them — keep writing, and the
+site keeps up.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Configuration" href="/docs/configuration" icon="file">
+    Tune the title, theme, search, and deployment.
+  </Card>
+  <Card title="Components" href="/docs/content/components" icon="folder">
+    Explore the built-in component library.
+  </Card>
+  <Card title="AI" href="/docs/configuration/ai" icon="lightbulb">
+    Ship `llms.txt` and an Ask AI assistant.
+  </Card>
+  <Card title="Deployment" href="/docs/deployment" icon="rocket">
+    Go live on any static host.
+  </Card>
+</CardGroup>

package/docs/02-deployment.mdx

@@ -0,0 +1,129 @@
+---
+title: Deployment
+description: Deploy static docs to any host, or switch to server rendering with an adapter.
+sidebar:
+  label: Deployment
+  order: 2
+---
+
+## Deploy anywhere (static)
+
+`blume build` compiles your docs to plain HTML, CSS, and a local search index in
+`dist/`. There's no server to run — point any static host at the folder.
+
+| Setting          | Value         |
+| ---------------- | ------------- |
+| Build command    | `blume build` |
+| Output directory | `dist`        |
+| Node version     | 22 or newer   |
+
+These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon
+S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the
+host can run the build.
+
+A static build includes:
+
+- every docs and custom page as static HTML
+- a local search index (Orama by default, Pagefind opt-in)
+- a [`sitemap.xml`](/docs/configuration/seo#sitemap) and [`robots.txt`](/docs/configuration/seo#robots) when `deployment.site` is set
+- `llms.txt` and `llms-full.txt` for AI tools
+- redirect pages
+- prerendered [Open Graph images](/docs/configuration/seo#open-graph-images) when `seo.og.enabled` is on
+
+### Set your site URL
+
+Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On
+**Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the
+platform's environment at build time — no config required.
+
+Set `deployment.site` to override the detected value, or to provide one on hosts
+that don't expose it (GitHub Pages, S3, a custom CDN):
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  site: "https://docs.example.com",
+}
+```
+
+When detecting automatically, Blume prefers your stable production domain over
+per-deploy preview URLs, so the canonical origin stays put across deploys.
+
+During `blume dev`, the site URL falls back to your local dev server (e.g.
+`http://localhost:4321`) when none is set, so site-gated features — Open Graph
+images, canonicals, the sitemap — work out of the box. Builds never use this
+fallback, so production output is never pointed at localhost.
+
+## Preview locally
+
+Before you ship, preview the production build exactly as a static host would
+serve it:
+
+```bash
+blume build
+blume preview
+```
+
+## Subpath deploys
+
+Serving docs under a path like `example.com/docs`? Set `deployment.base` — common
+for GitHub Pages project sites. Internal links and assets are rewritten to
+include the base path.
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  base: "/docs",
+}
+```
+
+## Server rendering
+
+Static output covers most docs. Switch to server output when you need
+request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  output: "server",
+  adapter: "vercel",
+}
+```
+
+Choosing an adapter pulls in the matching Astro adapter automatically:
+
+| Adapter      | Package               | Use for                              |
+| ------------ | --------------------- | ------------------------------------ |
+| `vercel`     | `@astrojs/vercel`     | Vercel — the most polished path      |
+| `netlify`    | `@astrojs/netlify`    | Netlify Functions                    |
+| `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
+| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |
+
+On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching
+adapter automatically for server output — set `output: "server"` and deploy. Set
+`adapter` explicitly to override the detected value, or when self-hosting with
+`node`.
+
+A server build includes everything a static build does, plus any Astro endpoints
+or middleware you add. The `node` adapter produces a standalone server you can
+run directly.
+
+:::note
+Server features have their own configuration — for example, Ask AI needs a model
+API key. See the [AI guide](/docs/configuration/ai) for setup.
+:::
+
+## Redirects
+
+Map old URLs to new ones in `blume.config.ts`:
+
+```ts blume.config.ts
+redirects: [{ from: "/old", to: "/new", status: 301 }];
+```
+
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Static builds
+emit redirect pages; server builds handle redirects at request time.
+
+## Build summary
+
+Every build prints a summary — output mode, adapter, resolved site URL, search
+provider, redirect count, sitemap and `llms.txt` status, and any enabled server
+features — so you can confirm what shipped (including anything auto-detected)
+before you deploy.

package/docs/advanced/api-reference.mdx

@@ -0,0 +1,114 @@
+---
+title: OpenAPI / AsyncAPI
+description: Drop in an OpenAPI or AsyncAPI spec and get an interactive reference, rendered by Scalar.
+---
+
+Point Blume at an OpenAPI or AsyncAPI spec and it generates an interactive API
+reference — schemas, authentication, examples, and a request playground — on its
+own route. The reference is rendered by [Scalar](https://scalar.com), not by
+Blume: API reference isn't core to Blume, so the whole surface is delegated to a
+tool that has already solved its large edge-case space.
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+}
+```
+
+That mounts the reference at `/reference` and adds a header link to it. The
+`spec` is either an `http(s)` URL or a path to a local file in your project.
+
+:::note
+The reference mounts inside Blume's shell — your navbar stays on top — but the
+body is a **self-contained Scalar embed** with its own sidebar, search, and
+theme. By design it doesn't weave into Blume's content sidebar, site search, or
+`llms.txt`.
+:::
+
+## A local spec
+
+A relative path is resolved from your project root and inlined at build time, so
+nothing is copied into your source tree and the page works offline:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+}
+```
+
+Both JSON and YAML specs work; Scalar auto-detects the format.
+
+## Route
+
+`route` controls where the reference mounts (and the header link's target):
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  route: "/api",
+  spec: "./openapi.yaml",
+}
+```
+
+## Multiple specs
+
+Use `sources` to publish more than one spec. Each source gets its own route and
+header link. Give each a `label` (used for the link and to derive its route), or
+set an explicit `route`:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  sources: [
+    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
+    { label: "Admin API", route: "/admin", spec: "./admin.json" },
+  ],
+}
+```
+
+`spec` is shorthand for a single-entry `sources`, so you only reach for `sources`
+when you have more than one.
+
+## AsyncAPI
+
+Event-driven APIs use a sibling `asyncapi` block with the **same shape** — Scalar
+renders AsyncAPI through the same component. Only the default route differs
+(`/events`):
+
+```ts blume.config.ts lineNumbers
+asyncapi: {
+  enabled: true,
+  spec: "./asyncapi.yaml",
+}
+```
+
+:::warning
+Scalar's AsyncAPI support is still a work in progress — it renders channels,
+operations, messages, and a Models section, but there's **no interactive
+playground** for events yet. It improves upstream over time.
+:::
+
+## Theming
+
+By default Blume layers your [accent and radius](/docs/configuration/theming) onto
+Scalar's theme so the reference doesn't feel jarring. It's best-effort, not
+pixel-identical — Scalar carries its own design system. To pick a specific
+[Scalar theme](https://github.com/scalar/scalar) instead, set `theme`:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+  theme: "purple",
+}
+```
+
+## The playground and CORS
+
+Scalar's "Try it" playground calls your **target API directly from the
+browser** — Blume doesn't proxy the request. For it to succeed, the API must
+allow cross-origin requests from the docs site (send the appropriate
+`Access-Control-Allow-Origin` headers). This is a property of the API being
+documented, not of Blume.

package/docs/advanced/blog.mdx

@@ -0,0 +1,121 @@
+---
+title: Blog
+description: Publish posts as content, get an RSS feed and article structured data for free, and build a custom index page.
+---
+
+A blog in Blume is just content with a type. Mark a page `type: blog` and Blume
+gives it an RSS feed and richer article metadata automatically. Unlike the
+[changelog](/docs/advanced/changelog), there's no generated index page — you compose
+the landing page yourself, which keeps the design entirely in your hands.
+
+## Write a post
+
+A post is a regular `.md` or `.mdx` page with `type: blog` in its frontmatter. By
+convention posts live under `blog/`, but the type — not the folder — is what
+matters:
+
+```mdx blog/introducing-blume.mdx lineNumbers
+---
+title: Introducing Blume
+type: blog
+date: 2026-06-22
+description: Why we built a markdown-first docs framework.
+---
+
+Documentation should be fast, AI-ready, and zero-config — down to not needing a
+starter template at all. Here's the thinking behind Blume.
+```
+
+Give every post a `date` so feed items sort newest-first and carry a `pubDate`,
+and a `description` — it's used for both the feed summary and SEO.
+
+## The RSS feed
+
+Blume builds a blog feed at **`/blog/rss.xml`**, sorted newest-first by `date`.
+Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume
+then injects a `<link rel="alternate">` tag on every page so readers discover it
+automatically.
+
+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 `"blog"` from `rss.types` to skip the feed.
+
+## Structured data
+
+When [structured data](/docs/configuration/seo#structured-data) is on, each post is
+emitted as a schema.org **`BlogPosting`** with its description and publish date —
+the richer article type search engines expect for blog content.
+
+## Building an index
+
+Blume doesn't generate a `/blog` landing page, so you build one. The simplest
+option is a content page that links to each post by hand:
+
+```mdx blog/index.mdx lineNumbers
+---
+title: Blog
+description: News and writing from the team.
+---
+
+<CardGroup cols={2}>
+  <Card title="Introducing Blume" href="/blog/introducing-blume">
+    Why we built a markdown-first docs framework.
+  </Card>
+</CardGroup>
+```
+
+To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages)
+at `pages/blog/index.astro` that reads from Astro's `docs` content collection and
+pairs each entry with its route from `blume:data`:
+
+```astro pages/blog/index.astro lineNumbers
+---
+import { getCollection } from "astro:content";
+import data from "blume:data";
+
+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) => ({
+    date: entry.data.date,
+    description: entry.data.description,
+    href: routeById.get(entry.id),
+    title: entry.data.title,
+  }))
+  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
+---
+
+<ul>
+  {
+    posts.map((post) => (
+      <li>
+        <a href={post.href}>{post.title}</a>
+        <p>{post.description}</p>
+      </li>
+    ))
+  }
+</ul>
+```
+
+See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this
+in the full site layout.
+
+<CardGroup cols={2}>
+  <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">
+    Mount the blog index and read from blume:data.
+  </Card>
+  <Card title="SEO" href="/docs/configuration/seo" icon="file">
+    Feeds, Open Graph images, and structured data.
+  </Card>
+</CardGroup>

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>