blume 1.6.2 → 1.6.4

package/docs/discoverability/open-graph.mdx

@@ -0,0 +1,113 @@
+---
+title: Open Graph images
+description: Generated 1200×630 social cards for every page — branding, card layers, fonts for non-Latin scripts, and per-page overrides.
+---
+
+Blume can render a 1200×630 social card for every page at build time — no headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay fast. On by default once [`deployment.site`](/docs/deployment) is set or auto-detected (the `og:image` URL has to be absolute to be useful to crawlers), and off otherwise. Set `enabled` to override that either way:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: { enabled: true }, // or false to opt out even with a site set
+}
+```
+
+## 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, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), 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               |
+| ---------------- | ----------------------- |
+| `/`              | `/og/index.png`         |
+| `/quickstart`    | `/og/quickstart.png`    |
+| `/guides/deploy` | `/og/guides/deploy.png` |
+
+Override the generated card for any page with `seo.image` — a file in `public/` or an external URL. It takes precedence over the generated card and works even when `og` is off, so you can mix custom images with generated ones:
+
+```yaml lineNumbers
+---
+title: Pricing
+seo:
+  image: /og/pricing-custom.png
+---
+```
+
+:::note
+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.
+
+## Show, hide, or override card layers
+
+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 (the page `description`, or your site `description` for pages without one), 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 on every card; a string replaces the site fallback
+    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: {
+  og: {
+    fonts: [
+      "Noto Sans JP",
+      { name: "Inter", weight: [400, 700] },
+      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
+    ],
+  },
+}
+```
+
+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
+
+A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    titles: {
+      "/cli": "CLI",
+    },
+  },
+}
+```
+
+Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.
+
+`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`.

package/docs/discoverability/rss.mdx

@@ -0,0 +1,24 @@
+---
+title: RSS feeds
+description: A feed per dated content type — blog and changelog by default — served at /<type>/rss.xml and advertised to feed readers automatically.
+---
+
+Blume builds an RSS feed for each content type in `rss.types` — `blog` and `changelog` by default — that has pages, served at `/<type>/rss.xml`. See [Feeds](/docs/content#feeds) for authoring blog and changelog entries with dates.
+
+```ts blume.config.ts lineNumbers
+seo: {
+  rss: {
+    enabled: true,
+    types: ["blog", "changelog"],
+    limit: 50,
+  },
+}
+```
+
+| Option    | Default                 | Description                           |
+| --------- | ----------------------- | ------------------------------------- |
+| `enabled` | `true`                  | Generate feeds.                       |
+| `types`   | `["blog", "changelog"]` | Content types that each get a feed.   |
+| `limit`   | `50`                    | Maximum items per feed, newest first. |
+
+Blume injects `<link rel="alternate">` tags so browsers and feed readers discover the feeds automatically, and lists them in the [agent readability manifest](/docs/discoverability/agent-discovery#agent-readability) so agents find them too. Item links are absolute when [`deployment.site`](/docs/deployment) is set.

package/docs/discoverability/sitemap-and-robots.mdx

@@ -0,0 +1,95 @@
+---
+title: Sitemap and robots
+description: The sitemap.xml and robots.txt Blume writes for crawlers, and the Content-Signal line that tells AI crawlers how they may use your docs.
+---
+
+Search crawlers and AI crawlers both start from the same two files at your site root. Blume writes both on every build, and the `robots.txt` carries the content-usage signals that AI crawlers look for, so this is where the search side and the agent side of discoverability meet.
+
+## Sitemap
+
+Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and [`noindex`](/docs/discoverability/metadata#per-page-overrides) pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  sitemap: true,
+}
+```
+
+Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file you place in `public/`.
+
+## Robots
+
+Blume writes a `robots.txt` that allows all crawlers, declares your [content signals](#content-signals), and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  robots: true,
+}
+```
+
+```txt robots.txt
+User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=yes
+Allow: /
+
+Sitemap: https://docs.example.com/sitemap.xml
+```
+
+### Content signals
+
+The `Content-Signal` line — the emerging content-usage convention — declares how AI crawlers may reuse your docs. Blume emits it **on by default with every signal set to `yes`**, matching its stance that docs are open to humans and agents alike:
+
+- `search` — traditional and AI search indexing
+- `aiInput` — grounding / RAG at answer time
+- `aiTrain` — model training
+
+Restrict any signal by setting it to `false`; the ones you leave out stay `yes`:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: {
+    aiTrain: false, // opt out of training, keep search + grounding
+  },
+}
+```
+
+```txt robots.txt
+User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=no
+Allow: /
+```
+
+Set `contentSignals: false` to drop the declaration entirely:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: false,
+}
+```
+
+<TypeTable
+  type={{
+    "seo.contentSignals": {
+      type: "boolean | object",
+      description:
+        "Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually.",
+    },
+    "contentSignals.search": {
+      type: "boolean",
+      description: "Allow use for search indexing (search). Default true.",
+    },
+    "contentSignals.aiInput": {
+      type: "boolean",
+      description:
+        "Allow use for AI grounding / RAG at answer time (ai-input). Default true.",
+    },
+    "contentSignals.aiTrain": {
+      type: "boolean",
+      description: "Allow use for AI model training (ai-train). Default true.",
+    },
+  }}
+/>
+
+Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honor them. The same policy is mirrored as `contentUsage` in the [agent readability manifest](/docs/discoverability/agent-discovery#agent-readability), so an agent that never reads `robots.txt` still sees it.
+
+Ship your own `public/robots.txt` to take over.

package/docs/discoverability/structured-data.mdx

@@ -0,0 +1,51 @@
+---
+title: Structured data
+description: The schema.org JSON-LD every page carries — WebSite, article, and breadcrumb nodes — plus the optional Organization and SoftwareApplication blocks that tell search engines and agents who you are.
+---
+
+Blume emits [schema.org](https://schema.org) JSON-LD in every page's `<head>` so search engines understand your content. On by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  structuredData: true,
+}
+```
+
+Each page includes:
+
+- a **WebSite** node for site identity,
+- the page as an **article** — `BlogPosting` for blog posts, `TechArticle` for changelog and docs — with its description and publish date,
+- a **BreadcrumbList** built from the navigation trail.
+
+URLs are absolute when [`deployment.site`](/docs/deployment) is set. Pages marked [`seo.noindex`](/docs/discoverability/metadata#per-page-overrides) are skipped. When [`lastModified`](/docs/configuration#last-modified) is on, each page's date is also emitted as `dateModified`.
+
+## Site identity
+
+The WebSite node says a site exists; it doesn't say _what_ it is or _who_ runs it — which is what AI agents read JSON-LD for before they recommend or cite you. Two optional blocks fill that in, both needing `deployment.site` (the nodes carry absolute identifiers):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  organization: {
+    name: "Acme", // defaults to the site title
+    email: "hello@acme.com",
+    telephone: "+1 555 0100",
+    address: { addressLocality: "Sydney", addressCountry: "AU" },
+    logo: "/logo.svg",
+    sameAs: ["https://github.com/acme", "https://x.com/acme"],
+  },
+  software: {
+    license: "MIT",
+    operatingSystem: "Node.js 22+",
+    price: 0, // emitted as an Offer; 0 marks it free
+    sameAs: ["https://www.npmjs.com/package/acme"],
+  },
+}
+```
+
+`organization` adds an **Organization** node to every page — the WebSite and article nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.
+
+`software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.
+
+## Custom pages
+
+A custom [`.astro` page](/docs/advanced/custom-pages) rendered through `PageLayout` emits the same `WebSite` graph, so a marketing home page isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with this setting, or `structuredDataEnabled={false}` to turn it off for that page alone.

