blume 0.0.0 → 0.1.1

package/docs/configuration/analytics.mdx

@@ -0,0 +1,98 @@
+---
+title: Analytics
+description: First-party web analytics — Vercel Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
+---
+
+Blume injects analytics for you from a single `analytics` block in
+`blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a
+`scripts` escape hatch covers every other provider — Plausible, Fathom, Google
+Analytics, Umami, and the rest.
+
+Analytics loads in **production builds only**. The scripts are emitted by
+`blume build`, never by `blume dev`, so local traffic never reaches your
+dashboards and you don't need a separate "development" project.
+
+:::note
+Analytics is opt-in. With no `analytics` block, Blume injects nothing.
+:::
+
+## Vercel Web Analytics
+
+Set `vercel: true` to add [Vercel Web Analytics](https://vercel.com/docs/analytics).
+Blume injects Vercel's first-party script, which is served from your own domain
+once Web Analytics is enabled for the project in the Vercel dashboard.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  vercel: true,
+}
+```
+
+No keys are needed — the script reports to the project it's deployed under. This
+only collects data on Vercel deployments, where the `/_vercel/insights` endpoint
+exists.
+
+## PostHog
+
+Provide your **project API key** to add [PostHog](https://posthog.com). The host
+defaults to PostHog Cloud US; set `host` for EU Cloud
+(`https://eu.i.posthog.com`) or a self-hosted instance.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  posthog: {
+    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    host: "https://us.i.posthog.com", // optional, this is the default
+  },
+}
+```
+
+The project API key is safe to ship to the browser — it's a public,
+write-only key.
+
+## Custom scripts
+
+Use `scripts` to load any other analytics provider. Each entry renders one
+`<script>` tag and must set **exactly one** of `src` (external) or `content`
+(inline).
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  scripts: [
+    // Plausible
+    {
+      src: "https://plausible.io/js/script.js",
+      strategy: "defer",
+      attributes: { "data-domain": "example.com" },
+    },
+    // Fathom
+    {
+      src: "https://cdn.usefathom.com/script.js",
+      strategy: "defer",
+      attributes: { "data-site": "ABCDEFG" },
+    },
+    // An inline snippet
+    {
+      content: "console.log('analytics ready')",
+    },
+  ],
+}
+```
+
+`attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto
+the tag, and `strategy` adds `async` or `defer` to external scripts.
+
+## Options
+
+| Option                 | Default                    | Description                                             |
+| ---------------------- | -------------------------- | ------------------------------------------------------- |
+| `vercel`               | `false`                    | Add Vercel Web Analytics (Vercel deployments only).     |
+| `posthog.key`          | —                          | PostHog project API key. Enables PostHog when set.      |
+| `posthog.host`         | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted).       |
+| `scripts[].src`        | —                          | External script URL. Mutually exclusive with `content`. |
+| `scripts[].content`    | —                          | Inline script body. Mutually exclusive with `src`.      |
+| `scripts[].strategy`   | —                          | `async` or `defer` for an external script.              |
+| `scripts[].attributes` | —                          | Extra HTML attributes spread onto the `<script>` tag.   |
+
+All three can be combined — enable Vercel, PostHog, and custom scripts together.
+For deploying your built site, see [Deployment](/docs/deployment).

package/docs/configuration/customization.mdx

@@ -0,0 +1,91 @@
+---
+title: Customization
+description: Override components, add interactive islands, mount custom pages, install registry components, or eject.
+---
+
+## Component overrides
+
+Add a `components.ts` (or `components.tsx`) to your project root and export
+`defineComponents`. The `mdx` map either **replaces** a built-in component or
+**adds** a new one — available in every `.mdx` page with no import.
+
+```ts components.ts lineNumbers
+import { defineComponents } from "blume";
+import Callout from "./components/Callout.astro";
+import Pricing from "./components/Pricing.astro";
+
+export default defineComponents({
+  mdx: {
+    Callout, // replace the built-in Callout
+    Pricing, // add a new <Pricing /> component
+  },
+});
+```
+
+Keys are the names you write in MDX (`<Callout>`, `<Pricing>`). Use the `.tsx`
+filename when you import React components.
+
+## Interactive islands
+
+For interactive UI (React, Vue, or Svelte), drop a component into an `islands/`
+folder and use it in any MDX page — Blume hydrates it for you, no wrapper or
+registration needed:
+
+```tsx islands/Counter.tsx lineNumbers
+import { useState } from "react";
+
+export default function Counter() {
+  const [n, setN] = useState(0);
+  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
+}
+```
+
+```mdx page.mdx
+Use it anywhere: <Counter />
+```
+
+See [Islands](/docs/content/islands) for hydration strategies and framework
+setup.
+
+## Custom pages
+
+Add `.astro` files under your `pages/` folder to mount fully custom routes
+alongside your docs — a landing page, a pricing page, or a hand-built index. They
+keep their location, so relative imports and `getStaticPaths` work as usual, and
+they can read your config, navigation, and routes from the `blume:data` module.
+
+See [Custom Pages](/docs/advanced/custom-pages) for the full guide.
+
+## Registry
+
+`blume add` copies a Blume-maintained component into your project as **source** —
+you own it and can edit it freely. Run it with no arguments to list what's
+available:
+
+```bash
+blume add
+```
+
+Install a widget, or any built-in layout slot you want to customize — the
+header, sidebar, breadcrumbs, table of contents, or pagination:
+
+```bash
+blume add pagination
+```
+
+The copy imports the rest of the framework from `blume/*`, so it renders
+exactly like the built-in until you change it. `blume add` prints the
+`defineComponents` snippet to register it under the matching layout slot.
+
+## Eject
+
+When you want full control, eject the generated runtime into a standalone Astro
+project:
+
+```bash
+blume eject --yes
+```
+
+Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app
+you own and can modify directly. The `blume` package stays importable, so you
+keep its components, theme, and Markdown processors.

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,290 @@
+---
+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.
+
+### Apple touch icon
+
+The icon iOS uses when someone adds your site to their home screen is detected
+the same way. Drop an `apple-icon` file (`.png`, `.jpg`, or `.jpeg`) — or an
+`apple-touch-icon.png`, the name most favicon generators emit — in your project
+root or `public/` directory and Blume wires up `<link rel="apple-touch-icon">`
+for you. There's no default; if no file is found, no tag is emitted.
+
+```
+my-docs/
+├─ blume.config.ts
+├─ apple-icon.png     ← picked up automatically
+└─ docs/
+```
+
+Put the file in `public/` rather than the project root: iOS ignores the inlined
+data URI Blume uses for a root-level icon, so only a `public/` file (served at
+`/apple-icon.png`) reliably reaches the home screen.
+
+### 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",
+});