blume 0.0.0 → 0.1.1

package/docs/configuration/search.mdx

@@ -0,0 +1,172 @@
+---
+title: Search
+description: Client-side search out of the box, with optional hosted and semantic backends.
+---
+
+Blume ships local search with no hosted infrastructure and no API keys. It runs
+in the browser, works in both `blume dev` and `blume build`, and indexes only
+your real content — navigation chrome and excluded pages are skipped. When you
+outgrow it, you can switch to a hosted or semantic backend without changing how
+search looks or behaves — only the `search.provider` you configure changes.
+
+Blume reaches parity with Fumadocs' provider set: **Orama**, **FlexSearch**,
+**Algolia**, **Orama Cloud**, **Typesense**, and **Mixedbread** (plus
+**Pagefind**). Only the configured provider's SDK is installed into your project,
+so picking one backend never pulls in the others.
+
+## Using search
+
+Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/`
+when you're not typing in a field. `Esc` closes it.
+
+Queries match page **titles**, **descriptions**, and **body text**, with title
+matches ranked highest and descriptions above body.
+
+## What's indexed
+
+For every indexable page, Blume indexes its title, description, and body reduced
+to plain text — code blocks, images, and markup are stripped, so results stay
+relevant. The index is built from your source files, so it's identical in dev and
+production.
+
+## Providers
+
+The client-side providers are keyless and need no extra config. The hosted ones
+take **public** credentials in `blume.config.ts` (safe to ship to the browser)
+and read their **secret** admin key from an environment variable at build time —
+the secret never lands in the config or the client bundle.
+
+### Orama (default)
+
+Blume's default engine. It builds a JSON index served at `/blume-search.json` and
+queries it in the browser — instant, client-side, and live in `blume dev` as you
+edit. No keys, no service.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "orama", // default
+}
+```
+
+### FlexSearch
+
+A second keyless, client-side option. It reuses the same `/blume-search.json`
+index Orama ships and builds a [FlexSearch](https://github.com/nextapps-de/flexsearch)
+document index in the browser. Works in `blume dev` and `blume build`.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "flexsearch",
+}
+```
+
+### Pagefind
+
+For very large docs, opt into [Pagefind](https://pagefind.app). It indexes your
+built HTML and loads the index in shards on demand, keeping the initial payload
+tiny no matter how big the site grows.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "pagefind",
+}
+```
+
+Pagefind only runs during `blume build`, so search isn't available in `blume dev`
+with this provider.
+
+### Algolia
+
+The browser queries [Algolia](https://www.algolia.com) directly with your
+search-only key. Each `blume build` uploads the index using the admin key from
+`ALGOLIA_ADMIN_API_KEY` (the build warns and skips the upload if it's unset).
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "algolia",
+  algolia: {
+    appId: "YOUR_APP_ID",
+    indexName: "docs",
+    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
+  },
+}
+```
+
+### Orama Cloud
+
+Hosted Orama. The browser queries your index endpoint with the public API key;
+`blume build` pushes records to the index using `ORAMA_PRIVATE_API_KEY`. Set
+`indexId` to enable the sync.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "orama-cloud",
+  oramaCloud: {
+    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
+    apiKey: "YOUR_PUBLIC_API_KEY",
+    indexId: "your-index-id", // for the build-time sync
+  },
+}
+```
+
+### Typesense
+
+Self-hosted or cloud [Typesense](https://typesense.org). The browser queries the
+collection with the search-only key; `blume build` creates the collection (if
+needed) and imports documents using `TYPESENSE_ADMIN_API_KEY`.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "typesense",
+  typesense: {
+    host: "xyz.a1.typesense.net",
+    collection: "docs",
+    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
+    // port + protocol default to 443 / https
+  },
+}
+```
+
+### Mixedbread
+
+Semantic search via [Mixedbread](https://www.mixedbread.com). Queries are proxied
+through a generated `/api/search` endpoint that holds your key, so this provider
+**requires server output** (`deployment.output: "server"`). The endpoint reads
+`MIXEDBREAD_API_KEY`. Sync your content to the store with the Mixedbread CLI in
+your build, e.g. `mxbai vs sync <STORE_ID> ./content --ci`.
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "mixedbread",
+  mixedbread: {
+    storeId: "YOUR_STORE_ID",
+  },
+}
+```
+
+### Disabling search
+
+```ts blume.config.ts lineNumbers
+search: {
+  provider: "none",
+}
+```
+
+## Excluding pages
+
+Only indexable pages are searched. A page is left out of the index when it sets
+`search.exclude` in frontmatter:
+
+```yaml
+search:
+  exclude: true
+```
+
+[Hidden pages](/docs/content/navigation#hidden-pages) are also excluded by default.
+To index them anyway, opt in:
+
+```ts blume.config.ts lineNumbers
+search: {
+  indexing: { includeHiddenPages: true },
+}
+```

package/docs/configuration/seo.mdx

@@ -0,0 +1,196 @@
+---
+title: SEO
+description: Metadata, Open Graph images, RSS feeds, and JSON-LD — Blume's discoverability layer, grouped under one seo config.
+sidebar:
+  label: SEO
+---
+
+Blume handles the discoverability layer for you: page metadata, social share
+images, feeds, and structured data. The three configurable features live under
+the `seo` key in `blume.config.ts`; metadata is driven by your content.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: { enabled: true },
+  rss: { enabled: true, types: ["blog", "changelog"] },
+  sitemap: true,
+  robots: true,
+  structuredData: true,
+}
+```
+
+Most of this is sharper with an absolute site URL — set
+[`deployment.site`](/docs/deployment) so feeds, OG images, canonicals, the sitemap,
+and JSON-LD can emit full URLs.
+
+## Metadata
+
+Every page renders the standard `<head>` tags from your config and frontmatter:
+
+- `<title>` — the page title plus your site `title`.
+- `<meta name="description">` and `og:description` — the page `description`,
+  falling back to the site `description`.
+- `og:title` — the page title.
+- `<link rel="canonical">` — the page's absolute URL (when `deployment.site` is
+  set).
+
+Override any of these per page with `seo` frontmatter:
+
+```yaml lineNumbers
+---
+title: Pricing
+description: Plans and pricing for every team size.
+seo:
+  title: Pricing — Acme
+  canonical: https://acme.com/pricing
+  noindex: false
+---
+```
+
+<TypeTable
+  type={{
+    "seo.title": {
+      type: "string",
+      description: "Override the <title> and og:title for this page.",
+    },
+    "seo.description": {
+      type: "string",
+      description: "Override the meta + og:description.",
+    },
+    "seo.image": {
+      type: "string",
+      description: "Custom social image (see Open Graph).",
+    },
+    "seo.canonical": {
+      type: "string",
+      description: "Override the canonical URL.",
+    },
+    "seo.noindex": {
+      type: "boolean",
+      description: "Emit robots noindex and skip structured data.",
+    },
+  }}
+/>
+
+## Open Graph images
+
+Blume can render a 1200×630 social card for every page at build time — no
+headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay
+fast. On by default once [`deployment.site`](/docs/deployment) is set or
+auto-detected (the `og:image` URL has to be absolute to be useful to crawlers),
+and off otherwise. Set `enabled` to override that either way:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: { enabled: true }, // or false to opt out even with a site set
+}
+```
+
+Each card is derived from your content and theme — the **page title** as the
+headline, your **site title** as the eyebrow, and your theme **accent** for the
+mark. Images are served at `/og/<slug>.png`, mirroring each route, and are
+prerendered as static files even in server mode:
+
+| Page route          | Image URL                  |
+| ------------------- | -------------------------- |
+| `/`                 | `/og/index.png`            |
+| `/quickstart`       | `/og/quickstart.png`       |
+| `/configuration/ai` | `/og/configuration/ai.png` |
+
+Override the generated card for any page with `seo.image` — a file in `public/`
+or an external URL. It takes precedence over the generated card and works even
+when `og` is off, so you can mix custom images with generated ones:
+
+```yaml lineNumbers
+---
+title: Pricing
+seo:
+  image: /og/pricing-custom.png
+---
+```
+
+:::note
+OG rendering uses hex internally, so an `oklch` custom accent falls back to the
+default. Use a named accent (`blue`, `teal`, …) or a hex value for custom cards.
+:::
+
+## RSS feeds
+
+Blume builds an RSS feed for each content type in `rss.types` — `blog` and
+`changelog` by default — that has pages, served at `/<type>/rss.xml`. See
+[Feeds](/docs/content#feeds) for authoring blog and changelog entries with dates.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  rss: {
+    enabled: true,
+    types: ["blog", "changelog"],
+    limit: 50,
+  },
+}
+```
+
+| Option    | Default                 | Description                           |
+| --------- | ----------------------- | ------------------------------------- |
+| `enabled` | `true`                  | Generate feeds.                       |
+| `types`   | `["blog", "changelog"]` | Content types that each get a feed.   |
+| `limit`   | `50`                    | Maximum items per feed, newest first. |
+
+Blume injects `<link rel="alternate">` tags so browsers and feed readers discover
+the feeds automatically.
+
+## Structured data
+
+Blume emits [schema.org](https://schema.org) JSON-LD in every page's `<head>` so
+search engines understand your content. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  structuredData: true,
+}
+```
+
+Each page includes:
+
+- a **WebSite** node for site identity,
+- the page as an **article** — `BlogPosting` for blog posts, `TechArticle` for
+  changelog and docs — with its description and publish date,
+- a **BreadcrumbList** built from the navigation trail.
+
+URLs are absolute when `deployment.site` is set. Pages marked `seo.noindex` are
+skipped.
+
+## Sitemap
+
+Blume writes a `sitemap.xml` of every indexable page at build time. It needs an
+absolute [`deployment.site`](/docs/deployment) and lists every page except drafts,
+hidden, and `noindex` pages. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  sitemap: true,
+}
+```
+
+Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file
+you place in `public/`.
+
+## Robots
+
+Blume writes a `robots.txt` that allows all crawlers and adds a `Sitemap:` line
+pointing to the sitemap when one is available. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  robots: true,
+}
+```
+
+```txt robots.txt
+User-agent: *
+Allow: /
+
+Sitemap: https://docs.example.com/sitemap.xml
+```
+
+Ship your own `public/robots.txt` to take over.

