blume 2.1.3 → 2.2.1

package/src/core/config-input.ts

@@ -22,6 +22,8 @@ import type { FontSlug } from "../theme/fonts.ts";
 import type { FooterSocial } from "./footer.ts";
 import type {
   blumeConfigSchema,
+  McpClient,
+  McpCustomClient,
   OpenInChatProvider,
   SidebarDisplay,
   SidebarItemConfig,
@@ -147,9 +149,15 @@ export interface FooterLink {
 
 /**
  * The site footer, below the content on every page: a row of links on one
- * side, and social profile icons on the other.
+ * side, social profile icons on the other, and a copyright line centered
+ * between them.
  */
 export interface FooterConfig {
+  /**
+   * A line of plain text centered between the links and the icons, like
+   * `© 2026 Acme, Inc.`, or a map of locale code to text.
+   */
+  copyright?: LocalizableLabel;
   /** Links in one row, left to right. */
   links?: FooterLink[];
   /**
@@ -181,7 +189,7 @@ export interface ChangelogConfig {
 export interface ContentConfig {
   /** Default page `type` for content that sets none. Defaults to `doc`. */
   defaultType?: string;
-  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. Shorthand; not allowed beside `sources`. */
+  /** Glob patterns to ignore, on top of `["**\/_*", "**\/.*"]`; a `!pattern` entry stops ignoring that pattern, a default included. Shorthand; not allowed beside `sources`. */
   exclude?: string[];
   /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. Shorthand; not allowed beside `sources`. */
   include?: string[];
@@ -719,6 +727,32 @@ export interface LlmsTxtConfig {
 
 /** Expose the docs as an MCP server for connecting agents. */
 export interface McpConfig {
+  /**
+   * The clients the "Connect to MCP" page action installs the server into,
+   * beside its "Copy server URL" row. Defaults to `true` (every built-in
+   * client). Set `false` to list none, or list built-in keys and your own
+   * clients, in order. A custom client's `command` is copied with `{name}`
+   * (the server name as an id) and `{url}` (the server's URL) filled in; its
+   * `label` localizes like a header link's, and `icon` defaults to `terminal`.
+   *
+   * ```ts
+   * agents: {
+   *   mcp: {
+   *     enabled: true,
+   *     clients: [
+   *       "claude-code",
+   *       {
+   *         label: "Copy Copilot CLI command",
+   *         command: "copilot mcp add --transport http {name} {url}",
+   *         icon: "terminal",
+   *       },
+   *       "vscode",
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  clients?: boolean | (McpClient | McpCustomClient)[];
   /** Turn the MCP server on. Defaults to `false`. */
   enabled?: boolean;
   /** Optional system hint passed to connecting agents. */
@@ -1567,8 +1601,8 @@ export interface BlumeConfig {
    */
   feedback?: boolean | FeedbackConfig;
   /**
-   * The site footer: social profile icons and up to four link columns. Unset,
-   * the site has no footer.
+   * The site footer: a copyright line, a row of links, and social profile
+   * icons. Unset, the site has no footer.
    */
   footer?: FooterConfig;
   /** Opt-in custom frontmatter keys, validated by schemas you supply. */
@@ -1597,7 +1631,7 @@ export interface BlumeConfig {
    * Limit how often one reader (by IP address) can call the server routes —
    * the assistant, the API playground proxy, server-side search — with an
    * adapter from `blume/ratelimit`: `memory()` (the default, 30 requests per
-   * 10 minutes), `upstash()`, or `cloudflare()`. `false` turns it off.
+   * 10 minutes), `upstash()`, `cloudflare()`, or `unkey()`. `false` turns it off.
    */
   rateLimit?: false | RateLimitAdapter;
   /** React island behavior (compiler auto-memoization). */

package/src/core/config.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename } from "pathe";
 import { z } from "zod";
 
+import { ACCENTS, invalidColorSettings } from "../theme/palette.ts";
 import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import {
@@ -261,6 +262,50 @@ const configIssues = (
     );
 };
 
+const COLOR_FORMS =
+  "a hex value like #6340ac, rgb(), hsl(), oklch(), or a color name like rebeccapurple";
+
+/**
+ * A warning for each configured color that isn't a CSS color, at the line
+ * that sets it. The schema has always taken any string, so this warns rather
+ * than failing a build that used to pass.
+ */
+const colorDiagnostics = (
+  config: ResolvedConfig,
+  configFile: string | null
+): Diagnostic[] => {
+  const invalid = invalidColorSettings(config);
+  if (invalid.length === 0) {
+    return [];
+  }
+  const source =
+    configFile && existsSync(configFile)
+      ? readFileSync(configFile, "utf-8")
+      : undefined;
+  const located = diagnosticsFromIssues(
+    invalid.map((setting) => ({
+      message: `${JSON.stringify(setting.value)} isn't a CSS color, so ${
+        setting.path[0] === "seo"
+          ? "the social card renderer rejects it"
+          : "browsers ignore the styles that use it"
+      }.`,
+      path: setting.path,
+    })),
+    {
+      code: "BLUME_THEME_COLOR_INVALID",
+      file: configFile ?? undefined,
+      source,
+    }
+  );
+  return located.map((diagnostic, index) => ({
+    ...diagnostic,
+    severity: "warning",
+    suggestion: invalid[index]?.presets
+      ? `Use a preset (${Object.keys(ACCENTS).join(", ")}) or a CSS color: ${COLOR_FORMS}.`
+      : `Use a CSS color: ${COLOR_FORMS}.`,
+  }));
+};
+
 /**
  * Load and validate the project config. When no config file exists, schema
  * defaults produce a fully resolved config so the zero-boilerplate path works.
@@ -364,7 +409,7 @@ export const loadConfig = async (
       seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
     },
     configFile,
-    diagnostics: [],
+    diagnostics: colorDiagnostics(config, configFile),
     themeFontsConfigured,
   };
 };

package/src/core/content-assets.ts

@@ -1,20 +1,19 @@
-import { readdirSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import {
-  basename,
-  dirname,
-  extname,
-  normalize,
-  relative,
-  resolve,
-} from "pathe";
+import { dirname, extname, relative } from "pathe";
 
 import { normalizeBasePath } from "./base-path.ts";
 import { nextFenceState } from "./code-fences.ts";
 import type { FenceState } from "./code-fences.ts";
+import { resolveRelativeFile, resolveRelativeImage } from "./relative-files.ts";
 import { hashText } from "./sources/cache.ts";
-import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
+import {
+  isLinkElementUrl,
+  rewriteCardImages,
+  rewriteElementUrls,
+  rewriteImageTargets,
+  rewriteLinkTargets,
+} from "./sources/normalize.ts";
 import { readExpandedEntryText } from "./sources/read.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { PageRecord } from "./types.ts";
@@ -29,31 +28,18 @@ import type { PageRecord } from "./types.ts";
  * `/blume-assets/content/<project-relative path>` by a generated endpoint (see
  * `contentAssetsEndpointTemplate`), and these helpers rewrite the relative
  * references in agent-facing output to that URL.
+ *
+ * Other files beside a page are published the same way: a link to one
+ * (`[spec](./spec.pdf)`, a reference definition), a raw HTML or `.mdx`
+ * element's `src` (`<img src="./diagram.png">`, `<video>`, `<source>`,
+ * `<audio>`), and an `<a>`'s or a component's `href`. Nothing else serves
+ * them, so the HTML render points those at the same URLs (see
+ * `markdown/content-assets.ts`).
  */
 
-/** The endpoint route prefix colocated content images are served under. */
+/** The endpoint route prefix colocated content files are served under. */
 export const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
 
-// The formats Astro's image pipeline accepts, plus the web-safe pass-throughs;
-// anything else referenced relatively (a `.pdf`, a source file) is left alone.
-const IMAGE_EXTENSIONS = new Set([
-  ".apng",
-  ".avif",
-  ".bmp",
-  ".gif",
-  ".ico",
-  ".jpeg",
-  ".jpg",
-  ".png",
-  ".svg",
-  ".tiff",
-  ".webp",
-]);
-
-/** Whether a link target is a relative filesystem path (not URL/absolute/hash). */
-const isRelativeTarget = (target: string): boolean =>
-  !(target.startsWith("/") || target.startsWith("#")) && !URL.canParse(target);
-
 /**
  * The endpoint param a colocated image is served under: its project-relative
  * path (readable, collision-free — it mirrors the source tree). A file outside
@@ -71,118 +57,35 @@ export const contentAssetParam = (
   return rel;
 };
 
-/** Percent-decode an image target; malformed escapes stay verbatim. */
-const decodeTarget = (target: string): string => {
-  try {
-    return decodeURI(target);
-  } catch {
-    return target;
-  }
-};
-
-/**
- * Whether a target is *shaped* like a colocated image reference: a relative
- * filesystem path with an image extension. Exported so link validation can
- * tell "not a colocated candidate" apart from "a candidate that resolves
- * nowhere" — the former falls through to the public-dir probe, the latter is
- * a broken reference beside the page source.
- */
-export const isRelativeImageTarget = (target: string): boolean =>
-  isRelativeTarget(target) &&
-  IMAGE_EXTENSIONS.has(extname(decodeTarget(target)).toLowerCase());
-
-/**
- * Whether `abs` is a file whose trailing `segments` names match the on-disk
- * entries exactly. A bare `existsSync` accepts `./Diagram.PNG` for
- * `diagram.png` (or a directory named like an image) on a case-insensitive
- * filesystem — the reference then validates and serves locally but breaks on
- * the case-sensitive Linux build.
- */
-const existsAsWritten = (abs: string, segments: number): boolean => {
-  let current = abs;
-  for (let i = 0; i < segments; i += 1) {
-    const parent = dirname(current);
-    let entries: string[];
-    try {
-      entries = readdirSync(parent);
-    } catch {
-      return false;
-    }
-    if (!entries.includes(basename(current))) {
-      return false;
-    }
-    current = parent;
-  }
-  const stat = statSync(abs, { throwIfNoEntry: false });
-  return stat !== undefined && stat.isFile();
-};
-
 /**
- * Resolve one image target against its page's directory. Returns the absolute
- * file path when the target is relative, is an image, and exists on disk —
- * anything else (remote URLs, `public/` absolutes, broken refs, code-block
- * examples that happen to look like paths) is null and left untouched. Shared
- * with link validation, so what counts as a colocated image is decided once.
+ * The URL a colocated image's endpoint param is served at, under
+ * `deployment.base` when set, encoded for a Markdown or HTML URL with its `/`
+ * separators kept.
  */
-export const resolveRelativeImage = (
-  sourceDir: string,
-  target: string
-): string | null => {
-  if (!isRelativeImageTarget(target)) {
-    return null;
-  }
-  const decoded = decodeTarget(target);
-  // Only the segments the author wrote are checked against on-disk names;
-  // `sourceDir`'s own casing is the filesystem's business, not the target's.
-  const segments = normalize(decoded)
+export const contentAssetUrl = (param: string, deployBase?: string): string =>
+  `${normalizeBasePath(deployBase)}${CONTENT_ASSETS_PREFIX}/${param
     .split("/")
-    .filter((part) => part !== "" && part !== "..").length;
-  const abs = resolve(sourceDir, decoded);
-  return existsAsWritten(abs, segments) ? abs : null;
-};
-
-/** Encode an endpoint param for use in a Markdown URL, keeping `/` separators. */
-const encodedParam = (param: string): string =>
-  param.split("/").map(encodeURIComponent).join("/");
+    .map(encodeURIComponent)
+    .join("/")}`;
+
+// Where a link (`[spec](./spec.pdf)`, `[spec]: ./spec.pdf`) or an element's
+// `href`/`src` could name a file beside the page: a destination or value not
+// written as a root path or a fragment, which `resolveRelativeFile` never
+// resolves. They're read in the text as it stands, code included, so a page
+// without one, like a page that links only to routes and anchors, has
+// nothing to rewrite and skips the passes that mask its code to look.
+const RELATIVE_DESTINATION = /\][(:][ \t]*(?![/#\s])/u;
+const RELATIVE_ELEMENT_URL = /(?:href|src)=["'](?![/#])/u;
 
 /**
- * Rewrite one line's relative image targets. Matches run on a copy with inline
- * code blanked out (a `` `![x](./y.png)` `` span is syntax being *shown*, not
- * an image), while replacements splice into the real line by index — the mask
- * preserves length, so the indices line up.
- */
-const rewriteLine = (
-  line: string,
-  toUrl: (target: string) => string | null
-): string => {
-  const masked = line.replaceAll(INLINE_CODE, (span) =>
-    " ".repeat(span.length)
-  );
-  let out = "";
-  let cursor = 0;
-  for (const match of masked.matchAll(MD_IMAGE)) {
-    const target = match.groups?.target ?? "";
-    const url = toUrl(target);
-    if (url === null) {
-      continue;
-    }
-    const offset =
-      (match.index ?? 0) +
-      targetOffsetIn(match[0], target, match.groups?.title);
-    out += line.slice(cursor, offset) + url;
-    cursor = offset + target.length;
-  }
-  return out + line.slice(cursor);
-};
-
-/**
- * Rewrite a page's relative image references to their served
+ * Rewrite a page's relative image references, and its links and element
+ * URLs naming other files beside it, to their served
  * `/blume-assets/content/…` URLs (under `deployment.base` when set). Fenced
  * code blocks and inline code are skipped; only references whose file actually
  * exists next to the source are touched. `register` observes each rewritten
  * asset so a caller can accumulate the files the endpoint must serve.
  */
-export const rewriteRelativeImages = (options: {
+export const rewriteRelativeAssets = (options: {
   source: string;
   sourcePath: string;
   projectRoot: string;
@@ -191,15 +94,18 @@ export const rewriteRelativeImages = (options: {
 }): string => {
   const { source, sourcePath, projectRoot, deployBase, register } = options;
   const sourceDir = dirname(sourcePath);
-  const prefix = `${normalizeBasePath(deployBase)}${CONTENT_ASSETS_PREFIX}`;
-  const toUrl = (target: string): string | null => {
-    const abs = resolveRelativeImage(sourceDir, target);
-    if (abs === null) {
-      return null;
-    }
+  const served = (abs: string): string => {
     const param = contentAssetParam(projectRoot, abs);
     register?.(param, abs);
-    return `${prefix}/${encodedParam(param)}`;
+    return contentAssetUrl(param, deployBase);
+  };
+  const toUrl = (target: string): string | null => {
+    const abs = resolveRelativeImage(sourceDir, target);
+    return abs === null ? null : served(abs);
+  };
+  const toFileUrl = (target: string): string | null => {
+    const file = resolveRelativeFile(sourceDir, target);
+    return file === null ? null : `${served(file.path)}${file.suffix}`;
   };
 
   let fence: FenceState = null;
@@ -207,13 +113,27 @@ export const rewriteRelativeImages = (options: {
     const next = nextFenceState(line, fence);
     const inFence = fence !== null || next !== null;
     fence = next;
-    return inFence ? line : rewriteLine(line, toUrl);
+    // Inline code is skipped too: a `` `![x](./y.png)` `` span is syntax
+    // being shown, not an image.
+    return inFence ? line : rewriteImageTargets(line, toUrl);
   });
-  return lines.join("\n");
+  // A `<Card img>` is an image embed too: its file is served and its value
+  // pointed there, which the HTML render reads back (see
+  // `markdown/content-assets.ts`), as are links and element URLs naming any
+  // other file beside the page.
+  const withCards = rewriteCardImages(lines.join("\n"), toUrl);
+  const withLinks = RELATIVE_DESTINATION.test(withCards)
+    ? rewriteLinkTargets(withCards, toFileUrl)
+    : withCards;
+  return RELATIVE_ELEMENT_URL.test(withLinks)
+    ? rewriteElementUrls(withLinks, (url) =>
+        isLinkElementUrl(url) ? toFileUrl(url.value) : null
+      )
+    : withLinks;
 };
 
 /**
- * Every colocated image the project's pages reference, keyed by endpoint param.
+ * Every colocated file the project's pages reference, keyed by endpoint param.
  * Serialized to `generated/content-assets.json`, which the
  * `/blume-assets/[...asset]` endpoint reads to serve the original files. Runs
  * the same rewrite the agent-Markdown builders apply — over the same
@@ -243,7 +163,7 @@ export const collectContentAssets = async (project: {
       } catch {
         return;
       }
-      rewriteRelativeImages({
+      rewriteRelativeAssets({
         projectRoot: project.context.root,
         register: (param, abs) => {
           files[param] = abs;

package/src/core/data.ts

@@ -187,7 +187,7 @@ export interface BlumeDataConfig {
   feedback: boolean;
   /** Whether the rating asks for a written comment after it (`feedback.comments`). */
   feedbackComments: boolean;
-  /** `footer`: social profile icons and link columns, or `null` when unset. */
+  /** `footer`: the copyright line, links, and social profile icons, or `null` when unset. */
   footer: ResolvedConfig["footer"] | null;
   /**
    * Repo coordinates for content components that address the API or build
@@ -206,8 +206,15 @@ export interface BlumeDataConfig {
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;
-  /** Hosted MCP server, or `null` when MCP is off. */
-  mcp: { name: string; route: string } | null;
+  /**
+   * Hosted MCP server, or `null` when MCP is off, with the clients its
+   * "Connect to MCP" page action lists (`agents.mcp.clients`), in order.
+   */
+  mcp: {
+    clients: ResolvedConfig["agents"]["mcp"]["clients"];
+    name: string;
+    route: string;
+  } | null;
   /** `seo.metatags`: the site's own tags for every page's head, or `null`. */
   metatags: Record<string, string> | null;
   /**

package/src/core/diagnostics.ts

@@ -27,40 +27,65 @@ const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_SOURCES_OBSIDIAN = "/docs/content/sources/obsidian";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
 const DOCS_CONTENT_INCLUDES = "/docs/content/includes";
+const DOCS_OPENAPI_WARNINGS = "/docs/references/openapi#spec-warnings";
+const DOCS_OTHER_TOOLS_SYNTAX = "/docs/content/syntax#syntax-from-other-tools";
+const DOCS_MARKDOWN_AND_MDX = "/docs/content#markdown-and-mdx";
 
 /** Diagnostic code → the docs page that explains it. */
 const DOCS_PATHS = new Map(
   Object.entries({
     BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
-    BLUME_ASSETS_UNCHECKED: DOCS_CLI_VALIDATE,
     BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
     BLUME_BROKEN_ANCHOR: DOCS_CLI_VALIDATE,
     BLUME_BROKEN_ASSET: DOCS_CLI_VALIDATE,
     BLUME_BROKEN_LINK: DOCS_CLI_VALIDATE,
+    BLUME_BROKEN_REDIRECT: DOCS_CLI_VALIDATE,
+    BLUME_CODE_FENCE_OPTION: "/docs/content/syntax",
     BLUME_COMPONENTS_INVALID: "/docs/configuration/customization",
     BLUME_CONFIG_INVALID: "/docs/configuration",
     BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
     BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
     BLUME_DEAD_LINK: DOCS_CLI_VALIDATE,
     BLUME_DEPENDENCY_MISSING: "/docs/cli/doctor",
+    BLUME_DIRECTIVE_CLOSING_TEXT: "/docs/content/syntax",
+    BLUME_DIRECTIVE_OPENING_TEXT: "/docs/content/syntax",
+    BLUME_DIRECTIVE_SPACED_NAME: "/docs/content/syntax",
     BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
     BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
     BLUME_EXAMPLE_NOT_FOUND: "/docs/content/components#component",
     BLUME_FRONTMATTER_INVALID: "/docs/content/frontmatter",
+    BLUME_GRAPHQL_UNKNOWN_CODE_SAMPLE: "/docs/references/graphql",
     BLUME_INCLUDE_CYCLE: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_MALFORMED: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_NOT_FOUND: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_OUTSIDE_ROOT: DOCS_CONTENT_INCLUDES,
+    BLUME_MDC_SYNTAX: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MDX_ATTRIBUTE_LIST: DOCS_OTHER_TOOLS_SYNTAX,
     BLUME_MDX_CURLY_ANCHOR: "/docs/content/syntax",
-
+    BLUME_MDX_EVENT_HANDLER: "/docs/content/islands",
+    BLUME_MDX_SYNTAX: DOCS_MARKDOWN_AND_MDX,
+    BLUME_MDX_UNCLOSED_ELEMENT: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MDX_UNDEFINED_NAME: DOCS_MARKDOWN_AND_MDX,
+    BLUME_MD_ATTRIBUTE_LIST: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MD_CURLY_ANCHOR: "/docs/content/syntax",
+    BLUME_MD_DIRECTIVE: "/docs/content/syntax",
+    BLUME_MD_GITHUB_ALERT: "/docs/content/syntax",
     BLUME_META_INVALID: "/docs/content/meta",
     BLUME_META_LOAD_FAILED: "/docs/content/meta",
+    BLUME_META_OUTSIDE_INCLUDE: "/docs/content/meta",
+    BLUME_META_UNKNOWN_PAGE: "/docs/content/meta",
     BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
     BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
     BLUME_NODE_VERSION: "/docs/quickstart",
+    BLUME_OPENAPI_DUPLICATE_OPERATION_ID: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_LOCAL_SERVER: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_NULLABLE: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_UNKNOWN_CODE_SAMPLE:
+      "/docs/references/openapi#code-samples-and-schemas",
+    BLUME_PUBLIC_OPENAPI_JSON: "/docs/discoverability/json-api",
     BLUME_SEARCH_SYNC_FAILED: "/docs/configuration/search",
     BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
     BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
@@ -72,15 +97,23 @@ const DOCS_PATHS = new Map(
     BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_UNRESOLVED_LINK: "/docs/content/sources/contentful",
     BLUME_SOURCE_UNSUPPORTED_NODE: "/docs/content/sources/payload",
+    BLUME_SVG_UNOPTIMIZED: "/docs/content/syntax#links-and-images",
+    BLUME_TEMPLATE_TAG: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_THEME_COLOR_INVALID: "/docs/configuration/theming",
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
+    BLUME_TSCONFIG_EXTENDS: "/docs/cli#type-checking",
+    BLUME_UNKNOWN_CODE_LANGUAGE: "/docs/content/syntax",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
     BLUME_UNKNOWN_DIRECTIVE: "/docs/content/syntax",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
     BLUME_UNKNOWN_OPTION: "/docs/cli",
+    BLUME_UNKNOWN_PROP: "/docs/content/components",
     BLUME_UNLOADABLE_FILE_NAME: "/docs/content",
+    BLUME_UNSUPPORTED_LINK_SCHEME: DOCS_CLI_VALIDATE,
     BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES_OBSIDIAN,
     BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES_OBSIDIAN,
+    BLUME_WIKILINK_UNSUPPORTED: DOCS_OTHER_TOOLS_SYNTAX,
     BLUME_YARN_PNP: "/docs/quickstart",
   })
 );
@@ -317,7 +350,7 @@ const findElement = (scope: Scope, position: number): Step | undefined => {
  * Returns 1-based line/column, or undefined when not even the first segment
  * matches.
  */
-const locatePath = (
+export const locatePath = (
   source: string,
   path: readonly (string | number)[]
 ): { column: number; line: number } | undefined => {