package/docs/index.mdx

@@ -31,7 +31,7 @@ Blume builds on Astro and Vite and renders static HTML by default — fast, cach
 
 ### AI-ready out of the box
 
-Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/configuration/ai#json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
+Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/discoverability/llms-txt), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/discoverability/json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/discoverability/mcp) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
 
 ### Zero configuration — even the template
 
@@ -45,9 +45,9 @@ Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/conten
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with [no imports](/docs/content/components).
 - **Local search** — Orama works in dev and production; Pagefind is one flag away for large sites. No hosted index.
-- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
+- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, and a hosted MCP server](/docs/discoverability), plus an optional [Ask AI assistant](/docs/configuration/ask-ai).
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
-- **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
+- **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/discoverability).
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
 - **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
 
@@ -64,8 +64,8 @@ The Blume CLI discovers your content, builds a content graph, and generates a hi
   <Card title="Components" href="/docs/content/components" icon="folder">
     Explore the built-in component library.
   </Card>
-  <Card title="AI" href="/docs/configuration/ai" icon="lightbulb">
-    Ship `llms.txt` and an Ask AI assistant.
+  <Card title="Discoverability" href="/docs/discoverability" icon="lightbulb">
+    Ship `llms.txt`, social cards, and an MCP server.
   </Card>
   <Card title="CLI" href="/docs/reference/cli" icon="rocket">
     Every `blume` command and flag.