package/docs/configuration/theming.mdx

@@ -0,0 +1,178 @@
+---
+title: Theming
+description: Tune the look with config tokens, override any CSS variable in theme.css, or use Tailwind utilities.
+---
+
+Blume's theme is token-driven and works in light and dark mode out of the box.
+Reach for as little or as much as you need: a few config tokens for the common
+cases, a `theme.css` to override any design token, or Tailwind utilities for
+custom components.
+
+## Config tokens
+
+The everyday knobs live under `theme` in your config:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  accent: "teal",   // a named preset or any CSS color
+  radius: "md",     // none | sm | md | lg
+  mode: "system",   // system | light | dark
+  fonts: {          // self-hosted Google Fonts
+    display: "inter-tight",
+    body: "inter",
+    mono: "ibm-plex-mono",
+  },
+}
+```
+
+### Accent
+
+The accent color tints interactive and highlighted elements — step markers,
+active tabs, badges, card hovers, and more. Use a named preset or any CSS color:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
+}
+```
+
+Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and
+`teal`.
+
+### Radius
+
+`radius` sets the corner rounding shared by cards, code blocks, callouts, and
+inputs — `none`, `sm`, `md` (default), or `lg`.
+
+### Color mode
+
+`mode` sets the initial color scheme:
+
+- **`system`** (default) — follow the reader's OS preference
+- **`light`** / **`dark`** — default to one scheme
+
+A toggle in the header always lets readers switch, and their choice is remembered
+across visits. Dark mode is applied with a `data-theme="dark"` attribute on the
+`<html>` element.
+
+### Fonts
+
+`fonts` sets the typefaces for three roles:
+
+- **`display`** — headings (`h1`–`h6`)
+- **`body`** — body text, UI, and prose
+- **`mono`** — code blocks and inline code
+
+Each defaults to a curated Google Font, so Blume looks intentional out of the box:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  fonts: {
+    display: "inter-tight",   // default
+    body: "inter",            // default
+    mono: "ibm-plex-mono",    // default
+  },
+}
+```
+
+Set only the roles you want to change — the rest keep their defaults:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
+}
+```
+
+Fonts are **self-hosted**: Blume downloads them at build time and serves them from
+your own site, so there's no runtime request to Google and no layout shift (Astro
+generates fallback-metric faces automatically).
+
+Each value is a Google Fonts slug from the curated set below:
+
+| Category | Slugs                                                                                                                                                            |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Sans     | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
+| Serif    | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4`                                                                                       |
+| Mono     | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono`                                                           |
+
+Need a font that isn't listed, or want to drop back to the system stack? Override
+the `--blume-font-*` tokens directly in [`theme.css`](#theme-css).
+
+## theme.css
+
+Drop a `theme.css` in your project root to override any design token. It's the
+last layer in the cascade, so it wins over the defaults and config tokens:
+
+```css theme.css lineNumbers
+:root {
+  --blume-accent: oklch(0.68 0.14 180);
+  --blume-radius: 0.5rem;
+}
+
+:root[data-theme="dark"] {
+  --blume-background: oklch(0.16 0 0);
+}
+```
+
+Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for
+dark mode.
+
+### Design tokens
+
+| Token                       | Controls                                  |
+| --------------------------- | ----------------------------------------- |
+| `--blume-background`        | Page background                           |
+| `--blume-foreground`        | Body text                                 |
+| `--blume-muted`             | Subtle surfaces — callouts, table headers |
+| `--blume-muted-foreground`  | Secondary text                            |
+| `--blume-border`            | Borders and dividers                      |
+| `--blume-accent`            | Accent color                              |
+| `--blume-accent-foreground` | Text and icons on an accent background    |
+| `--blume-code-background`   | Code block surface                        |
+| `--blume-radius`            | Corner radius                             |
+| `--blume-font-display`      | Heading font                              |
+| `--blume-font-body`         | Body / UI font                            |
+| `--blume-font-mono`         | Code font                                 |
+
+Set a `--blume-font-*` token to any font stack to use a font outside the curated
+list, or to fall back to the system stack:
+
+```css theme.css lineNumbers
+:root {
+  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+## Tailwind utilities
+
+Blume's theme is built with Tailwind v4 internally, and your project's `.astro`,
+`.tsx`, and `.jsx` files are scanned too — so you can style custom components and
+pages with utility classes, no Tailwind setup required. Every token is exposed as
+a utility, so your components track the theme automatically:
+
+| Token                       | Utilities                  |
+| --------------------------- | -------------------------- |
+| `--blume-background`        | `bg-background`            |
+| `--blume-foreground`        | `text-foreground`          |
+| `--blume-muted`             | `bg-muted`                 |
+| `--blume-muted-foreground`  | `text-muted-foreground`    |
+| `--blume-border`            | `border-border`            |
+| `--blume-accent`            | `bg-accent`, `text-accent` |
+| `--blume-accent-foreground` | `text-accent-foreground`   |
+| `--blume-radius`            | `rounded-blume`            |
+| `--blume-font-display`      | `font-display`             |
+| `--blume-font-body`         | `font-sans`                |
+| `--blume-font-mono`         | `font-mono`                |
+
+## Cascade order
+
+Styles resolve in three layers, each overriding the last:
+
+<Steps>
+  <Step title="Base">Blume's reset, default tokens, and component styles.</Step>
+  <Step title="Config tokens">
+    `--blume-accent`, `--blume-radius`, and the `--blume-font-*` tokens from
+    `theme`.
+  </Step>
+  <Step title="theme.css">Your token overrides — the final word.</Step>
+</Steps>