blume 2.0.2 → 2.1.0

package/src/core/config-input.ts

@@ -2,15 +2,20 @@ import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
-import type { AssistantAdapter } from "../ai/ask.ts";
+import type { AssistantAdapter, AssistantGatewayAdapter } from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { AnalyticsAdapter } from "../analytics/schema.ts";
+import type { CaptchaAdapter } from "../captcha/schema.ts";
+import type { ConsentAdapter } from "../consent/schema.ts";
 import type { DeploymentInput } from "../deploy/adapters/registry.ts";
 import type { CodeTheme } from "../markdown/themes.ts";
+import type { RateLimitAdapter } from "../ratelimit/schema.ts";
+import type { PlaygroundOptions } from "../reference/options.ts";
 import type { ReferenceAdapter } from "../reference/schema.ts";
 import type { AnySearchAdapter } from "../search/adapters/registry.ts";
 import type { SourceAdapterInput } from "../sources/registry.ts";
 import type { FontSlug } from "../theme/fonts.ts";
+import type { FooterSocial } from "./footer.ts";
 import type {
   blumeConfigSchema,
   OpenInChatProvider,
@@ -92,21 +97,64 @@ export type LogoConfig =
 export type BannerConfig =
   | string
   | {
-      /** The banner message. */
-      content: string;
+      /** The banner message, or a map of locale code to message. */
+      content: LocalizableLabel;
       /** Show a dismiss button; the choice is remembered per visitor. */
       dismissible?: boolean;
-      /** Stable key for remembering dismissal; defaults to the content. */
+      /**
+       * Stable key for remembering dismissal; defaults to the content (the
+       * default locale's, for a per-locale map).
+       */
       id?: string;
       /** An optional call-to-action link. */
       link?: {
         /** Link target (internal route or external URL). */
         href: string;
-        /** Link text. */
-        text: string;
+        /** Link text, or a map of locale code to text. */
+        text: LocalizableLabel;
       };
     };
 
+/** Defaults for hand-written endpoint pages, the ones with `api` frontmatter. */
+export interface ApiConfig {
+  /** How requests authenticate, unless a page sets `authMethod`. Defaults to none. */
+  auth?: {
+    method: "bearer" | "basic" | "key" | "none";
+    /** The header an API key goes in. Defaults to `x-api-key`. */
+    name?: string;
+  };
+  /**
+   * The Try it panel: `false` hides it, and `{ proxy }` sends requests through
+   * a CORS proxy, a URL or `true` for the built-in `/_api-proxy` route (server
+   * output only). Defaults to `true`, sending directly.
+   */
+  playground?: PlaygroundOptions;
+  /** The base URL an `api` path joins, like `https://api.acme.com/v1`. */
+  server?: string;
+}
+
+/** A link in the footer's row. */
+export interface FooterLink {
+  /** Link target (internal route or external URL). An external href opens in a new tab. */
+  href: string;
+  /** Link text, or a map of locale code to text. */
+  label: LocalizableLabel;
+}
+
+/**
+ * The site footer, below the content on every page: a row of links on one
+ * side, and social profile icons on the other.
+ */
+export interface FooterConfig {
+  /** Links in one row, left to right. */
+  links?: FooterLink[];
+  /**
+   * Social profiles, platform to URL, shown as icons in the order written:
+   * `{ github: "https://github.com/acme", x: "https://x.com/acme" }`.
+   */
+  socials?: Partial<Record<FooterSocial, string>>;
+}
+
 /**
  * Where content lives and how it's discovered. `root`/`include`/`exclude` are
  * zero-config shorthand for a single `filesystem()` source; set `sources` to
@@ -203,7 +251,8 @@ export interface ContentTypeConfig {
 // ---------------------------------------------------------------------------
 
 /**
- * A header label, optionally per locale: a plain string, or a map of locale
+ * A label, optionally per locale (header tabs and links, the banner, the
+ * footer): a plain string, or a map of locale
  * code to label (`{ en: "Docs", ja: "ドキュメント" }`). The active locale's
  * entry wins, then the default locale's, then the map's first entry.
  */
@@ -286,8 +335,8 @@ export interface FeaturedLink {
   href: string;
   /** Lucide icon name shown beside the label. */
   icon?: string;
-  /** Link label. */
-  label: string;
+  /** Link label, or a map of locale code to label. */
+  label: LocalizableLabel;
 }
 
 /**
@@ -312,8 +361,8 @@ export type SidebarConfig =
 export interface HeaderAction {
   /** Link target. An external href opens in a new tab. */
   href: string;
-  /** Link label. */
-  label: string;
+  /** Link label, or a map of locale code to label. */
+  label: LocalizableLabel;
 }
 
 /** Header, sidebar, tabs, and switcher configuration. */