package/docs/reference/eval.mdx

@@ -26,7 +26,7 @@ blume eval  3 question(s) · Claude Code
 
 Each question runs through two agent sessions, using an agent CLI you already have installed — [Claude Code](https://claude.com/claude-code) by default, or [Codex](https://developers.openai.com/codex/cli) with `--agent codex`. Blume holds no API keys and calls no model itself.
 
-1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/configuration/ai) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
+1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/discoverability/mcp) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
 2. **The judge** grades the answer against the facts you listed, with no tools at all. Paraphrase passes; a missing or contradicted fact fails — and so does "the documentation doesn't say."
 
 The MCP snapshot is built from your content sources directly, so there is no need to run `blume build` first, and nothing is deployed or uploaded anywhere.

package/docs/reference/meta.ts

@@ -1,7 +1,7 @@
 import { defineMeta } from "blume";
 
 export default defineMeta({
-  order: 6,
+  order: 7,
   pages: ["frontmatter", "cli", "eval", "translate"],
   title: "Reference",
 });

package/docs/reference/translate.mdx

@@ -44,6 +44,7 @@ The agent is never trusted with structure. Before writing, Blume checks each rep
 
 - The frontmatter is reconstructed from the source file's data, with only the six translatable values overlaid — keys the agent invented are dropped, keys it deleted are restored, and `slug`, `icon`, `order`, and dates are source-verbatim by construction.
 - The number of code fences must match the source, the body must be non-empty, and the frontmatter must parse.
