blume 0.2.0 → 0.4.0

package/docs/configuration/search.mdx

@@ -3,38 +3,23 @@ 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 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.
+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, and `⌘J` (or `Ctrl J`)
-toggles the result preview pane.
+Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/` when you're not typing in a field. `Esc` closes it, and `⌘J` (or `Ctrl J`) toggles the result preview pane.
 
-Queries match page **titles**, **descriptions**, and **body text**, with title
-matches ranked highest and descriptions above body.
+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.
+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.
 
 ## Tags
 
-Add `search.tags` to a page's frontmatter to group it under a filter in the
-search dialog — readers can narrow results to a tag with a click. Tags also
-become a facet on the hosted providers.
+Add `search.tags` to a page's frontmatter to group it under a filter in the search dialog — readers can narrow results to a tag with a click. Tags also become a facet on the hosted providers.
 
 ```yaml
 search:
@@ -43,16 +28,11 @@ search:
 
 ## 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.
+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.
+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: {
@@ -62,9 +42,7 @@ search: {
 
 ### 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`.
+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: {
@@ -74,9 +52,7 @@ search: {
 
 ### 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.
+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: {
@@ -84,14 +60,11 @@ search: {
 }
 ```
 
-Pagefind only runs during `blume build`, so search isn't available in `blume dev`
-with this provider.
+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).
+The browser queries [Algolia](https://www.algolia.com) directly with your search-only key. Each `blume build` replaces the index using the admin key from `ALGOLIA_ADMIN_API_KEY` (the build warns and skips the upload if it's unset). The whole index is replaced on every sync, so pages you delete or rename don't linger as stale results.
 
 ```ts blume.config.ts lineNumbers
 search: {
@@ -106,9 +79,7 @@ search: {
 
 ### 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.
+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: {
@@ -123,9 +94,7 @@ search: {
 
 ### 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`.
+Self-hosted or cloud [Typesense](https://typesense.org). The browser queries the collection with the search-only key; `blume build` recreates the collection and imports documents using `TYPESENSE_ADMIN_API_KEY`. The collection is dropped and rebuilt on every sync so deleted or renamed pages don't linger as stale results — if you hand-tune the collection's settings, reapply them after a build.
 
 ```ts blume.config.ts lineNumbers
 search: {
@@ -141,11 +110,7 @@ search: {
 
 ### 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`.
+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: {
@@ -166,16 +131,14 @@ search: {
 
 ## Excluding pages
 
-Only indexable pages are searched. A page is left out of the index when it sets
-`search.exclude` in frontmatter:
+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:
+[Hidden pages](/docs/content/navigation#hidden-pages) are also excluded by default. To index them anyway, opt in:
 
 ```ts blume.config.ts lineNumbers
 search: {

package/docs/configuration/seo.mdx

@@ -5,9 +5,7 @@ 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.
+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: {
@@ -19,20 +17,16 @@ seo: {
 }
 ```
 
-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.
+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`.
+- `<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).
+- `<link rel="canonical">` — the page's absolute URL (when `deployment.site` is set).
 
 Override any of these per page with `seo` frontmatter:
 
@@ -74,11 +68,7 @@ seo:
 
 ## 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:
+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: {
@@ -86,10 +76,7 @@ seo: {
 }
 ```
 
-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:
+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                  |
 | ------------------- | -------------------------- |
@@ -97,9 +84,7 @@ prerendered as static files even in server mode:
 | `/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:
+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
 ---
@@ -109,16 +94,13 @@ seo:
 ---
 ```
 
-:::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.
-:::
+:::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. :::
+
+`seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
 
 ## 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.
+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: {
@@ -136,13 +118,11 @@ seo: {
 | `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.
+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:
+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: {
@@ -153,18 +133,14 @@ seo: {
 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,
+- 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.
+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:
+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: {
@@ -172,13 +148,11 @@ seo: {
 }
 ```
 
-Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file
-you place in `public/`.
+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:
+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: {

package/docs/configuration/theming.mdx

@@ -3,10 +3,7 @@ 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.
+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
 
@@ -27,8 +24,7 @@ theme: {
 
 ### 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:
+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: {
@@ -36,13 +32,11 @@ theme: {
 }
 ```
 
-Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and
-`teal`.
+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`.
+`radius` sets the corner rounding shared by cards, code blocks, callouts, and inputs — `none`, `sm`, `md` (default), or `lg`.
 
 ### Color mode
 
@@ -51,9 +45,7 @@ inputs — `none`, `sm`, `md` (default), or `lg`.
 - **`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.
+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
 
@@ -83,26 +75,21 @@ theme: {
 }
 ```
 
-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).
+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`                                                           |
+| 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).
+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`](#themecss).
 
 ### Dark-mode colors
 
-By default light and dark share one `accent`. Set `accentDark` for a different
-accent in dark mode, and `background` / `backgroundDark` to override the page
-background per mode:
+By default light and dark share one `accent`. Set `accentDark` for a different accent in dark mode, and `background` / `backgroundDark` to override the page background per mode:
 
 ```ts blume.config.ts lineNumbers
 theme: {
@@ -117,8 +104,7 @@ Each takes a named preset or any CSS color, exactly like `accent`.
 
 ### Action color
 
-`action` is a secondary accent for primary calls to action and the `action`
-Tailwind utilities (`bg-action`, `text-action`). It defaults to your `accent`:
+`action` is a secondary accent for primary calls to action and the `action` Tailwind utilities (`bg-action`, `text-action`). It defaults to your `accent`:
 
 ```ts blume.config.ts
 theme: {
@@ -128,8 +114,7 @@ theme: {
 
 ### Background decoration
 
-Add a subtle, theme-aware pattern behind your content with `backgroundDecoration`
-— `gradient`, `grid`, or `windows`:
+Add a subtle, theme-aware pattern behind your content with `backgroundDecoration` — `gradient`, `grid`, or `windows`:
 
 ```ts blume.config.ts
 theme: {
@@ -137,8 +122,7 @@ theme: {
 }
 ```
 
-For a full background image, set `backgroundImage` (and `backgroundImageDark` for
-a dark variant) to a URL or a path under `public/`:
+For a full background image, set `backgroundImage` (and `backgroundImageDark` for a dark variant) to a URL or a path under `public/`:
 
 ```ts blume.config.ts lineNumbers
 theme: {
@@ -149,8 +133,7 @@ theme: {
 
 ## 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:
+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 {
@@ -163,8 +146,7 @@ last layer in the cascade, so it wins over the defaults and config tokens:
 }
 ```
 
-Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for
-dark mode.
+Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode.
 
 ### Design tokens
 
@@ -184,8 +166,7 @@ dark mode.
 | `--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:
+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 {
@@ -195,10 +176,7 @@ list, or to fall back to the system stack:
 
 ## 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:
+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                  |
 | --------------------------- | -------------------------- |