@@ -325,7 +374,7 @@ export interface NavigationConfig {
   /** Pinned links shown above the generated sidebar sections. */
   featured?: FeaturedLink[];
   /**
-   * The GitHub link in the header. `true` derives it from `github` (the
+   * The GitHub link in the footer. `true` derives it from `github` (the
    * default), `false` hides it, and an absolute URL points it anywhere on
    * GitHub — an organization, say, when the docs repo itself is private.
    */
@@ -520,6 +569,13 @@ export interface AssistantRetrievalConfig {
 
 /** The chat assistant. */
 export interface AssistantConfig {
+  /**
+   * A bot check from `blume/captcha` — `turnstile({ siteKey })` or
+   * `hcaptcha({ siteKey })`. The panel sends a token with each question and
+   * the generated route verifies it (with `TURNSTILE_SECRET_KEY` or
+   * `HCAPTCHA_SECRET_KEY`) before the model runs.
+   */
+  captcha?: CaptchaAdapter;
   /**
    * Origins allowed to call the generated endpoint from another site — a
    * marketing page that embeds an ask box, for example — or `"*"` to allow
@@ -548,10 +604,10 @@ export interface AssistantConfig {
   instructions?: string;
   /**
    * Which backend answers: the descriptor an adapter factory returns —
-   * `gateway({ model })`, `openrouter({ model, reasoning })`,
-   * `llmgateway({ model })`, `inkeep({ model })`, or
-   * `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`, all exported
-   * from `blume/ai`. Each adapter owns its model, key env var, reasoning
+   * `openai({ model, baseUrl })`, `anthropic({ model })`,
+   * `gemini({ model })`, `grok({ model })`, `gateway({ model })`,
+   * `openrouter({ model, reasoning })`, `llmgateway({ model })`, or
+   * `inkeep({ model })`, all exported from `blume/ai`. Each adapter owns its model, key env var, reasoning
    * mapping, and `providerOptions` passthrough. Defaults to
    * `gateway({ model: "openai/gpt-5.5" })`.
    */
@@ -562,8 +618,23 @@ export interface AssistantConfig {
    * backend — at the cost of recall. Defaults keep the built-in behavior.
    */
   retrieval?: AssistantRetrievalConfig;
+  /**
+   * A Contact support link in the panel once there's a conversation: a
+   * `mailto:` address starts an email with the conversation as its body; a
+   * URL or root-relative path gets the conversation's `thread` id, which the
+   * assistant's analytics events carry too.
+   */
+  support?: string;
   /** Starter prompts shown before the first question. */
   suggestions?: AssistantSuggestion[];
+  /**
+   * Let the model search the docs and read whole pages itself, over several
+   * steps, instead of answering only from the excerpts retrieved up front.
+   * Defaults to `true`, except for `openai()` with a `baseUrl`, whose model
+   * may not support tool calling. `inkeep()` does its own retrieval and
+   * ignores it.
+   */
+  tools?: boolean;
 }
 
 /** What the AI Catalog (ARD) manifest carries. */
@@ -693,6 +764,12 @@ export interface I18nConfig {
   locales: LocaleConfigInput[];
   /** `dir`: locale directories (`fr/page.mdx`). `dot`: filename suffix (`page.fr.mdx`). */
   parser?: "dir" | "dot";
+  /**
+   * Send a visitor who lands on the default language's home page to the home
+   * page in their browser's preferred language, until they pick a language
+   * with the switcher. Defaults to `false`.
+   */
+  routeByBrowserLanguage?: boolean;
   /**
    * Per-locale UI string overrides, e.g.
    * `{ fr: { search: { button: "Rechercher" } } }`.
@@ -802,11 +879,19 @@ type RedirectStatus = RedirectStatusPermanent | RedirectStatusTemporary;
 
 /** A URL redirect rule. */
 export interface RedirectConfig {
-  /** Path to redirect from. */
+  /**
+   * Path to redirect from: an exact path, or a pattern. `:name` matches one
+   * segment, `:name*` as the last segment the rest of the path
+   * (`/beta/:slug*`), and `*` ending a segment the rest from there
+   * (`/old/article-*`).
+   */
   from: string;
   /** HTTP status. Defaults to `301`. */
   status?: RedirectStatus;
-  /** Path or URL to redirect to. */
+  /**
+   * Path or URL to redirect to. Reads `from`'s captures as `/:name` (or `*`
+   * for what `*` matched): `/v2/:slug*`.
+   */
   to: string;
 }
 
@@ -890,6 +975,13 @@ export interface AgentsConfig {
   markdownComponents?: Record<string, ComponentMarkdown>;
   /** Expose the docs as an MCP server for agents. */
   mcp?: McpConfig;
+  /**
+   * Generate the site's own agent skill: a `SKILL.md` named after the site,
+   * built from its navigation and page descriptions, served at `/skill.md`
+   * and in the skills discovery index. Needs `deployment.site`. A skill in
+   * `agents.skills` with the same name replaces it. Defaults to `true`.
+   */
+  skillMd?: boolean;
   /**
    * Publish Agent Skills for discovery: a directory (resolved against the
    * project root) whose subdirectories each hold a `SKILL.md`. Skills are
@@ -958,13 +1050,15 @@ export interface OgConfig {
    */
   enabled?: boolean;
   /**
-   * Fonts for the generated card, extending Takumi's Latin-only default so
-   * non-Latin titles (CJK, and so on) render instead of tofu. A bare string is
-   * a Google Fonts family fetched at build; the name-only object form pins
-   * weights (`700`, `[400, 700]`, or a `"100..900"` variable range) and
-   * styles; the `src` form reads a local font file from the project instead.
-   * When omitted and `theme.fonts` is explicitly configured, the theme's
-   * display and body fonts are used automatically — pass `[]` to opt out.
+   * Fonts for the generated card, replacing the default stack: Takumi's
+   * Latin-only built-in font plus a Noto fallback per script, which a card
+   * fetches only when its text needs one. A bare string is a Google Fonts
+   * family fetched at build; the name-only object form pins weights (`700`,
+   * `[400, 700]`, or a `"100..900"` variable range) and styles; the `src`
+   * form reads a local font file from the project instead. When omitted and
+   * `theme.fonts` is explicitly configured, the theme's display and body
+   * fonts are used automatically, ahead of the fallbacks — pass `[]` to opt
+   * out of both.
    */
   fonts?: (
     | string
@@ -1068,6 +1162,23 @@ export interface SoftwareConfig {
 
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
+  /**
+   * Meta tags written into every page's head, name to content: site
+   * verification tokens, `theme-color`, an app banner, and anything else
+   * Blume has no setting for. `og:*`, `fb:*`, and `article:*` tags render
+   * with `property`, the rest with `name`. A tag Blume writes itself
+   * (`description`, `robots`, `og:image`, `twitter:card`, …) is refused.
+   *
+   * ```ts
+   * seo: {
+   *   metatags: {
+   *     "google-site-verification": "abc123",
+   *     "theme-color": "#0b5fff",
+   *   },
+   * }
+   * ```
+   */
+  metatags?: Record<string, string>;
   /** Per-page Open Graph image generation. */
   og?: OgConfig;
   /**
@@ -1239,6 +1350,37 @@ export type ExportConfig =
       pdf?: boolean;
     };
 
+/** Page feedback: the rating, and an optional written comment after it. */
+export interface FeedbackConfig {
+  /**
+   * After the rating, offer a box to say more. The comment is sent as a
+   * `feedback_comment` event through every analytics adapter with an event
+   * API. Defaults to `false`.
+   */
+  comments?: boolean;
+  /** Show the rating. Defaults to `true`. */
+  enabled?: boolean;
+}
+
+/**
+ * "Listen to this page". `true` reads pages aloud with the reader's browser
+ * voices (no key, any host). The object form's `provider` generates neural
+ * audio at build instead, one cached clip per sentence, and falls back to
+ * browser voices where no clips exist. Defaults to `false`.
+ */
+export type NarrationConfig =
+  | boolean
+  | {
+      /** Show the player. Defaults to `true` in the object form. */
+      enabled?: boolean;
+      /**
+       * Generate audio at build with a speech model:
+       * `gateway({ model: "openai/tts-1-hd", voice: "alloy" })` from
+       * `blume/ai`. Without it, pages are read with browser voices.
+       */
+      provider?: AssistantGatewayAdapter;
+    };
+
 /**
  * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
  * an unknown key fails the build so typos are caught — and `extend` carves
@@ -1333,6 +1475,8 @@ export interface BlumeConfig {
   agents?: AgentsConfig;
   /** Model-facing features: the assistant and the "Open in chat" action. */
   ai?: AiConfig;
+  /** Defaults for hand-written endpoint pages (`api` frontmatter). */
+  api?: ApiConfig;
   /**
    * Analytics adapters from `blume/analytics`, emitted into `<head>` of every
    * production page in this order: `[posthog({ key }), vercel(),
@@ -1351,6 +1495,14 @@ export interface BlumeConfig {
    * compose: with both set, a page lands at `{deployment.base}/{basePath}/page`.
    */
   basePath?: string;
+  /**
+   * Ask readers before analytics runs, with an adapter from `blume/consent`:
+   * `native()` for Blume's own banner, or a hosted consent manager
+   * (`osano({ customerId, configId })`, `ethyca({ privacyCenter })`). Every
+   * `analytics` adapter waits until the reader allows analytics. Unset runs
+   * analytics as it loads.
+   */
+  consent?: ConsentAdapter;
   /** Where content lives and how it's discovered. */
   content?: ContentConfig;
   /**
@@ -1374,8 +1526,17 @@ export interface BlumeConfig {
   examples?: string | ExamplesConfig;
   /** Reader-facing PDF/EPUB export actions. Defaults to `false`. */
   export?: ExportConfig;
-  /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
-  feedback?: boolean;
+  /**
+   * The "Was this page helpful?" rating at the foot of each page. On by
+   * default; `false` hides it. `{ comments: true }` also asks for a written
+   * comment after the rating, sent through your analytics adapters.
+   */
+  feedback?: boolean | FeedbackConfig;
+  /**
+   * The site footer: social profile icons and up to four link columns. Unset,
+   * the site has no footer.
+   */
+  footer?: FooterConfig;
   /** Opt-in custom frontmatter keys, validated by schemas you supply. */
   frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
@@ -1392,8 +1553,17 @@ export interface BlumeConfig {
   logo?: LogoConfig;
   /** Markdown / MDX rendering behavior. */
   markdown?: MarkdownConfig;
+  /** "Listen to this page" narration. Defaults to `false`. */
+  narration?: NarrationConfig;
   /** Header, sidebar, tabs, and switchers. */
   navigation?: NavigationConfig;
+  /**
+   * 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.
+   */
+  rateLimit?: false | RateLimitAdapter;
   /** React island behavior (compiler auto-memoization). */
   react?: ReactConfig;
   /** URL redirect rules. */
@@ -1414,6 +1584,12 @@ export interface BlumeConfig {
   title?: string;
   /** On-page table of contents. Defaults to on (H2–H3). */
   toc?: TocConfig;
+  /**
+   * Content variables: `{{name}}` in a page reads the value, in prose, code,
+   * and links alike. Names take letters, digits, `_`, and `-`; an undefined
+   * name in prose fails the build. Defaults to none.
+   */
+  variables?: Record<string, string>;
   /** Docs versioning (opt-in frozen snapshots with a version switcher). */
   versions?: VersionsConfig;
 }

package/src/core/data.ts

@@ -1,8 +1,10 @@
+import type { CaptchaSettings } from "../captcha/schema.ts";
+import type { EndpointAuth } from "../components/content/api-page.ts";
 import type { SearchAdapterKind } from "../search/adapters/registry.ts";
 import type { StructuredDataIdentity } from "../seo/jsonld.ts";
 import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
-import type { ResolvedConfig } from "./schema.ts";
+import type { LocalizableLabel, ResolvedConfig } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 
 /**
@@ -42,10 +44,14 @@ export interface BlumeFavicon {
   dark?: { href: string; type?: string };
 }
 
-/** Announcement banner, normalized from its config (string shorthand or object). */
+/**
+ * Announcement banner, normalized from its config (string shorthand or
+ * object). `content` and the link's `text` may be per-locale maps, resolved
+ * when the banner renders (see `core/localizable.ts`).
+ */
 export interface BlumeBanner {
-  content: string;
-  link?: { href: string; text: string };
+  content: LocalizableLabel;
+  link?: { href: string; text: LocalizableLabel };
   dismissible: boolean;
   /** Dismissal key: the configured id, else the content itself. */
   key: string;
@@ -71,6 +77,8 @@ export interface BlumeDataI18n {
   fallbackLocale: string | null;
   hideDefaultLocalePrefix: boolean;
   locales: BlumeDataLocale[];
+  /** Send visitors from the default home page to their browser's language. */
+  routeByBrowserLanguage: boolean;
 }
 
 /** A single content route, with the metadata custom pages can read. */
@@ -124,9 +132,23 @@ export interface BlumeDataConfig {
   appleIcon: BlumeFavicon | null;
   /** The assistant's empty-state suggestions, or `null` when the assistant is off. */
   assistant: {
+    /** The bot check's public settings, or `null` without one. */
+    captcha: CaptchaSettings | null;
     endpoint: string | null;
     suggestions: NonNullable<ResolvedConfig["ai"]["assistant"]>["suggestions"];
+    /** The Contact support link (`ai.assistant.support`), or `null`. */
+    support: string | null;
   } | null;
+  /**
+   * Defaults for hand-written endpoint pages (`api` frontmatter): the server a
+   * path joins, the default auth, and the playground, its `proxy` resolved to
+   * the URL sends go through (the built-in route under `basePath`) or `false`.
+   */
+  api: {
+    auth?: EndpointAuth;
+    playground: { enabled: boolean; proxy: string | false };
+    server?: string;
+  };
   banner: BlumeBanner | null;
   /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */
   basePath: string;
@@ -134,6 +156,11 @@ export interface BlumeDataConfig {
   codeThemes: ResolvedConfig["markdown"]["code"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
+  /**
+   * The consent adapter's descriptor, or `null` without one. When set, the
+   * layouts hold analytics until the reader allows it.
+   */
+  consent: ResolvedConfig["consent"];
   /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
   dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
@@ -156,7 +183,12 @@ export interface BlumeDataConfig {
     sitemap: boolean;
   };
   favicon: BlumeFavicon;
+  /** Whether pages end with the "Was this page helpful?" rating. */
   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: ResolvedConfig["footer"] | null;
   /**
    * Repo coordinates for content components that address the API or build
    * their own repo links (`<GithubInfo>`, the OG card's footer slug), carrying
@@ -176,6 +208,14 @@ export interface BlumeDataConfig {
   logo: BlumeLogo | null;
   /** Hosted MCP server, or `null` when MCP is off. */
   mcp: { name: string; route: string } | null;
+  /** `seo.metatags`: the site's own tags for every page's head, or `null`. */
+  metatags: Record<string, string> | null;
+  /**
+   * "Listen to this page": `generated` when a `narration.provider` makes
+   * `blume build` write audio clips the player should look for, else the
+   * player reads with browser voices. `null` when narration is off.
+   */
+  narration: { generated: boolean } | null;
   /**
    * Open Graph image generation. Card fonts are baked into the generated OG
    * endpoint (they can carry absolute build-machine paths) and deliberately

package/src/core/diagnostics.ts

@@ -24,6 +24,7 @@ const DOCS_BASE = "https://useblume.dev";
 const DOCS_DEPLOYMENT = "/docs/deployment";
 const DOCS_CLI_VALIDATE = "/docs/cli/validate";
 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";
 
@@ -69,10 +70,12 @@ const DOCS_PATHS = new Map(
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+    BLUME_UNKNOWN_DIRECTIVE: "/docs/content/syntax",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
     BLUME_UNKNOWN_OPTION: "/docs/cli",
-    BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES,
-    BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES,
+    BLUME_UNLOADABLE_FILE_NAME: "/docs/content",
+    BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES_OBSIDIAN,
+    BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES_OBSIDIAN,
     BLUME_YARN_PNP: "/docs/quickstart",
   })
 );

package/src/core/directive-diagnostics.ts

@@ -0,0 +1,99 @@
+import type { Nodes } from "mdast";
+import { mdxToMdast } from "satteri";
+
+import {
+  CALLOUT_ALIASES,
+  CALLOUT_TYPES,
+  calloutTypeFor,
+} from "../markdown/directives.ts";
+import { MDX_BODY_FEATURES } from "../markdown/features.ts";
+import { strippedLineOffset } from "./sources/normalize.ts";
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+
+// A line that may open a container directive: a colon fence and a name, after
+// any quote or list indentation. A page is parsed only when one of these
+// names something other than a callout, so pages without one cost a scan.
+const CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
+
+const codeList = (names: Iterable<string>): string =>
+  [...names].map((name) => `\`${name}\``).join(", ");
+
+const CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
+
+/** A container directive that isn't a callout, and its line in `text`. */
+interface UnknownContainer {
+  line: number;
+  name: string;
+}
+
+/**
+ * Every container directive in an `.mdx` body whose name isn't a callout, in
+ * source order. The body is parsed as the renderer reads it, so a fence in a
+ * code block or a `::: name` that isn't a directive at all never counts. A
+ * body MDX can't parse fails to render anyway, with its own error.
+ */
+const unknownContainers = (text: string): UnknownContainer[] => {
+  const named = [...text.matchAll(CONTAINER_OPENING)].some(
+    (match) => calloutTypeFor(match.groups?.name ?? "") === null
+  );
+  if (!named) {
+    return [];
+  }
+  let tree: Nodes;
+  try {
+    tree = mdxToMdast(text, { features: MDX_BODY_FEATURES });
+  } catch {
+    return [];
+  }
+  const found: UnknownContainer[] = [];
+  const walk = (node: Nodes): void => {
+    if (
+      node.type === "containerDirective" &&
+      calloutTypeFor(node.name) === null
+    ) {
+      found.push({ line: node.position?.start.line ?? 1, name: node.name });
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return found;
+};
+
+/**
+ * Warn about each `:::name` container in an `.mdx` entry that isn't a callout.
+ * The page keeps its content — the body renders between the literal `:::`
+ * lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
+ * `:::details` carried over from another docs tool, should read as the
+ * mistake it is rather than as a finished page. Lines point into the file
+ * the author wrote, a partial's own file for a container an `<include>`
+ * brought in.
+ */
+export const unknownDirectiveDiagnostics = (
+  entry: SourceEntry,
+  sourceName: string
+): Diagnostic[] => {
+  if (entry.body.format !== "mdx") {
+    return [];
+  }
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset =
+    entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(
+    ({ line, name }) => {
+      const origin = entry.expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNKNOWN_DIRECTIVE",
+        file: origin?.file ?? page,
+        line: origin?.line ?? line + offset,
+        message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
+        severity: "warning",
+        suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
+      };
+    }
+  );
+};

package/src/core/footer.ts

@@ -0,0 +1,26 @@
+/**
+ * The social platforms `footer.socials` links to, each shown by its brand
+ * icon: Mintlify's set, without its aliases (`twitter` and `x-twitter` are
+ * `x`, `earth-americas` is `website`).
+ */
+export const FOOTER_SOCIALS = [
+  "bluesky",
+  "discord",
+  "facebook",
+  "github",
+  "hacker-news",
+  "instagram",
+  "linkedin",
+  "medium",
+  "podcast",
+  "reddit",
+  "slack",
+  "telegram",
+  "threads",
+  "website",
+  "x",
+  "youtube",
+] as const;
+
+/** A platform `footer.socials` links to. */
+export type FooterSocial = (typeof FOOTER_SOCIALS)[number];