blume 2.2.2 → 2.2.3

package/docs/content/frontmatter.mdx

@@ -23,7 +23,7 @@ Frontmatter is YAML, so quote a value that holds a colon followed by a space, li
     authors: {
       type: "string | string[] | object[]",
       description:
-        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Preserved as-is.",
+        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Credited as Person nodes in the page's JSON-LD; other fields are preserved as-is.",
     },
     slug: {
       type: "string",

package/docs/content/i18n.mdx

@@ -186,7 +186,7 @@ i18n: {
 Localized SEO is handled for you — no per-page metadata to write:
 
 - `<html lang>` and `dir` are set from the active locale.
-- `hreflang` alternates link every real translation of a page, plus an `x-default` pointing at the default locale.
+- `hreflang` alternates link every real translation of a page that search engines may index (a `noindex`, hidden, or canonical-elsewhere translation is left out), plus an `x-default` pointing at the default locale.
 - Canonical URLs are locale-correct, and JSON-LD carries `inLanguage`.
 
 Set [`deployment.site`](/docs/deployment) so these can be emitted as absolute URLs.

package/docs/content/sources/remote-mdx.mdx

@@ -35,7 +35,7 @@ mdxRemote({
 
 `include` (default `["**/*.{md,mdx}"]`) filters the files by their path under `path`, the way a `filesystem()` source's `include` does: a pattern starting with `!` excludes what it matches (`["**/*.mdx", "!drafts/**"]`). With `github`, the source lists the repository's whole tree at `ref` and keeps the files under `path`. If nothing is under `path` at that ref, the source reads no pages and warns with `BLUME_SOURCE_PATH_MISSING`. GitHub caps the listing (100,000 entries or 7 MB for the whole repository, whatever `path` is), and past it the source warns with `BLUME_SOURCE_TRUNCATED`: list the files with `url` and `files` instead.
 
-A relative link between remote files (`[Errors](./02-errors.mdx)`) lands on the page the linked file publishes at, with its ordering prefix dropped from the route, and `blume validate` checks it the same way.
+A relative link between remote files (`[Errors](./02-errors.mdx)`) lands on the page the linked file publishes at, with its ordering prefix dropped from the route. It does on the rendered page, in the page's [Markdown copy](/docs/discoverability/markdown#raw-markdown) and `llms-full.txt`, and in what the assistant reads, and `blume validate` checks it the same way.
 
 A private repo's token is read from the `GITHUB_TOKEN` environment variable. It is never inlined into your config or generated output, and it is only ever sent to GitHub's own hosts (`api.github.com`, `raw.githubusercontent.com`), never to a custom `url` base. A public repo works without it. With `github`, the adapter declares the variable, so `blume dev` and `blume build` warn `BLUME_MISSING_SECRET` when it's unset: the file listing goes through GitHub's API, which allows 60 unauthenticated requests an hour. A raw `url` reads files only, so nothing warns up front; when GitHub refuses a file with a 401, 403, or 404 while `GITHUB_TOKEN` is unset, the warning for the skipped file says the variable isn't set.
 

package/docs/discoverability/open-graph.mdx

@@ -3,7 +3,7 @@ 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:
+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 or when a [default image](#default-image) replaces the cards. Set `enabled` to override that either way:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -11,6 +11,21 @@ seo: {
 }
 ```
 
+## Default image
+
+Set `seo.og.image` to share one image across every page instead of a generated card, or give each locale its own:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    image: { en: "/og/default-en.png", fr: "/og/default-fr.png" },
+    // Or image: "https://example.com/og/default.png"
+  },
+}
+```
+
+A page's `seo.image`, or a custom page's `ogImage` prop, wins over the default. A locale missing from the map takes the default locale's image. The default covers custom pages rendered with `PageLayout` and the generated changelog index too, so Blume stops generating cards once it's set, unless `enabled` is `true`. Root-relative paths resolve under the deployment base. Blume declares image dimensions only for generated cards. Whichever image a page ends up with also goes into its [JSON-LD](/docs/discoverability/structured-data) as the page's `image`.
+
 ## 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.

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

@@ -15,6 +15,18 @@ seo: {
 }
 ```
 
+### Locale alternates
+
+Opt into alternate links on a multilingual site's sitemap:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  sitemap: { alternates: true },
+}
+```
+
+Each translated page lists its translations, itself included, as `xhtml:link` elements, plus an `x-default` link when the default locale has the page. These are the same `hreflang` links the page head carries: a `noindex`, hidden, or canonical-elsewhere translation is in neither. A page in fewer than two listed locales gets no alternate links. URLs include the deployment base. `sitemap: true` and `sitemap: {}` keep alternates off; `sitemap: false` turns the sitemap off.
+
 Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file you place in `public/`.
 
 ## Robots

package/docs/discoverability/structured-data.mdx

@@ -48,6 +48,50 @@ seo: {
 
 `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`.
 
+## Shared entity identifiers
+
+When docs live inside another site (`example.com/docs`), point at the entities that site already defines instead of defining them again:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  jsonLd: {
+    websiteId: "https://example.com/#website",
+    organizationId: "https://example.com/#organization",
+  },
+}
+```
+
+Every page names `websiteId` as its `isPartOf`, and Blume stops emitting its own WebSite node, whose name and URL would describe the docs instead of the site. Set `website: true` to emit it anyway under that id, or `website: false` to omit the docs' own WebSite node without sharing an id. `organizationId` becomes every page's publisher. With [`seo.organization`](#site-identity) also set, the Organization node uses that id and carries only the fields you configure: the docs' title and URL don't stand in for its name and URL. By default, Blume emits the WebSite node and uses the site URL plus `#website` and `#organization`. Identifiers must be absolute URLs, so they work without a site URL too.
+
+## Page author and publisher
+
+Reference existing entities on every page:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  jsonLd: {
+    author: { "@id": "https://example.com/#author" },
+    publisher: { "@id": "https://example.com/#publisher" },
+  },
+}
+```
+
+These references apply to the WebPage or article node, and `publisher` replaces the organization as its publisher. Blume doesn't define the entities they point at. A page's own [`authors`](/docs/content/frontmatter) front matter wins over `author`: each one is credited as a `Person`.
+
+## Publication date from Git
+
+Date pages by the commit that added their content file:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  datePublished: "git",
+}
+```
+
+Front matter `date` or `changelog.date` still wins. Git dates the rest, through the same `git log` as [`lastModified`](/docs/configuration#last-modified). Renames are followed only when the content is unchanged, so a new page never inherits the history of a similar one deleted in the same commit. Pages from non-filesystem sources and uncommitted files get no date from git. A shallow clone dates no page and warns instead, since its oldest commit is where the clone was cut. Fetch full history in CI (`VERCEL_DEEP_CLONE=true` on Vercel, `fetch-depth: 0` for `actions/checkout`).
+
+The resolved [Open Graph image](/docs/discoverability/open-graph) is also included as the page node's `image`, whether it comes from frontmatter, a site default, or a generated card.
+
 ## Custom pages
 
 A custom [`.astro` page](/docs/advanced/custom-pages) rendered through `PageLayout` emits the same graph, so a marketing home page isn't the one URL without structured data. A custom page has no content file to date, so pass `lastModified` to give it a `dateModified`. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with this setting, or `structuredDataEnabled={false}` to turn it off for that page alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",

package/src/ai/ask-context.ts

@@ -1,8 +1,14 @@
 import { normalizeRoute } from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
+import {
+  accentInsensitive,
+  foldLatinTerm,
+  stripSoftHyphens,
+} from "../search/fold.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
+import { linkText } from "./link-text.ts";
 
 /** A chat message as posted by the assistant island (`{ role, content }`). */
 export interface AskMessage {
@@ -47,7 +53,7 @@ const EXCERPT_CHARS = 2000;
 const CONTEXT_BUDGET = 10_000;
 /**
  * Smallest excerpt worth injecting. A long page pushed under a tiny residual
- * budget would get a full `## Title (/route)` heading over a fragment of a few
+ * budget would get a full `## [Title](/route)` heading over a fragment of a few
  * dozen characters — a section the model is invited to cite but that grounds
  * nothing. Short pages that fit whole are still injected below this floor.
  */
@@ -196,7 +202,7 @@ const hasSegmenter = (
 ): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
 
 const segmentQuery = (query: string): string[] => {
-  const lowered = query.normalize("NFC").toLowerCase();
+  const lowered = stripSoftHyphens(query).normalize("NFC").toLowerCase();
   if (!hasSegmenter(Intl.Segmenter)) {
     return lowered.match(TERM) ?? [];
   }
@@ -210,9 +216,15 @@ const segmentQuery = (query: string): string[] => {
   return pieces;
 };
 
-/** Lowercase word tokens of `text`, cut at the same boundaries as a query. */
+/**
+ * Lowercase word tokens of `text`, cut at the same boundaries as a query.
+ * Latin words fold the way the search index folds them, so the section a page
+ * was retrieved for (Prüfung, for the question `prufung`) is the one excerpted.
+ */
 const tokenize = (text: string): string[] =>
-  segmentQuery(text).flatMap((piece) => piece.match(TERM) ?? []);
+  segmentQuery(text).flatMap((piece) =>
+    (piece.match(TERM) ?? []).map((term) => foldLatinTerm(term))
+  );
 
 /** Distinct, meaningful lowercase terms from a query (drops stopwords). */
 const queryTerms = (query: string): string[] =>
@@ -222,11 +234,35 @@ const queryTerms = (query: string): string[] =>
 
 /**
  * The grounding preamble. The model is told to answer strictly from the injected
- * excerpts and to cite the pages it used as Markdown links (each excerpt is
- * headed by `## Title (/route)`), so citations render as real links in the panel.
+ * excerpts and to cite the pages it used as Markdown links, so citations render
+ * as real links in the panel. Each excerpt is headed by the very link to cite
+ * (`## [Title](/route)`), so a model that copies the heading copies a link.
  */
 const BASE_INSTRUCTION =
-  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt is headed by its page as `## Page Title (/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from, and write every citation as a Markdown link to that page using its route, e.g. [Page Title](/route).";
+  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt opens with a heading that links to its page, `## [Page Title](/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from with the link in the heading that opens their excerpt, written exactly as it is there: [Page Title](/route).";
+
+/** `encodeURIComponent` leaves parentheses as they are, so they're mapped here. */
+const PARENTHESES = new Map([
+  ["(", "%28"],
+  [")", "%29"],
+]);
+
+/**
+ * An excerpt's heading: the Markdown link the model cites the page with. A
+ * bracket or backslash in the title, or whitespace or a parenthesis in the
+ * route, would break the link, and a `%` in the route would read back as an
+ * escape (`read_page` decodes them), so those are escaped; the rest of the
+ * route stays as the reader sees it (`/ja/ポイント`).
+ */
+export const excerptHeading = (
+  doc: Pick<OramaDoc, "route" | "title">
+): string => {
+  const target = doc.route.replaceAll(
+    /[%\s()]/gu,
+    (char) => PARENTHESES.get(char) ?? encodeURIComponent(char)
+  );
+  return `## [${linkText(doc.title)}](${target})`;
+};
 
 /**
  * Appended when the endpoint gives the model the docs tools (see
@@ -272,7 +308,7 @@ const isFollowUp = (message: string): boolean => {
 /**
  * The texts that retrieve for the latest question, in rank order.
  *
- * The question itself always leads, verbatim: Orama's own tokenizer and BM25
+ * The question itself always leads, verbatim: the index's tokenizer and BM25
  * weighting see the whole sentence (version numbers, single-character CJK
  * words, `--flags`, and the bigrams a ja/zh index depends on all survive), and
  * a short question that names its subject ("Does it support i18n?") is never
@@ -350,13 +386,15 @@ export const relevantExcerpt = (
     return `${prefix}${slice}${suffix}`;
   };
 
-  // Case-insensitive matching via regex rather than `indexOf` on a lowercased
-  // copy: length-changing case mappings (Turkish İ → "i" + U+0307) would shift
-  // every index in the copy, sliding the excerpt window off the match. Terms
-  // come from TERM (letters, marks and digits only), so no regex escaping.
+  // Case- and accent-insensitive matching via regex rather than `indexOf` on
+  // a folded copy: length-changing mappings (Turkish İ → "i" + U+0307, ß →
+  // "ss") would shift every index in the copy, sliding the excerpt window off
+  // the match.
   const positions: number[] = [];
   for (const term of queryTerms(query)) {
-    for (const match of trimmed.matchAll(new RegExp(term, "giu"))) {
+    for (const match of trimmed.matchAll(
+      new RegExp(accentInsensitive(term), "giu")
+    )) {
       positions.push(match.index);
     }
   }
@@ -770,7 +808,7 @@ export const createAskContext = (
         Math.min(excerptChars, budget)
       );
       budget -= body.length;
-      sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);
+      sections.push(`${excerptHeading(doc)}${label}\n${body}`);
     };
 
     if (current) {

package/src/ai/ask-data.ts

@@ -14,7 +14,10 @@ import type { AskData } from "./ask-context.ts";
  * from the docs instead of declining.
  * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
  * (web-only content removed, agents-only unwrapped) and components downlevel to
- * Markdown, both matching llms-full.txt.
+ * Markdown, both matching llms-full.txt. Its page links point at the pages
+ * they mean, as there, but as the routes this snapshot keys those pages by:
+ * without the `deployment.base`, like the excerpt headings, since the chat
+ * panel mounts every link it renders under the base.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {

package/src/ai/ask-tools.ts

@@ -3,7 +3,12 @@ import { jsonSchema, tool } from "ai";
 import { normalizeRoute } from "../core/base-path.ts";
 import { queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
-import { askIndex, readerScope, sectionExcerpt } from "./ask-context.ts";
+import {
+  askIndex,
+  excerptHeading,
+  readerScope,
+  sectionExcerpt,
+} from "./ask-context.ts";
 import type { AskData, AskPage, ReaderScope } from "./ask-context.ts";
 
 /**
@@ -37,7 +42,7 @@ const PAGE_CHARS = 20_000;
 
 /** A result block, headed the way the injected excerpts are, for citing. */
 const block = (doc: OramaDoc, body: string): string =>
-  `## ${doc.title} (${doc.route})\n${body}`;
+  `${excerptHeading(doc)}\n${body}`;
 
 /**
  * Search the docs for `query` within the reader's scope: the most relevant
@@ -66,7 +71,9 @@ export const searchDocs = async (
 
 /**
  * The route a model asked for, as the snapshot keys it: a full URL on the
- * site becomes its path, and a query string or fragment is dropped.
+ * site becomes its path, a query string or fragment is dropped, and
+ * percent-escapes are decoded (a cited route escapes whitespace,
+ * parentheses, and `%`; see `excerptHeading`).
  */
 const routeOf = (data: AskData, requested: string): string => {
   let path = requested.trim();
@@ -74,6 +81,11 @@ const routeOf = (data: AskData, requested: string): string => {
     path = path.slice(data.site.replace(/\/$/u, "").length) || "/";
   }
   path = path.replace(/[?#].*$/u, "");
+  try {
+    path = decodeURI(path);
+  } catch {
+    // Malformed percent sequence — look it up as written.
+  }
   return normalizeRoute(path.startsWith("/") ? path : `/${path}`);
 };
 
@@ -106,7 +118,7 @@ export const createAskTools = (data: AskData) => {
     return {
       read_page: tool({
         description:
-          "Read one documentation page in full, by its route (the path in parentheses after a page title, such as /docs/getting-started).",
+          "Read one documentation page in full, by its route (the link target in the heading that opens a page's excerpt, such as /docs/getting-started).",
         execute: ({ route }) => Promise.resolve(readPage(data, byRoute, route)),
         inputSchema: jsonSchema<{ route: string }>({
           additionalProperties: false,
@@ -122,7 +134,7 @@ export const createAskTools = (data: AskData) => {
       }),
       search_docs: tool({
         description:
-          "Search this project's documentation. Returns the most relevant excerpt of each matching page, headed by its title and route.",
+          "Search this project's documentation. Returns the most relevant excerpt of each matching page, headed by a Markdown link to the page.",
         execute: ({ query }) => searchDocs(data, scope, query),
         inputSchema: jsonSchema<{ query: string }>({
           additionalProperties: false,

package/src/ai/link-text.ts

@@ -0,0 +1,6 @@
+/**
+ * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
+ * — closes or nests the text early, and the line stops being a link.
+ */
+export const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);

package/src/ai/llms.ts

@@ -13,6 +13,7 @@ import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
 import { downlevelComponents } from "./component-markdown.ts";
+import { linkText } from "./link-text.ts";
 import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
 import {
@@ -33,13 +34,6 @@ const pageUrl = (route: string, site?: string, base = ""): string => {
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
-/**
- * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
- * — closes or nests the text early, and the line stops being a link.
- */
-const linkText = (title: string): string =>
-  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
-
 /** Inputs only the build has: the published skills, collected once per build. */
 export interface LlmsIndexOptions {
   /**

package/src/ai/markdown.ts

@@ -7,7 +7,7 @@ import { discoverPages, discoverPagesSync } from "../core/custom-pages.ts";
 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 type { PageRecord, RouteManifestEntry } from "../core/types.ts";
 import { advertisedConfig, servesMcp } from "./agent-surface.ts";
 import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
@@ -64,8 +64,10 @@ export const buildRawMarkdown = async (
   const components = projectComponentSerializers(project);
   const rewriteLinks = relativeLinkRewriter(project);
 
-  const readRoute = async (route: RouteManifestEntry): Promise<string> => {
-    const page = pageById.get(route.id);
+  const readRoute = async (
+    route: RouteManifestEntry,
+    page: PageRecord | undefined
+  ): Promise<string> => {
     if (page) {
       return await readExpandedEntryText(project, page);
     }
@@ -74,7 +76,8 @@ export const buildRawMarkdown = async (
 
   const entries = await Promise.all(
     project.manifest.routes.map(async (route) => {
-      let text = await readRoute(route);
+      const page = pageById.get(route.id);
+      let text = await readRoute(route, page);
       if (route.sourcePath) {
         text = rewriteRelativeAssets({
           deployBase: project.config.deployment.options.base,
@@ -87,6 +90,7 @@ export const buildRawMarkdown = async (
       // agent fetched resolves it to, and `/install` gains the base and the
       // page's locale the rendered link has — remote content included.
       text = rewriteLinks(text, {
+        entryId: page?.entryId,
         route: route.path,
         sourcePath: route.sourcePath,
       });