blume 1.2.1 → 1.3.0

package/dist/types/theme/fonts.d.ts

@@ -1,23 +1,65 @@
 /**
- * Curated Google Fonts exposed through `theme.fonts`.
+ * Fonts exposed through `theme.fonts`.
  *
- * Each slug maps to the official Google family name (Astro's font provider needs
- * the exact name), a docs-appropriate set of weights, and a fallback category.
- * Fonts are self-hosted and optimized by Astro's built-in Fonts API; this module
- * only resolves config slugs into the data that drives it.
+ * Each role accepts a curated Google Font slug, a remote-provider family (any
+ * Google/Fontsource/Bunny/Fontshare family by name), or local font files. All
+ * forms resolve to entries for Astro's built-in Fonts API, which self-hosts
+ * and optimizes them; this module only resolves config values into the data
+ * that drives it.
  */
 export type FontCategory = "sans" | "serif" | "mono";
 /** The three configurable roles in `theme.fonts`. */
 export type FontSlot = "display" | "body" | "mono";
-/** Resolved theme fonts (a validated slug per role, all optional). */
-export type FontsConfig = Partial<Record<FontSlot, string>> | undefined;
-/** A single Astro `fonts:` entry (sans the literal `fontProviders.google()`). */
-export interface FontEntry {
+/** Zero-config Astro font providers usable from `theme.fonts`. */
+export type RemoteFontProvider = "google" | "fontsource" | "bunny" | "fontshare";
+/** A remote-provider family: any family name the provider knows. */
+export interface RemoteFontConfig {
+    /** Family name as the provider lists it, e.g. `"Noto Sans JP"`. */
+    name: string;
+    /** Which provider serves the family. Defaults to `"google"`. */
+    provider?: RemoteFontProvider;
+    /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
+    weights?: (number | string)[];
+    /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
+    fallback?: FontCategory;
+}
+/** One `@font-face` declaration for a local font. */
+export interface LocalFontVariant {
+    /** Font file path, relative to the project root. */
+    src: string;
+    /** Face weight; inferred from the file when omitted. */
+    weight?: number | string;
+    /** Face style; inferred from the file when omitted. */
+    style?: "normal" | "italic" | "oblique";
+}
+/** A self-hosted family loaded from files in the project. */
+export interface LocalFontConfig {
+    /** Family name used in CSS and the OG card. */
+    name: string;
+    /** The faces to declare (at least one). */
+    variants: LocalFontVariant[];
+    /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
+    fallback?: FontCategory;
+}
+/** A role's font: curated slug, remote family, or local files. */
+export type FontValue = string | RemoteFontConfig | LocalFontConfig;
+/** Resolved theme fonts (a validated value per role, all optional). */
+export type FontsConfig = Partial<Record<FontSlot, FontValue>> | undefined;
+/** A single Astro `fonts:` entry (sans the literal `fontProviders.*()` call). */
+export type FontEntry = {
+    kind: "remote";
+    provider: RemoteFontProvider;
     cssVariable: string;
     fallbacks: string[];
     name: string;
-    weights: number[];
-}
+    weights: (number | string)[];
+} | {
+    kind: "local";
+    cssVariable: string;
+    fallbacks: string[];
+    name: string;
+    variants: LocalFontVariant[];
+};
 /** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
 export declare const GOOGLE_FONTS: {
     "dm-sans": {
@@ -151,6 +193,8 @@ export type FontSlug = keyof typeof GOOGLE_FONTS;
 export declare const FONT_SLUGS: string[];
 /** Type guard: is `value` a supported font slug? */
 export declare const isFontSlug: (value: string) => value is FontSlug;