+- Every heading is pinned to its source heading's anchor id with a trailing [`[#id]` marker](/docs/content/syntax#custom-anchors), unless the translation already pins one, so `#fragment` links resolve identically in every language. Headings pair up positionally, so a translation whose heading structure doesn't match the source gets no pins.
 
 A reply that fails validation writes nothing — the item is reported as failed and the run moves on. Everything that succeeded stays stamped in the ledger, so a rerun retries only the failures.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -67,21 +67,21 @@
   },
   "dependencies": {
     "@astrojs/check": "^0.9.10",
-    "@astrojs/markdown-satteri": "^0.4.0",
-    "@astrojs/mdx": "^8.0.0",
+    "@astrojs/markdown-satteri": "^0.4.1",
+    "@astrojs/mdx": "^8.0.1",
     "@astrojs/node": "^11.1.5",
     "@astrojs/react": "^6.0.5",
     "@astrojs/vercel": "^11.0.10",
     "@asyncapi/converter": "^2.0.2",
-    "@clack/prompts": "^1.7.0",
-    "@iconify-json/lucide": "^1.2.129",
+    "@clack/prompts": "^1.8.0",
+    "@iconify-json/lucide": "^1.2.130",
     "@iconify/types": "^2.0.0",
-    "@iconify/utils": "^3.1.5",
+    "@iconify/utils": "^3.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
     "@pierre/diffs": "^1.4.1",
-    "@scalar/astro": "^0.4.17",
-    "@scalar/openapi-parser": "^0.29.0",
+    "@scalar/astro": "^0.4.18",
+    "@scalar/openapi-parser": "^0.29.1",
     "@scalar/openapi-types": "^0.9.5",
     "@shikijs/transformers": "^4.4.3",
     "@shikijs/twoslash": "^4.4.3",
@@ -89,14 +89,14 @@
     "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^7.0.93",
-    "astro": "^7.3.1",
+    "ai": "^7.0.94",
+    "astro": "^7.3.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "cross-spawn": "^7.0.6",
-    "dompurify": "^3.4.14",
+    "dompurify": "^3.4.15",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
     "fast-xml-parser": "^5.11.1",
@@ -107,9 +107,9 @@
     "image-size": "^2.0.2",
     "jiti": "^2.7.0",
     "js-yaml": "^5.4.1",
-    "katex": "^0.18.6",
+    "katex": "^0.18.7",
     "markdown-table": "^3.0.4",
-    "marked": "^18.0.11",
+    "marked": "^18.0.12",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-string": "^4.0.0",
@@ -117,7 +117,7 @@
     "mermaid": "^11.17.2",
     "micromark-extension-gfm": "^3.0.0",
     "nanotar": "^0.3.0",
-    "node-html-parser": "^9.0.3",
+    "node-html-parser": "^9.0.4",
     "openapi-sampler": "^1.7.5",
     "p-limit": "^7.3.2",
     "p-map": "^7.0.7",
@@ -134,11 +134,11 @@
     "semver": "^7.8.5",
     "sharp": "^0.35.4",
     "shiki": "^4.4.3",
-    "simple-icons": "^16.29.0",
+    "simple-icons": "^16.30.0",
     "string-width": "^8.2.2",
     "sucrase": "^3.35.1",
     "tailwindcss": "^4.3.3",
-    "takumi-js": "^2.13.6",
+    "takumi-js": "^2.13.7",
     "tinyglobby": "^0.2.17",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
@@ -148,12 +148,12 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@ai-sdk/openai-compatible": "^3.0.44",
+    "@ai-sdk/openai-compatible": "^3.0.45",
     "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@oramacloud/client": "^2.1.4",
-    "@sanity/client": "^8.5.0",
+    "@sanity/client": "^8.6.1",
     "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
     "@types/node": "^22.20.1",

package/src/ai/component-markdown.ts

@@ -64,7 +64,7 @@ export type EvaluatedValue =
   | EvaluatedValue[]
   | { [key: string]: EvaluatedValue };
 
-const isString = <Value>(value: Value): value is Value & string =>
+export const isString = <Value>(value: Value): value is Value & string =>
   typeof value === "string";
 
 const isNumber = <Value>(value: Value): value is Value & number =>
@@ -384,7 +384,7 @@ const linkText = (value: string): string =>
  * part of a balanced pair — so an href carrying either goes in the angle
  * bracket form, where only `<` and `>` are special.
  */
-const linkDestination = (href: string): string =>
+export const linkDestination = (href: string): string =>
   /[\s()<>]/u.test(href)
     ? `<${href.replaceAll(/[<>]/gu, String.raw`\$&`)}>`
     : href;
@@ -471,6 +471,21 @@ const youtube: ComponentMarkdown = ({ props }) => {
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
 
+/**
+ * `text` as an inline code span whose delimiter outlengths any backtick run
+ * inside it, padded with a space when the content starts or ends with a
+ * backtick (CommonMark strips one such pair) — so a spec path or address
+ * carrying a backtick cannot close the span early.
+ */
+export const inlineCode = (text: string): string => {
+  const runs = text.match(/`+/gu);
+  const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+  const delimiter = "`".repeat(longest + 1);
+  const padded =
+    text.startsWith("`") || text.endsWith("`") ? ` ${text} ` : text;
+  return `${delimiter}${padded}${delimiter}`;
+};
+
 /** Fence `code` so its opening/closing run outlengths any backticks inside. */
 const fencedBlock = (lang: string, code: string): string => {
   const trimmed = code.replace(/(?<!\n)\n+$/u, "");

package/src/ai/llms.ts

@@ -8,10 +8,8 @@ import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
-import {
-  downlevelComponents,
-  exampleComponentSerializers,
-} from "./component-markdown.ts";
+import { downlevelComponents } from "./component-markdown.ts";
+import { projectComponentSerializers } from "./serializers.ts";
 import { AGENT_SKILLS_DIR, AGENT_SKILLS_INDEX_PATH } from "./skills.ts";
 import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
@@ -292,12 +290,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
   const pages = eligiblePages(project, { versions: "current" }).toSorted(
     (a, b) => a.route.localeCompare(b.route)
   );
-  // Downlevel `<Component>` to its example's source; a same-name user
-  // `markdownComponents` entry is spread last and still wins.
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...config.ai.markdownComponents,
-  };
+  const components = projectComponentSerializers(project);
 
   const sections = await Promise.all(
     pages.map(async (page) => {

package/src/ai/markdown.ts

@@ -5,11 +5,9 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
-import {
-  downlevelComponents,
-  exampleComponentSerializers,
-} from "./component-markdown.ts";
+import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
+import { projectComponentSerializers } from "./serializers.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -55,12 +53,7 @@ export const buildRawMarkdown = async (
 ): Promise<Record<string, RawMarkdownEntry>> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
-  // Downlevel `<Component>` to its example's source. A user `markdownComponents`
-  // entry of the same name is spread last, so it still wins.
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...project.config.ai.markdownComponents,
-  };
+  const components = projectComponentSerializers(project);
 
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);