blume 1.0.3 → 1.1.0

package/dist/types/core/sources/types.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedI18nConfig } from "../schema.ts";
+import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 /**
  * A single content item, normalized by a source adapter. Adapters lower their
@@ -111,5 +111,7 @@ export interface NormalizeContext {
     /** Site-wide route mount point (`""` or `/seg`), prepended to every route. */
     basePath?: string;
     defaultType: string;
+    /** Opt-in custom frontmatter keys (`frontmatter.extend`), schema per key. */
+    frontmatterExtend?: FrontmatterExtend;
     i18n?: ResolvedI18nConfig;
 }

package/dist/types/core/standard-schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), the minimal
+ * `~standard` surface shared by Zod 3.24+, Zod 4, Valibot, ArkType, and
+ * friends. Blume accepts user-supplied validation schemas (e.g.
+ * `frontmatter.extend`) through this interface instead of Zod's own types:
+ * `blume.config.ts` imports zod from the *consumer's* node_modules, which may
+ * be a different major version than the zod Blume bundles, and calling Zod
+ * methods (`.extend()`, `.safeParse()`) across instances is unsupported. The
+ * `~standard.validate` contract is version- and library-agnostic.
+ */
+/** One validation failure, with an optional path into the checked value. */
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}
+/** A passing validation: the (possibly transformed) output value. */
+export interface StandardSchemaSuccess<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+/** A failing validation: one or more issues. */
+export interface StandardSchemaFailure {
+    readonly issues: readonly StandardSchemaIssue[];
+}
+export type StandardSchemaResult<Output> = StandardSchemaSuccess<Output> | StandardSchemaFailure;
+/** A validation schema exposing the Standard Schema `~standard` contract. */
+export interface StandardSchema<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/** Whether a config-supplied value implements the `~standard` contract. */
+export declare const isStandardSchema: (value: unknown) => value is StandardSchema;

package/dist/types/core/types.d.ts