+/** Kebab-case a family name into a slug (`"Noto Sans JP"` -> `"noto-sans-jp"`). */
+export declare const slugifyFontName: (name: string) => string;
 /** The unique Astro `fonts:` entries for the configured roles (deduped). */
 export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
 /**

package/docs/02-deployment.mdx

@@ -101,6 +101,8 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 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.
 
+On Vercel, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/configuration/ai#content-negotiation): Blume splices header-conditional rewrites into the deploy's routing config, so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL.
+
 :::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.
 :::

package/docs/07-faq.mdx

@@ -87,19 +87,19 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.58.0.patch`:
-
-   ```diff patches/oxfmt@0.58.0.patch
-   diff --git a/dist/markdown-BjyDFyaO.js b/dist/markdown-BjyDFyaO.js
-   index 1905aa7563e612808426e26f1ed28bebbef3456f..42bb9f66829068676c5697fc9fc39279bf937f3e 100644
-   --- a/dist/markdown-BjyDFyaO.js
-   +++ b/dist/markdown-BjyDFyaO.js
-   @@ -4830,7 +4830,43 @@ function lu(e, t, r) {
-    		case "sentence": return Mh(e, r);
-    		case "word": return t.parser !== "mdx" ? Vh(e, t) : Gh(e);
+1. Save the patch as `patches/oxfmt@0.61.0.patch`:
+
+   ```diff patches/oxfmt@0.61.0.patch
+   diff --git a/dist/markdown-ZuiQU4Xe.js b/dist/markdown-ZuiQU4Xe.js
+   index 566b9e6d27f36061d64b93736e238e871e1ee2b2..82d0595acc010807c2939fc4a1717dde887a8555 100644
+   --- a/dist/markdown-ZuiQU4Xe.js
+   +++ b/dist/markdown-ZuiQU4Xe.js
+   @@ -4875,7 +4875,43 @@ function lu(e, t, r) {
+    		case "sentence": return Oh(e, r);
+    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
     		case "whitespace": {
-   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
-   +			let { next: i, previous: oxfmtFencePrev } = e;
+   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
+   +			let { next: a, previous: oxfmtFencePrev } = e;
    +			// Preserve line breaks that sit directly against a `:::` container
    +			// directive fence, so `proseWrap: "never"` keeps the opening/closing
    +			// fence on their own lines instead of joining them into the prose (which
@@ -135,7 +135,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    +				}
    +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
    +			}
-   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
+   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
     			return ou(e, n.value, u, !1, t);
     		}
     		case "emphasis": {
@@ -146,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.58.0": "patches/oxfmt@0.58.0.patch"
+       "oxfmt@0.61.0": "patches/oxfmt@0.61.0.patch"
      }
    }
    ```

package/docs/advanced/skills.mdx

@@ -3,11 +3,11 @@ title: Skills
 description: The agent skills Blume ships — playbooks that teach a coding agent like Claude Code, Codex, or Cursor to build and maintain a Blume docs site.
 ---
 
-Blume ships [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks that teach a coding agent (Claude Code, Codex, Cursor) how to do a Blume-shaped job without you explaining it. They live on GitHub in the repo's `skills/` folder and are bundled in the package at `node_modules/blume/skills/` once Blume is installed, so any agent can be pointed at a `SKILL.md` directly.
+Blume ships [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks that teach a coding agent (Claude Code, Codex, Cursor) how to do a Blume-shaped job without you explaining it. They live on GitHub in the repo's `skills/` folder and are bundled in the installed package under `skills/`, so any agent can be pointed at a `SKILL.md` directly.
 
 ## Blume
 
-The core skill. It teaches the agent what Blume is and how to scaffold, write, and configure a site — filesystem-derived navigation, the config schema, content components — and points it at the full docs bundled in the installed package (`node_modules/blume/docs`). Install it in any project where an agent helps you build your docs:
+The core skill. It teaches the agent what Blume is and how to scaffold, write, and configure a site — filesystem-derived navigation, the config schema, content components — and points it at the full docs bundled in the installed package (the `docs/` directory inside `blume`, resolved from wherever your package manager installs it — in a pnpm monorepo that's the depending workspace's `node_modules`, not the repo root). Install it in any project where an agent helps you build your docs:
 
 ```bash
 npx skills add haydenbleasel/blume

package/docs/configuration/ai.mdx

@@ -61,6 +61,10 @@ Nested routes work the same way (`/content/syntax.md`), and the home page is ser
 
 The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
 
+### Content negotiation
+
+Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy's routing rules automatically — no configuration needed. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
+
 ### Custom component serializers
 
 Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
@@ -249,7 +253,7 @@ ai: {
 | `name`         | title   | Server name shown to clients (defaults to title). |
 | `instructions` | —       | Optional system hint passed to connecting agents. |
 
-The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).
+The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).
 
 `search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even when search is set to `none`. The MCP server is a separate feature from on-page search.
 
@@ -306,8 +310,128 @@ The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown
 }
 ```
 
+The `contentNegotiation` field appears only when the deployed site actually honors the `Accept: text/markdown` header — see [content negotiation](#content-negotiation); on every other deployment the manifest advertises just the `.md` mirror pattern.
+
 Set `seo.agentReadability` to `false` to skip it, or ship your own `public/agent-readability.json` to take over — Blume never overwrites a file you place in `public/`.
 
+### Discovery Link header
+
+Agents that probe a site don't know to look for the manifest — so Blume also advertises it in an [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` response header on the homepage, using IANA-registered relation types:
+
+```http
+Link: </agent-readability.json>; rel="describedby"; type="application/json",
+  </llms.txt>; rel="describedby"; type="text/plain",
+  </index.md>; rel="alternate"; type="text/markdown"
+```
+
+Each entry appears only when its feature is on, and the `alternate` link only when your homepage is a content page with a [raw Markdown](#raw-markdown) mirror. Sites that publish APIs also get a `rel="api-catalog"` entry pointing at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules. Hosts that ignore `_headers` on static output (GitHub Pages, S3) can't send custom response headers at all — there, agents still find everything through `llms.txt` and `agent-readability.json` at the site root.
+
+### API catalog
+
+When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog` — a [linkset](https://www.rfc-editor.org/rfc/rfc9264) that lets agents enumerate your APIs from the domain alone, served with its registered `application/linkset+json` media type on every build surface. There's nothing to configure: the catalog is derived from what's already in `blume.config.ts`. Each [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) becomes an entry anchored at its rendered docs route, with `service-doc` pointing at those docs and `service-desc` at the spec when it lives at a fetchable URL; the [MCP server](#mcp-server) becomes an entry with its discovery document as the service description:
+
+```json .well-known/api-catalog
+{
+  "linkset": [
+    {
+      "anchor": "https://docs.example.com/reference",
+      "service-doc": [
+        { "href": "https://docs.example.com/reference", "type": "text/html" }
+      ],
+      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
+    },
+    {
+      "anchor": "https://docs.example.com/mcp",
+      "service-desc": [
+        {
+          "href": "https://docs.example.com/.well-known/mcp.json",
+          "type": "application/json"
+        }
+      ],
+      "service-doc": [
+        { "href": "https://docs.example.com/", "type": "text/html" }
+      ]
+    }
+  ]
+}
+```
+
+A site with no API references and no MCP server emits no catalog — there'd be nothing in it. As everywhere, a `public/.well-known/api-catalog` file you ship yourself wins over the generated one.
+
+### WebMCP
+
+[WebMCP](https://webmachinelearning.github.io/webmcp/) is an emerging browser API that lets a page register tools directly with an agentic browser — no separate server connection needed. Every Blume page registers the docs' read-only surface on the page's model context: `search_docs` (site search), `get_page` (a page's [raw Markdown](#raw-markdown)), and `list_pages` (the [`llms.txt`](#llmstxt) index). The script is tiny, loads no search machinery until a tool is actually called, and silently no-ops in every browser without the API — which today is all of them outside [Chrome's early preview](https://developer.chrome.com/blog/webmcp-epp). It registers on whichever surface the in-flux spec exposes (`navigator.modelContext` or `document.modelContext`), via `provideContext` or per-tool `registerTool`.
+
+It's on by default; set `webmcp: false` to opt out:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  webmcp: false,
+}
+```
+
+### Skills discovery
+
+If your project ships [agent skills](https://agentskills.io) — the [Blume repo itself does](#agent-skill) — point `ai.skills` at the directory that holds them, and the build publishes them for discovery per the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc):
+
+```ts blume.config.ts lineNumbers
+ai: {
+  skills: "./skills",
+}
+```
+
+The path resolves against your project root, and each subdirectory with a `SKILL.md` becomes a published skill. A skill that's a lone `SKILL.md` is copied verbatim to `/.well-known/agent-skills/<name>/SKILL.md` (`type: "skill-md"`); a skill with supporting resources (`scripts/`, `references/`, `assets/`) is bundled into a deterministic `.tar.gz` (`type: "archive"`) so its relative references resolve after unpacking, with script execute bits preserved. The discovery index at `/.well-known/agent-skills/index.json` carries the v0.2.0 `$schema` and, per skill, its name, type, description (from the `SKILL.md` frontmatter), artifact URL, and the SHA-256 digest clients verify downloads against.
+
+Skills with a missing or spec-invalid `name`/`description` are skipped with a build warning rather than published broken, and a `public/.well-known/agent-skills/index.json` you ship yourself takes over the whole surface.
+
+### DNS-based discovery (DNS-AID)
+
+[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) is an emerging IETF draft that lets agents discover a site's AI surface before making a single HTTP request, by querying ServiceMode [SVCB/HTTPS records](https://www.rfc-editor.org/rfc/rfc9460) at a well-known DNS entrypoint. DNS records live in your zone, not in the build, so this is the one discovery surface Blume can't publish for you — instead, add a record with your DNS provider:
+
+```txt
+_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
+```
+
+Use the `HTTPS` record type if your provider offers it (Vercel DNS does; it doesn't support the plain `SVCB` type), or a ServiceMode `SVCB` record with `alpn` and `port` parameters otherwise. The draft also recommends signing the zone with DNSSEC so validating resolvers return authenticated answers — providers like Cloudflare enable it in one click, while some (including Vercel DNS) don't support it at all.
+
+`blume audit --url <origin>` checks this for you: when [`deployment.site`](/docs/deployment) is set, the network tier queries the entrypoint over DNS-over-HTTPS and reports the exact record to publish if none exists, plus whether the answers are DNSSEC-authenticated. Set `BLUME_DOH_URL` to point the lookup at your own resolver if your network blocks the public ones (Google, Cloudflare).
+
+### Web Bot Auth
+
+[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) works in the other direction: it's not about agents reading your docs, but about **your organization's agents identifying themselves** when they make requests elsewhere. Your agents sign their requests with [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421), and receiving sites verify them against a public-key directory published on your domain. If your org runs agents and your Blume site lives at the domain they identify as, publish their public keys:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  webBotAuth: {
+    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
+  },
+}
+```
+
+Blume then serves the JWKS at `/.well-known/http-message-signatures-directory` with its registered media type on every build surface. The directory is public by definition, so the config only admits public keys — a JWK containing private material (`d`, `p`, `q`, …) fails validation with an error rather than shipping a leaked credential. Generate an Ed25519 pair with:
+
+```bash
+node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
+```
+
+The public JWK goes in the config above; the private one goes wherever your signing agent runs (a secret manager, never the repo). If your organization doesn't operate agents, skip this — an empty directory advertises nothing worth verifying.
+
+Since `blume.config.ts` is executed at build time, the key doesn't have to be hardcoded — load it from a build-time environment variable to keep the config free of key blobs and rotate without a commit:
+
+```ts blume.config.ts lineNumbers
+const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;
+
+export default defineConfig({
+  ai: {
+    webBotAuth: {
+      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
+    },
+  },
+});
+```
+
+Environments without the variable publish no directory, and a key loaded this way is validated exactly like an inline one — including the private-material check. (The public key isn't a secret, so committing it inline is equally fine; the env var is an ergonomic choice, not a security one.)
+
 ## Agent skill
 
 Building a Blume site with the help of a coding agent? Install the Blume [agent skill](https://docs.claude.com/en/docs/claude-code/skills) so it knows how Blume works without you explaining it:
@@ -316,6 +440,6 @@ Building a Blume site with the help of a coding agent? Install the Blume [agent
 npx skills add haydenbleasel/blume
 ```
 
-The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (`node_modules/blume/docs`).
+The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (the `docs/` directory inside `blume`, wherever your package manager installs it).
 
 It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside a skill for keeping docs in sync with your product from a scheduled agent run.

package/docs/configuration/index.mdx

@@ -190,7 +190,25 @@ content: {
 | `pages` | `"pages"` | Folder for custom `.astro` pages. |
 | `defaultType` | `"doc"` | Page `type` used when frontmatter omits it. |
 
-Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`.
+Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`. Images referenced by **relative path** (`![](./diagram.png)`) live next to your content instead, and are [optimized at build time](/docs/content/syntax#links-and-images).
+
+## Images
+
+Local images referenced by relative path are optimized automatically at build time — compressed, converted to WebP, and given intrinsic `width`/`height` attributes so the layout doesn't shift while they load. There's nothing to configure; see [Links and images](/docs/content/syntax#links-and-images) for authoring guidance.
+
+Remote images are served untouched by default. To have Blume download and optimize them at build time too, authorize their hosts:
+
+```ts blume.config.ts lineNumbers
+image: {
+  domains: ["cdn.example.com"],
+  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `domains` | `[]` | Hostnames whose remote images may be optimized. |
+| `remotePatterns` | `[]` | Pattern-based authorization (`protocol`, `hostname`, `port`, `pathname`); hostnames accept `*.` (one level) and `**.` (any depth) wildcards. |
 
 ## Frontmatter
 

package/docs/configuration/search.mdx

@@ -80,6 +80,8 @@ i18n: {
 
 The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding. On a mixed-language site the whole index shares the default locale's tokenizer — that's safe, because Latin words survive segmentation intact, so pages in English (or any spaced language) stay searchable alongside the default language.
 
+Japanese and Chinese go one step further. Segmenting alone indexes a compound term as its parts — 資金決済法 as 資金, 決済 and 法 — which lets a page mentioning each part somewhere outrank the page the term is actually about. Han, Hiragana and Katakana are therefore indexed as overlapping character pairs, and queries on those indexes prefer pages carrying a term's pairs together, loosening to any-pair matching when no page carries them all, so typing a whole sentence still returns its closest pages. Korean and Thai keep their segmented words.
+
 ### 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`.

package/docs/configuration/seo.mdx

@@ -149,9 +149,27 @@ Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and
 
 Emoji in a page title or site title render as [Twemoji](https://github.com/jdecked/twemoji) glyphs, fetched from a CDN while the card renders — so a build whose titles contain emoji needs network access. Each glyph is fetched once per build, however many pages use it.
 
-### Non-Latin titles
+### Show, hide, or override card layers
 
-The card's built-in font covers only Latin glyphs, so a title in another script (Japanese, Chinese, Korean, Arabic, …) renders as tofu — empty boxes. List one or more [Google Fonts](https://fonts.google.com) families in `og.fonts` that cover your script, by name:
+Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (your site `description`), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    site: "docs.acme.com", // footer URL text, or false to hide it
+    description: false, // hide the subtitle; a string overrides it
+    logo: false, // no brand mark at all — not even the initial tile
+  },
+}
+```
+
+### Card fonts
+
+By default the card renders in Takumi's built-in font, which covers only Latin glyphs — a title in another script (Japanese, Chinese, Korean, Arabic, …) would render as tofu, empty boxes.
+
+**Set [`theme.fonts`](/docs/configuration/theming#fonts) and the card follows it.** When your config picks its own fonts, the generated cards automatically render the headline in your display font and the description and footer in your body font, so shared links match the site — including non-Latin coverage, with nothing to configure here. (Families from non-Google providers are skipped — the card renderer can only fetch from Google Fonts — but local font files work.)
+
+To use different fonts on cards than on the site, or to add script coverage without touching the theme, set `og.fonts` explicitly — it always wins over the theme-derived fonts:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -159,12 +177,17 @@ seo: {
     fonts: [
       "Noto Sans JP",
       { name: "Inter", weight: [400, 700] },
+      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
     ],
   },
 }
 ```
 
-Each entry is a family name, or an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both). The families are fetched from Google Fonts at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the built-in font can't draw; Latin text renders exactly as before.
+Each entry is a Google Fonts family name, an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both), or a local font file — `src` resolves from the project root, with optional `weight` and `style` when the file's own metadata shouldn't decide.
+
+Google families are fetched at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the other fonts can't draw.
+
+An explicit `og.fonts: []` opts out entirely: cards keep the built-in font even when `theme.fonts` is set.
 
 ### Custom page titles
 

package/docs/configuration/theming.mdx

@@ -79,7 +79,7 @@ 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).
 
-Each value is a Google Fonts slug from the curated set below:
+A bare string is a Google Fonts slug from the curated set below:
 
 | Category | Slugs |
 | --- | --- |
@@ -87,7 +87,49 @@ Each value is a Google Fonts slug from the curated set below:
 | 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`](#themecss).
+#### Any provider family
+
+Need a family that isn't in the curated set — say, one that covers a non-Latin script? Pass an object with the family's exact name. It's self-hosted and optimized the same way:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  fonts: {
+    display: { name: "Noto Sans JP", weights: [400, 700] },
+    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
+  },
+}
+```
+
+- **`name`** — the family name exactly as the provider lists it.
+- **`provider`** — where the family comes from: `google` (default), `fontsource`, `bunny`, or `fontshare`.
+- **`weights`** — the weights to load, as numbers or a variable range like `"100..900"`. Defaults to `[400, 500, 600, 700]`.
+- **`fallback`** — the system stack shown while the font loads and for missing glyphs: `sans`, `serif`, or `mono`. Defaults to `mono` for the mono role and `sans` otherwise.
+
+#### Local font files
+
+For a font you own (or one no provider serves), point a role at font files in your project. Each variant becomes one `@font-face`:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  fonts: {
+    display: {
+      name: "Berkeley Mono",
+      variants: [
+        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
+        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
+      ],
+    },
+  },
+}
+```
+
+Paths resolve from the project root. `weight` and `style` (`normal`, `italic`, `oblique`) are optional — Astro reads them from the font file when omitted.
+
+:::note
+When you set `theme.fonts` explicitly, your display and body fonts also style the generated [Open Graph cards](/docs/configuration/seo#card-fonts) automatically, so shared links match the site. Non-Google provider families are skipped there (the card renderer can only fetch from Google Fonts); local files work everywhere.
+:::
+
+Want to drop back to the system stack? Override the `--blume-font-*` tokens directly in [`theme.css`](#themecss).
 
 ### Dark-mode colors
 

package/docs/content/syntax.mdx

@@ -94,18 +94,34 @@ Tabulate structured data — config options, comparison matrices, parameter list
 | `blume build` | Build the static site | `dist/` |
 ```
 
+For a table without a header row — key–value pairs, for example — leave the header cells empty. Markdown requires the header and divider rows syntactically, but Blume drops the empty header from the rendered table.
+
+```md
+|                |          |
+| -------------- | -------- |
+| Current status | E-3 visa |
+```
+
 ## Links and images
 
-Link to other pages or external sites. Images accept any path under `public/` (served at the site root) or a remote URL.
+Link to other pages or external sites. Images accept a relative path to a file next to your content, any path under `public/` (served at the site root), or a remote URL.
 
 Read the [quickstart](/docs/quickstart) to get started.
 
 ```md
 Read the [quickstart](/docs/quickstart) to get started.
 
-![Alt text](/screenshot.png)
+![Alt text](./screenshot.png)
 ```
 
+**Prefer relative paths for local images** — they're optimized at build time: compressed, converted to WebP, and stamped with intrinsic `width`/`height` so the page doesn't shift while loading. Keep the image next to the page that uses it (or in a shared folder inside your content directory) and reference it relatively:
+
+```md
+![Build output](./images/build-output.png)
+```
+
+Absolute paths under `public/` (`![Alt text](/screenshot.png)`) are served verbatim with no optimization — use them for files that must keep their exact bytes and URL, like a logo referenced from outside your docs. Remote images are also passed through untouched unless their host is authorized in the [`image` config](/docs/configuration#images).
+
 Content images are click-to-zoom by default — readers can click any image to open it in a lightbox. Turn this off with `markdown: { imageZoom: false }` in `blume.config.ts`, or opt a single image out with `data-no-zoom`.
 
 ## Horizontal rule

package/docs/reference/cli.mdx

@@ -56,7 +56,7 @@ blume <command> [options]
 - `blume audit --external` — probe outbound links over the network.
 - `blume audit --only <check|category>` / `--skip <check|category>` — narrow the report while you work through it (comma-separated).
 - `blume audit --list-checks` — print every check the audit can report.
-- `blume audit --verbose` — list every affected page instead of the first few.
+- `blume audit --verbose` — list every affected page with each finding's full detail, such as which link target is broken.
 - `blume audit --json` — emit the report as JSON on stdout.
 - `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
 - `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
@@ -140,7 +140,7 @@ blume build
 blume audit
 ```
 
-Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.
+Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page with its full detail, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.
 
 ### Failing CI
 
@@ -186,6 +186,6 @@ Two limits worth stating plainly:
 Anything the audit did not run is reported as skipped rather than silently passing:
 
 ```
-⊘ network      skipped — pass --url <origin> (9 checks)
+⊘ network      skipped — pass --url <origin> (11 checks)
 ⊘ external     skipped — pass --external (2 checks)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -87,7 +87,7 @@
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^5.0.0",
+    "ai": "^7.0.42",
     "astro": "^7.0.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "citty": "^0.1.6",
@@ -98,7 +98,7 @@
     "gray-matter": "^4.0.3",
     "jiti": "^2.4.0",
     "js-yaml": "^4.1.0",
-    "katex": "^0.17.0",
+    "katex": "^0.18.1",
     "marked": "^18.0.5",
     "mermaid": "^11.15.0",
     "node-html-parser": "^9.0.0",
@@ -107,15 +107,16 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "satteri": "^0.9.5",
+    "sharp": "^0.35.3",
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
-    "tailwindcss": "^4.3.0",
+    "tailwindcss": "^4.3.3",
     "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",
-    "zod": "^3.24.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
@@ -126,16 +127,16 @@
     "bun-types": "^1.3.14"
   },
   "peerDependencies": {
-    "@ai-sdk/openai-compatible": "^1.0.41",
+    "@ai-sdk/openai-compatible": "^3.0.0",
     "@astrojs/cloudflare": "^14.0.0",
     "@astrojs/netlify": "^8.0.0",
     "@astrojs/svelte": "^9.0.0",
     "@astrojs/vue": "^7.0.0",
     "@mixedbread/sdk": "^0.76.0",
     "@notionhq/client": "^2.2.15",
-    "@openrouter/ai-sdk-provider": "^1.5.4",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@oramacloud/client": "^2.1.0",
-    "@sanity/client": "^6.21.0",
+    "@sanity/client": "^6.21.0 || ^7.0.0",
     "algoliasearch": "^5.55.0",
     "flexsearch": "^0.8.0",
     "typesense": "^3.0.0"

package/skills/blume/SKILL.md

@@ -64,10 +64,12 @@ The Blume CLI discovers your content, builds a content graph, and generates a hi
 
 ## Full documentation
 
-This is a high-level overview. For complete, authoritative docs — configuration reference, every CLI command and flag, component APIs, content authoring, navigation, search, SEO, AI features, theming, and deployment — read the bundled docs in the installed package:
+This is a high-level overview. For complete, authoritative docs — configuration reference, every CLI command and flag, component APIs, content authoring, navigation, search, SEO, AI features, theming, and deployment — read the `docs/` directory bundled inside the installed `blume` package.
 
-```
-node_modules/blume/docs
+**Locate the package first — it is not always at the repository root.** In a workspace monorepo (pnpm especially), `blume` is installed in the depending workspace's `node_modules` (e.g. `apps/docs/node_modules/blume/docs`), not the root. From the package that depends on `blume`, this prints the exact location:
+
+```bash
+node -e "console.log(require.resolve('blume/package.json'))"
 ```
 
-Start with `node_modules/blume/docs/index.mdx` (Introduction) and `node_modules/blume/docs/01-quickstart.mdx`, then browse the `configuration/`, `content/`, `reference/`, and `advanced/` sections for specifics.
+The docs sit in `docs/` next to that `package.json`. Start with `docs/index.mdx` (Introduction) and `docs/01-quickstart.mdx`, then browse the `configuration/`, `content/`, `reference/`, and `advanced/` sections for specifics.