blume 0.0.0 → 0.1.0

package/docs/configuration/export.mdx

@@ -0,0 +1,70 @@
+---
+title: Export
+description: Let readers download any page as a PDF or EPUB.
+---
+
+Blume can add an **Export** action to the [page
+actions](/docs/content/navigation#page-actions) beneath the table of contents,
+letting readers save the page they're on as a **PDF** or an **EPUB**. It's off by
+default and entirely client-side — no server, and [static](/docs/deployment)
+builds stay static.
+
+## Enable it
+
+Turn on both formats with a single toggle:
+
+```ts blume.config.ts
+export: true,
+```
+
+To offer just one format, pass an object instead:
+
+```ts blume.config.ts
+export: {
+  pdf: true,
+  epub: false,
+},
+```
+
+Any format you omit (or set to `false`) is left out of the menu. With both off —
+the default — the **Export** action doesn't appear at all.
+
+## PDF
+
+**Export to PDF** opens your browser's print dialog with a print stylesheet that
+strips the site chrome — header, sidebars, navigation — down to just the article.
+Choose **Save as PDF** to finish.
+
+Because it prints the live, fully-styled page, the result keeps crisp, selectable
+text, real fonts, and syntax-highlighted code. It needs no dependencies and works
+the same in dev, in production, and on static hosts.
+
+:::note
+PDF export goes through the browser's native print dialog, so the exact "Save as
+PDF" wording and options depend on the browser. Enable **Background graphics** in
+the dialog to keep code-block and callout backgrounds.
+:::
+
+## EPUB
+
+**Export to EPUB** generates a self-contained `.epub` of the current page in the
+browser and downloads it — ready for Apple Books, Calibre, or any e-reader. The
+generator is loaded only when a reader clicks Export, so it never weighs down the
+rest of your site.
+
+To keep the file readable on a device with no stylesheet or JavaScript of its
+own, Blume rewrites the page into clean, standalone HTML: syntax-highlighted code
+becomes plain monospace, decorative icons and copy buttons are dropped, and a
+built-in e-reader stylesheet handles spacing, code blocks, and tables.
+
+## What gets exported
+
+Both formats export the **single page** a reader is viewing — not the whole site
+— which matches where the action lives, beneath that page's table of contents.
+
+:::note
+In an EPUB there's no JavaScript to switch tabs, so tabbed content — like
+[package-install](/docs/content/syntax) blocks and code groups — is expanded to
+show every panel at once. Client-rendered embeds such as Mermaid diagrams aren't
+included.
+:::

package/docs/configuration/index.mdx

@@ -0,0 +1,271 @@
+---
+title: Configuration file
+description: Every option in blume.config.ts — site metadata, content, and links to each feature guide.
+sidebar:
+  label: blume.config.ts
+---
+
+Blume reads `blume.config.ts` from your project root. Wrap your config in
+`defineConfig` for autocomplete and type-checking — every field is optional, with
+a sensible default.
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  title: "My Docs",
+  description: "Documentation for my project.",
+});
+```
+
+## A complete example
+
+Every option Blume reads, with its default:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  // Site
+  title: "My Docs",
+  description: "Documentation for my project.",
+  logo: "/logo.svg",
+
+  // Content
+  content: {
+    root: "docs",
+  },
+
+  // Theme — see the Theming guide
+  theme: {
+    accent: "teal",
+    radius: "md",
+    mode: "system",
+  },
+
+  // Search — see the Search guide
+  search: {
+    provider: "orama",
+  },
+
+  // Markdown features
+  markdown: {
+    imageZoom: true,
+    math: false,
+    code: {
+      icons: true, // language icon in the code-block header
+      wrap: false, // wrap long lines instead of scrolling
+      inline: false, // highlight inline `code{:lang}` snippets
+    },
+  },
+
+  // AI — see the AI guide
+  ai: {
+    llmsTxt: true,
+  },
+
+  // MCP server (needs server output) — see the AI guide
+  mcp: {
+    enabled: false,
+    route: "/mcp",
+  },
+
+  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
+  seo: {
+    og: { enabled: true },
+    rss: { enabled: true, types: ["blog", "changelog"] },
+    sitemap: true,
+    robots: true,
+    structuredData: true,
+  },
+
+  // Deployment — see the Deployment guide
+  deployment: {
+    output: "static",
+    site: "https://docs.example.com",
+  },
+});
+```
+
+## Site
+
+| Option        | Default           | Description                                             |
+| ------------- | ----------------- | ------------------------------------------------------- |
+| `title`       | `"Documentation"` | Site name — shown in the header, page titles, OG cards. |
+| `description` | —                 | Default meta description, used for SEO and OG.          |
+| `logo`        | —                 | Brand logo shown beside the title in the header.        |
+| `banner`      | —                 | Site-wide announcement bar above the header.            |
+
+### Logo
+
+Point `logo` at an SVG and Blume inlines it, so a `currentColor` logo follows
+the light and dark theme automatically:
+
+```ts blume.config.ts
+logo: "/logo.svg",
+```
+
+The SVG can live at your project root or in `public/`. For raster images — or
+separate light and dark artwork — use the object form (these must live in
+`public/`):
+
+```ts blume.config.ts lineNumbers
+logo: {
+  light: "/logo-light.png",
+  dark: "/logo-dark.png",
+  alt: "Acme",
+  href: "/",
+},
+```
+
+`href` overrides the logo's link (it defaults to `/`).
+
+### Favicon
+
+There's no favicon option — Blume auto-detects one by filename, the way Next.js
+does. Drop an `icon` or `favicon` file (`.svg`, `.png`, or `.ico`) in your
+project root or `public/` directory and it becomes the browser tab icon:
+
+```
+my-docs/
+├─ blume.config.ts
+├─ icon.png          ← picked up automatically
+└─ docs/
+```
+
+SVG wins over PNG over ICO when several are present, and a file in `public/` is
+preferred over one at the root. If Blume finds no icon, it falls back to its own
+mark.
+
+### Banner
+
+Show a site-wide announcement bar above the header. Pass a string, or an object
+with a link and a dismiss button:
+
+```ts blume.config.ts
+banner: "Docs are in beta — expect changes.",
+```
+
+```ts blume.config.ts lineNumbers
+banner: {
+  content: "Blume v1 is here!",
+  link: { text: "Read more", href: "/blog/v1" },
+  dismissible: true,
+  id: "v1",
+},
+```
+
+When `dismissible` is on, the bar shows a close button and stays hidden for that
+visitor afterward. The dismissal key defaults to the content text, so editing
+the message brings the banner back; set a stable `id` to keep it dismissed
+across edits.
+
+## Content
+
+Where your content lives and how Blume discovers it. See [Pages](/docs/content) for
+how files become routes.
+
+```ts blume.config.ts lineNumbers
+content: {
+  root: "docs",
+}
+```
+
+| Option        | Default              | Description                                  |
+| ------------- | -------------------- | -------------------------------------------- |
+| `root`        | `"docs"`             | Folder Blume scans for content.              |
+| `include`     | `["**/*.{md,mdx}"]`  | Globs that match content files.              |
+| `exclude`     | `["**/_*", "**/.*"]` | Globs to ignore (underscore- and dot-files). |
+| `pages`       | `"pages"`            | Folder for custom `.astro` pages.            |
+| `defaultType` | `"doc"`              | Page `type` used when frontmatter omits it.  |
+
+## Last modified
+
+Show a "Last updated on …" line at the bottom of each page. Off by default; set
+`lastModified` to `true` to derive each page's date from its git history:
+
+```ts blume.config.ts
+lastModified: true,
+```
+
+| Value                     | Description                                                    |
+| ------------------------- | -------------------------------------------------------------- |
+| `false`                   | Disabled (default).                                            |
+| `true`                    | Read the date from git history (commit dates).                 |
+| `{ type: "git" }`         | Same as `true`, written explicitly.                            |
+| `{ type: "frontmatter" }` | Never run git — use only the `lastModified` frontmatter field. |
+
+The git source reads the most recent commit that touched each file, so it works
+in any git repository — including monorepos — and needs the repo's history at
+build time (avoid a shallow `--depth 1` checkout in CI). A page's own
+`lastModified` frontmatter always wins, which is handy for pinning a date or for
+files that aren't committed yet:
+
+```mdx page.mdx
+---
+title: My page
+lastModified: 2026-06-20
+---
+```
+
+When enabled, the date is also emitted as schema.org `dateModified` in the
+page's structured data.
+
+## SEO
+
+Open Graph images, RSS feeds, and JSON-LD structured data, grouped under `seo`.
+See the [SEO guide](/docs/configuration/seo) for metadata, frontmatter overrides, and
+the full reference.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: { enabled: false },
+  rss: { enabled: true, types: ["blog", "changelog"] },
+  sitemap: true,
+  robots: true,
+  structuredData: true,
+}
+```
+
+| Option           | Default                 | Description                                   |
+| ---------------- | ----------------------- | --------------------------------------------- |
+| `og.enabled`     | `false`                 | Generate per-page Open Graph images.          |
+| `rss.enabled`    | `true`                  | Build feeds for blog and changelog content.   |
+| `rss.types`      | `["blog", "changelog"]` | Content types that each get a feed.           |
+| `rss.limit`      | `50`                    | Maximum items per feed.                       |
+| `sitemap`        | `true`                  | Generate sitemap.xml (needs deployment.site). |
+| `robots`         | `true`                  | Generate robots.txt with a Sitemap link.      |
+| `structuredData` | `true`                  | Emit schema.org JSON-LD in each page's head.  |
+
+These work best with an absolute [`deployment.site`](/docs/deployment) for full URLs.
+
+## Feature options
+
+Each of these has its own guide. The config field is the entry point:
+
+| Field        | What it configures                                  | Guide                                      |
+| ------------ | --------------------------------------------------- | ------------------------------------------ |
+| `theme`      | Accent color, corner radius, fonts, light/dark mode | [Theming](/docs/configuration/theming)     |
+| `navigation` | Explicit sidebar and header tabs                    | [Navigation](/docs/content/navigation)     |
+| `search`     | Provider (Orama or Pagefind) and indexing           | [Search](/docs/configuration/search)       |
+| `markdown`   | Opt-in Markdown features like math                  | [Syntax](/docs/content/syntax)             |
+| `ai`         | `llms.txt`, Ask AI, and the MCP server              | [AI](/docs/configuration/ai)               |
+| `mcp`        | Hosted MCP server for coding agents                 | [AI](/docs/configuration/ai#mcp-server)    |
+| `analytics`  | Vercel, PostHog, and custom scripts                 | [Analytics](/docs/configuration/analytics) |
+| `seo`        | Metadata, OG images, feeds, structured data         | [SEO](/docs/configuration/seo)             |
+| `deployment` | Output mode, adapter, and site URL                  | [Deployment](/docs/deployment)             |
+| `redirects`  | Permanent and temporary redirects                   | [Deployment](/docs/deployment#redirects)   |
+
+## Precedence
+
+Settings resolve from lowest to highest priority, so you only override what you
+need:
+
+<Steps>
+  <Step title="Blume defaults">A sensible default for every field.</Step>
+  <Step title="blume.config.ts">Your project-wide configuration.</Step>
+  <Step title="Folder meta">
+    [`meta.ts`](/docs/content/meta) for a section's title and ordering.
+  </Step>
+  <Step title="Page frontmatter">Per-page overrides win.</Step>
+</Steps>

package/docs/configuration/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  order: 4,
+  pages: [
+    "theming",
+    "customization",
+    "search",
+    "ai",
+    "analytics",
+    "export",
+    "seo",
+  ],
+  title: "Configuration",
+});

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 },
+}
+```