@@ -12,6 +12,13 @@ export interface Diagnostic {
     file?: string;
     line?: number;
     column?: number;
+    /**
+     * The built URL this diagnostic is about, for findings that are a property of
+     * the output rather than of a source file (`blume audit`). Set alongside
+     * `file`/`line` where the page maps back to authored content, so a finding can
+     * name both the URL that's wrong and the frontmatter line that fixes it.
+     */
+    url?: string;
     schemaPath?: string;
     suggestion?: string;
     docsUrl?: string;
@@ -110,6 +117,12 @@ export interface PageRecord {
     description?: string;
     contentType: string;
     meta: PageMeta;
+    /**
+     * Custom frontmatter values declared via `frontmatter.extend`, validated by
+     * the user-supplied schemas (schema output, so transforms apply). Present
+     * only when the project opts in and the page carries at least one value.
+     */
+    custom?: Record<string, unknown>;
     headings: Heading[];
     /** Whether the file is `.md`/`.mdx`. */
     format: "md" | "mdx";
@@ -150,7 +163,17 @@ export type NavNode = {
 /** Top-level tab/section. */
 export interface NavTab {
     label: string;
+    /**
+     * The tab's section prefix, used to scope the sidebar and match the active
+     * tab. Not necessarily a linkable route — a section may have no index page.
+     */
     path: string;
+    /**
+     * The clickable target. Equals `path` when the section has an index page;
+     * otherwise it's resolved to the section's first page so the tab never links
+     * to a 404. Absent when it matches `path`.
+     */
+    href?: string;
     icon?: string;
     items?: NavSelectorItem[];
 }

package/dist/types/og/card.d.ts

@@ -0,0 +1,63 @@
+import type { RenderOptions } from "takumi-js";
+/**
+ * A Google Font family to load into the OG card renderer. A bare string is the
+ * family name (weight 400, normal style); the object form pins weight and style.
+ * Handed straight to Takumi's `googleFonts` helper, which fetches the family
+ * from Google Fonts at build and returns per-glyph coverage subsets.
+ */
+export type OgFont = string | {
+    /** Google Fonts family name, e.g. `"Noto Sans JP"`. */
+    name: string;
+    /** `400`, `[400, 700]`, or a variable range like `"100..900"`. */
+    weight?: number | number[] | string;
+    /** `"normal"`, `"italic"`, or both. */
+    style?: "normal" | "italic" | ("normal" | "italic")[];
+};
+export interface OgCardPalette {
+    accent?: string;
+    background?: string;
+    border?: string;
+    foreground?: string;
+    muted?: string;
+}
+export interface OgCardOptions {
+    /** Large headline — the page title. */
+    title: string;
+    /** Accent color (named preset or any CSS color) for the fallback brand mark. */
+    accent?: string;
+    /** Brand/site name shown in the top-left lockup. */
+    brand?: string;
+    /** Muted subtitle under the headline (usually the site description). */
+    description?: string;
+    /**
+     * Inlined SVG markup of the configured logo, painted into
+     * the brand lockup. Falls back to an accent mark when absent.
+     */
+    logo?: string;
+    /** Optional colors for the generated card. */
+    palette?: OgCardPalette;
+    /** Footer-left repository slug, e.g. `owner/repo`. */
+    repo?: string;
+    /** Footer-right site host, e.g. `docs.acme.com`. */
+    site?: string;
+    /**
+     * Pre-fetched image entries, or a group controlling how remote images (and
+     * emoji glyphs) are fetched. Blume merges in a shared glyph cache; see
+     * {@link resolveImages}.
+     */
+    images?: RenderOptions["images"];
+    /**
+     * Google Font families for non-Latin titles. Takumi's built-in font covers
+     * only Latin, so a CJK (etc.) title renders as tofu without a family that
+     * covers its script — see {@link loadFonts}.
+     */
+    fonts?: OgFont[];
+}
+/**
+ * Truncate to `max` code points with an ellipsis. Slices by code points, not
+ * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
+ * glyph) before the ellipsis.
+ */
+export declare const truncate: (value: string, max: number) => string;
+/** Render a 1200x630 Open Graph card to a PNG buffer. */
+export declare const renderOgImage: (options: OgCardOptions) => Promise<Uint8Array>;

package/dist/types/og/dimensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Dimensions of a generated OG card, shared by the renderer (`card.ts`) and the
+ * layouts that declare them as `og:image:width`/`og:image:height` so a crawler
+ * can lay out the card without fetching the PNG first.
+ *
+ * This lives apart from `card.ts` because that module imports the Takumi native
+ * binding at load; a layout importing it would drag the renderer into every
+ * page render (and into the prerender/SSR bundles that externalize it).
+ */
+export declare const OG_IMAGE_WIDTH = 1200;
+export declare const OG_IMAGE_HEIGHT = 630;
+export declare const OG_IMAGE_TYPE = "image/png";

package/dist/types/openapi/references.d.ts

@@ -1,11 +1,10 @@
 import type { ResolvedConfig } from "../core/schema.ts";
-import type { NavTab } from "../core/types.ts";
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
- * labels, and a renderer choice — no file IO, so the content source, the nav
- * tabs, the Scalar page generator, and the `blume:openapi` data module all share
- * one source of truth. Kept free of any Astro/template imports so `core` can
- * depend on it without a cycle.
+ * labels, and a renderer choice — no file IO, so the content source, the
+ * nav-target validation, the Scalar page generator, and the `blume:openapi`
+ * data module all share one source of truth. Kept free of any Astro/template
+ * imports so `core` can depend on it without a cycle.
  */
 export type ReferenceKind = "openapi" | "asyncapi";
 /** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
@@ -52,8 +51,14 @@ export declare const normalizeRoute: (route: string) => string;
  * by default); AsyncAPI is always rendered by Scalar for now.
  */
 export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSource[];
-/** Nav tabs (header links) for every reference, regardless of renderer. */
-export declare const referenceTabs: (config: ResolvedConfig) => NavTab[];
+/**
+ * Mounted route for every reference, regardless of renderer. References no
+ * longer add a header tab automatically — authors point a `navigation.tabs`
+ * entry at one of these routes to surface it (and, for Blume-rendered specs, to
+ * scope its operations sidebar). These routes are whitelisted as valid nav
+ * targets so such a tab doesn't read as a broken link.
+ */
+export declare const referenceRoutes: (config: ResolvedConfig) => string[];
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
 /** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */

package/docs/01-quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-description: Install Blume, scaffold a project, and ship your first page in minutes.
+description: Install Blume, scaffold a new project, and ship your first documentation page in minutes — then grow it into a full site at your own pace.
 sidebar:
   label: Quickstart
   order: 1

package/docs/02-deployment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Deployment
-description: Deploy static docs to any host, or switch to server rendering with an adapter.
+description: Deploy static docs to any host with zero configuration, or switch to server-side rendering with an adapter when you need dynamic behavior.
 sidebar:
   label: Deployment
   order: 2
@@ -119,6 +119,14 @@ redirects: [{ from: "/old", to: "/new", status: 301 }];
 `from` is matched as an exact path — wildcards and pattern matching (e.g. `/blog/:slug` or `/old/*`) aren't supported. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
 :::
 
+:::note
+Write both `from` and `to` as if mounted at root — under [`deployment.base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
+:::
+
+## Content types
+
+A static build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify and Cloudflare (Pages/Workers static assets) read `_headers`; hosts that don't (Vercel, S3) ignore the file harmlessly. A `_headers` you ship in `public/` is left untouched.
+
 ## Environment variables
 
 When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's missing — so the problem surfaces early instead of at the first request:

package/docs/advanced/api-reference.mdx

@@ -3,7 +3,7 @@ title: OpenAPI / AsyncAPI
 description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. These docs ship one: the [Example API](/api) reference is generated from the Petstore spec by the config below.
+Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. The config below points Blume at the public Petstore spec as an example.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -12,7 +12,15 @@ openapi: {
 }
 ```
 
-That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`, and adds a header tab. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
+That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
+
+The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the operations sidebar for the native renderer:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [{ label: "API", path: "/reference" }],
+}
+```
 
 :::note
 Operations are indexed for search by their **summary and tag**. The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title and section, then links to its own page.
@@ -31,7 +39,7 @@ openapi: {
 
 ## Route
 
-`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the header tab's target):
+`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the route you point a navigation tab at):
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -70,6 +78,17 @@ openapi: {
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
+## Authorization
+
+Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.
+
+The OpenAPI semantics carry over as written:
+
+- An operation's own `security` overrides the document's root default; `security: []` marks it **public** and renders no Authorization section.
+- Multiple requirement entries are alternatives — rendered as "or" groups; every scheme inside one entry is required together. The first alternative feeds the code samples.
+- An empty `{}` entry means auth is **optional** for that operation, and the section says so.
+- OAuth2 scopes are listed per scheme; scheme `description`s from `components.securitySchemes` render inline.
+
 ## The Scalar renderer
 
 The native renderer is the default. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference — its own sidebar, search, theme, and "Try it" playground on a single route — set `renderer: "scalar"`:

package/docs/advanced/changelog.mdx

@@ -1,6 +1,6 @@
 ---
 title: Changelog
-description: Author release notes as content, and Blume builds a timeline page and an RSS feed automatically.
+description: Author release notes as ordinary content files or source them from GitHub Releases, and Blume builds a timeline page and an RSS feed automatically.
 ---
 
 Blume ships a changelog out of the box. Write each release as a normal content file, mark it `type: changelog`, and Blume collects every entry into a generated timeline page and an RSS feed — no layout to build, no list to maintain. Or skip the files entirely and [source your changelog from GitHub Releases](#from-github-releases).

package/docs/advanced/skills.mdx

@@ -1,6 +1,6 @@
 ---
 title: Skills
-description: The agent skills Blume ships — playbooks that teach a coding agent to build and maintain a Blume docs site.
+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.

package/docs/configuration/ai.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI
-description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
+description: Make your docs machine-readable with llms.txt, add an optional in-page Ask AI assistant, and expose a hosted MCP server for coding agents.
 ---
 
 Blume has a few AI features: machine-readable docs for external tools (`llms.txt`, on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.

package/docs/configuration/customization.mdx

@@ -1,6 +1,6 @@
 ---
 title: Customization
-description: Override components, add interactive islands, mount custom pages, install registry components, or eject.
+description: Override components, add interactive islands, mount custom pages, install registry components, or eject entirely when you need full control.
 ---
 
 ## Component overrides

package/docs/configuration/export.mdx

@@ -1,6 +1,6 @@
 ---
 title: Export
-description: Let readers download any page as a PDF or EPUB — client-side, so static builds stay static.
+description: Let readers download any page as a PDF or EPUB — rendered client-side, so your static builds stay static and need no server infrastructure.
 ---
 
 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.

package/docs/configuration/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configuration file
-description: Every option in blume.config.ts — site metadata, content, and links to each feature guide.
+description: Every option in blume.config.ts, from site metadata and content sources to the links that lead into each individual feature configuration guide.
 sidebar:
   label: blume.config.ts
 ---
@@ -188,6 +188,26 @@ content: {
 
 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`.
 
+## Frontmatter
+
+Page frontmatter is strictly validated — an unknown key fails the build, so typos are caught early. To carry project-specific metadata (an owner, a review date), declare the extra keys under `frontmatter.extend`, each mapped to a schema you supply:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  frontmatter: {
+    extend: {
+      owner: z.string(),
+      reviewedAt: z.coerce.date().optional(),
+    },
+  },
+});
+```
+
+Any [Standard Schema](https://standardschema.dev) library works — Zod (whichever version your project installs), Valibot, ArkType. Keys outside the extension stay strictly validated, so typo-catching is unchanged. See [Custom keys](/docs/reference/frontmatter#custom-keys) for the validation semantics.
+
 ## GitHub
 
 Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):

package/docs/configuration/search.mdx

@@ -1,6 +1,6 @@
 ---
 title: Search
-description: Client-side search out of the box, with optional hosted and semantic backends.
+description: Client-side search that works out of the box with no API keys, plus optional hosted and semantic backends you can switch to as your docs grow.
 ---
 
 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.
@@ -13,6 +13,33 @@ Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/
 
 Queries match page **titles**, **descriptions**, and **body text**, with title matches ranked highest and descriptions above body.
 
+## Popular pages
+
+Before a reader types a query, the search dialog shows a **Popular** list. By default it is the first six sidebar pages — which on multi-tab sites often surfaces the wrong section. Pin the links you want instead:
+
+```ts blume.config.ts lineNumbers
+search: {
+  popular: [
+    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
+    { href: "/guides/install", icon: "download", label: "Install" },
+    { href: "/concepts/overview", label: "Overview" },
+  ],
+},
+```
+
+Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a built-in icon name shown beside the label, defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.
+
+Unlike icons elsewhere in Blume, `icon` here must be a built-in name: these rows render in a client island, so an image path or inline SVG isn't supported and falls back to the file glyph.
+
+Write `href` as if the site were mounted at the root — a `basePath` is applied for you, the same as `navigation.featured`. External URLs pass through untouched.
+
+<Callout type="warning">
+  A curated list is a single set of links shared by every language. On a site
+  with `i18n` configured, the sidebar fallback follows the reader's locale, but
+  `popular` entries point wherever their `href` says — so pin locale-prefixed
+  routes only if you want every reader sent to that one language.
+</Callout>
+
 ## 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.

package/docs/configuration/seo.mdx

@@ -106,7 +106,26 @@ 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:
+### Brand the generated card
+
+Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    logo: "/logo/og.svg",
+    palette: {
+      accent: "#ff5410",
+      background: "#1d1d1d",
+      foreground: "#fff6f2",
+      muted: "#a6a19f",
+      border: "#323232",
+    },
+  },
+}
+```
+
+By default, 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                  |
 | ------------------- | -------------------------- |
@@ -125,9 +144,28 @@ 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.
+Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and so on. The accent also accepts a named preset (`blue`, `teal`, …), matching [`theme.accent`](/docs/configuration/theming#accent). A color the renderer can't parse fails the build rather than silently shipping a default-colored card.
 :::
 
+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
+
+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:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    fonts: [
+      "Noto Sans JP",
+      { name: "Inter", weight: [400, 700] },
+    ],
+  },
+}
+```
+
+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.
+
 `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

package/docs/configuration/theming.mdx

@@ -1,6 +1,6 @@
 ---
 title: Theming
-description: Tune the look with config tokens, override any CSS variable in theme.css, or use Tailwind utilities.
+description: Tune the look with a handful of config tokens, override any CSS variable in theme.css, or drop down to 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.

package/docs/content/components.mdx

@@ -69,6 +69,20 @@ Switch between equivalent content in place — language variants, OS-specific co
 </Tabs>
 ```
 
+Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page.
+
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+
+```astro lineNumbers
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+```
+
 ## Badge
 
 A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning.
@@ -619,7 +633,6 @@ An Astro example renders live with no client JavaScript:
 
 <CodeBlock
   lang="ts"
-  icons={false}
   code={`export const greet = (name: string): string =>
   \`Hello, \${name}!\`;`}
 />
@@ -629,7 +642,7 @@ An Astro example renders live with no client JavaScript:
 import CodeBlock from "blume/components/content/CodeBlock.astro";
 ---
 
-<CodeBlock lang="ts" code={source} icons={false} />
+<CodeBlock lang="ts" code={source} />
 ```
 
 To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:

package/docs/content/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Pages
-description: How files in your content folder become pages, and how to organize them.
+description: How the files in your content folder become pages, and how to organize and name them so routing and navigation are inferred automatically.
 ---
 
 Your docs are just a folder of Markdown and MDX files. Blume turns each file into a page — routing, navigation, and metadata are inferred from the file system, so there's no manifest to keep in sync.

package/docs/content/meta.mdx

@@ -1,6 +1,6 @@
 ---
 title: Folder meta
-description: Configure a sidebar group — its title, icon, order, and page order — with a meta.ts file.
+description: Configure a sidebar group with a meta.ts file beside its pages — set the group's title, icon, order, and the order of the pages nested inside.
 ---
 
 Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).

package/docs/content/navigation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Navigation
-description: Build the sidebar from your files, then refine it with frontmatter, folder meta, or config.
+description: Blume builds the sidebar from your files, then lets you refine it with frontmatter, folder meta, or config — breadcrumbs and outlines follow along.
 ---
 
 Blume builds your sidebar from the file system, then lets you refine it as much — or as little — as you want: page by page, folder by folder, or with one explicit config. Breadcrumbs, previous/next links, and the on-page outline all follow from the same model, with nothing to wire up.
@@ -109,6 +109,16 @@ navigation: {
 }
 ```
 
+An enabled [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) mounts at its route but doesn't add a tab on its own — point a tab at that route to surface it in the header (and, for the native renderer, to scope its operations sidebar), with whatever label you like:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [
+    { label: "API", path: "/reference" },
+  ],
+}
+```
+
 Tabs also **scope the sidebar**: when the current route falls under a tab's `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the adapters and nothing else. The folder at a tab's `path` becomes the section, so this needs no extra config beyond the tabs themselves; structure your content into a folder per tab and point each tab at it.
 
 On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the pages that _don't_ belong to a tab — each tab's folder is hidden from it, since that section already has its own tab in the header. So a root landing page lists your loose top-level pages while the sectioned content stays behind its tab, mirroring Fumadocs' root folders. If a route has no pages of its own to show this way, the full tree is shown instead, so the sidebar is never left blank.

package/docs/content/sources.mdx

@@ -1,6 +1,6 @@
 ---
 title: Content sources
-description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
+description: Pull docs from local files, a remote repository, or any custom backend — and mix several sources into one static-first site read at build time.
 ---
 
 By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.