blume 1.7.2 → 2.0.0

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

@@ -1,4 +1,5 @@
 import type { BlumeConfig } from "./config-input.ts";
+import { BlumeError } from "./diagnostics.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type { Diagnostic } from "./types.ts";
 /**
@@ -35,10 +36,12 @@ import type { Diagnostic } from "./types.ts";
  *   dismissible }`.
  *
  * **Content & navigation**
- * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
- *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
- *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
- *   implicit filesystem source.
+ * - `content` — where content lives: adapters from `blume/sources` under
+ *   `sources` (`filesystem({ root })`, `mdxRemote({…})`, `githubReleases({…})`,
+ *   `sanity({…})`, `notion({…})`, `contentful({…})`, `payload({…})`,
+ *   `strapi({…})`, `obsidian({…})`, or `custom(source)`), or the
+ *   zero-config shorthand `root`/`include`/`exclude`, which desugars to one
+ *   `filesystem()` source and can't be combined with `sources`.
  * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
  *   switchers), pinned `featured` links, header `actions` and the one `cta`,
  *   and the `repo` link (a toggle, or a URL). Omit `sidebar` to generate it
@@ -60,35 +63,41 @@ import type { Diagnostic } from "./types.ts";
  * - `export` — reader-facing PDF/EPUB export actions (off by default).
  *
  * **Reference docs**
- * - `openapi` — native OpenAPI reference: one real page per operation, woven
- *   into the sidebar and search. Point `sources`/`spec` at your spec.
- * - `asyncapi` — native AsyncAPI reference with the same treatment; 2.x specs
- *   are normalized to 3.x automatically.
- *
- * **Search & AI**
- * - `search` — search backend `provider` (`orama` by default; `pagefind`,
- *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
- *   credential block.
- * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model), `llmsTxt`
- *   (emit `llms.txt`), `mcp` (expose the docs as an MCP server for connecting
- *   agents), and `markdownComponents` (Markdown serializers for custom
- *   components in agent-facing output).
+ * - `reference` — API references as a list of adapters from
+ *   `blume/reference`: `openapi({…})` and `asyncapi({…})` render native pages
+ *   (one real page per operation, woven into the sidebar and search; AsyncAPI
+ *   2.x specs are normalized to 3.x), `graphql({…})` renders a schema, and
+ *   `scalar({…})` embeds the Scalar reference instead.
+ *
+ * **Search, AI & agents**
+ * - `search` — a search adapter from `blume/search` (`orama()` by default;
+ *   `flexsearch()`, `pagefind()`, `algolia({…})`, `oramaCloud({…})`,
+ *   `typesense({…})`, `mixedbread({…})`, or `false`), or `{ provider,
+ *   popular, indexing }` to add curated links and indexing settings.
+ * - `ai` — what faces a model at read time: `ask` (the Ask AI assistant, with
+ *   a provider adapter from `blume/ai` such as `gateway()` or `openrouter()`)
+ *   and `openInChat` (the "Open in chat" page action).
+ * - `agents` — the machine-readable surface: `llmsTxt`, the JSON `api`, the
+ *   `mcp` server, published `skills`, `markdownComponents` (Markdown
+ *   serializers for custom components), the `catalog` manifests,
+ *   `agentReadability`, robots `contentSignals`, `webmcp`, and `webBotAuth`.
  *
  * **SEO, feeds & analytics**
- * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
- *   JSON-LD, `agentReadability`, and robots `contentSignals`.
- * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
- *   GA, …).
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, and
+ *   `structuredData` JSON-LD.
+ * - `analytics` — a list of adapters from `blume/analytics`, one per provider
+ *   (`posthog()`, `googleAnalytics()`, `plausible()`, `fathom()`, `vercel()`,
+ *   `cloudflare()`, …), or `script()` for anything without one.
  *
  * **Astro**
  * - `integrations` — Astro integrations appended after Blume's built-ins, in
  *   declaration order. Install and maintain each integration in the site.
  *
  * **Deployment & i18n**
- * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
- *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
- *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
- *   Cloudflare from the platform env.
+ * - `deployment` — a host adapter from `blume/deploy` (`vercel()`, `node()`,
+ *   `netlify()`, `cloudflare()`) for a server build, each taking `site`,
+ *   `base`, and `output`; or `{ site, base }` for a static build anywhere.
+ *   `site` is auto-detected on Vercel/Netlify/Cloudflare from the platform env.
  * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
  *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
  *
@@ -103,33 +112,41 @@ import type { Diagnostic } from "./types.ts";
  *
  * @example A production docs site with theming, search, and deployment.
  * ```ts
+ * import { vercel } from "blume/deploy";
+ * import { orama } from "blume/search";
+ *
  * export default defineConfig({
  *   title: "Acme Docs",
  *   description: "Build faster with Acme.",
  *   logo: { image: "/logo.svg", text: "Acme" },
  *   github: { owner: "acme", repo: "acme" },
- *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   theme: { accent: "purple", fonts: { body: "inter" }, radius: "lg" },
  *   navigation: {
  *     tabs: [
  *       { label: "Guides", path: "/guides" },
  *       { label: "API", path: "/api" },
  *     ],
  *   },
- *   search: { provider: "orama" },
- *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ *   search: orama(),
+ *   // A server build on Vercel.
+ *   deployment: vercel({ site: "https://docs.acme.com" }),
  * });
  * ```
  *
  * @example An OpenAPI reference with the Ask AI assistant enabled.
  * ```ts
+ * import { openapi } from "blume/reference";
+ *
  * export default defineConfig({
  *   title: "Acme API",
- *   openapi: {
- *     enabled: true,
- *     route: "/reference",
- *     sources: [{ label: "Core", spec: "./openapi.json" }],
- *   },
- *   ai: { ask: { enabled: true }, llmsTxt: true },
+ *   reference: [
+ *     openapi({
+ *       route: "/reference",
+ *       sources: [{ label: "Core", spec: "./openapi.json" }],
+ *     }),
+ *   ],
+ *   agents: { llmsTxt: true },
+ *   ai: { ask: { enabled: true } },
  * });
  * ```
  *
@@ -138,6 +155,15 @@ import type { Diagnostic } from "./types.ts";
  * @see https://useblume.dev/docs for the full configuration reference.
  */
 export declare const defineConfig: (config: BlumeConfig) => BlumeConfig;
+/**
+ * A config that fails validation. `diagnostic` folds every issue into the one
+ * message a command prints; `issues` keeps each on its own, with its own
+ * line, for `blume upgrade`, which lists them one by one.
+ */
+export declare class ConfigValidationError extends BlumeError {
+    readonly issues: Diagnostic[];
+    constructor(diagnostic: Diagnostic, issues: Diagnostic[]);
+}
 /** Result of loading + validating a project config. */
 export interface ConfigLoadResult {
     config: ResolvedConfig;

package/dist/types/core/content-assets.d.ts

@@ -0,0 +1,76 @@
+import type { ContentSource } from "./sources/types.ts";
+import type { PageRecord } from "./types.ts";
+/**
+ * Colocated content images — `![alt](./diagram.png)` next to the page that
+ * references it. The HTML render optimizes these through `astro:assets` into
+ * hashed `_astro/` files, but that mapping doesn't exist yet when the raw
+ * agent-facing Markdown (`/<route>.md`, llms-full.txt, MCP) is snapshotted at
+ * generate time — so a verbatim relative path would 404 for every agent
+ * fetching the page by URL. Instead, the originals are served at
+ * `/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.
+ */
+/** The endpoint route prefix colocated content images are served under. */
+export declare const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
+/**
+ * The endpoint param a colocated image is served under: its project-relative
+ * path (readable, collision-free — it mirrors the source tree). A file outside
+ * the project root can't be addressed that way (`..` segments don't survive a
+ * URL), so it falls back to a content-addressed name.
+ */
+export declare const contentAssetParam: (projectRoot: string, absPath: string) => string;
+/**
+ * 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 declare const isRelativeImageTarget: (target: string) => boolean;
+/**
+ * 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.
+ */
+export declare const resolveRelativeImage: (sourceDir: string, target: string) => string | null;
+/**
+ * Rewrite a page's relative image references 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 declare const rewriteRelativeImages: (options: {
+    source: string;
+    sourcePath: string;
+    projectRoot: string;
+    deployBase?: string;
+    register?: (param: string, absPath: string) => void;
+}) => string;
+/**
+ * Every colocated image 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
+ * include-expanded text, so a partial's colocated images (rebased into the
+ * including page by the expander) are served too — keeping the served set and
+ * the rewritten URLs from drifting apart.
+ */
+export declare const collectContentAssets: (project: {
+    context: {
+        root: string;
+    };
+    manifest: {
+        routes: {
+            id: string;
+            sourcePath?: string;
+        }[];
+    };
+    graph: {
+        pages: PageRecord[];
+    };
+    sources?: ContentSource[];
+}) => Promise<Record<string, string>>;

package/dist/types/core/custom-pages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Custom `.astro` pages (the `pages/` folder): discovery and the routes they
+ * serve. Lives in core so the content graph can see them too — a header tab or
+ * brand link that points at a custom page must know the page exists only at
+ * its own path, not under every locale prefix.
+ */
+/** A user `.astro` page and the route pattern Blume injects it at. */
+export interface CustomPageRoute {
+    /** Route pattern, e.g. `/changelog` or `/examples/[slug]`. */
+    pattern: string;
+    /** Absolute path to the user's `.astro` page file. */
+    entrypoint: string;
+}
+/**
+ * Discover user `.astro` pages and map them to route patterns. Files keep their
+ * original location; only the route pattern is derived (index -> parent,
+ * dynamic `[param]` segments preserved).
+ */
+export declare const discoverPages: (pagesRoot: string) => Promise<CustomPageRoute[]>;
+/** {@link discoverPages} for synchronous callers (e.g. the sitemap builder). */
+export declare const discoverPagesSync: (pagesRoot: string) => CustomPageRoute[];
+/** Segments of a static, shareable page pattern; null for dynamic/private ones. */
+export declare const staticSegments: (pattern: string) => string[] | null;
+/**
+ * The static routes served by custom `.astro` pages — the same filtering as
+ * the generated OG cards, but yielding the routes themselves. Feeds the route
+ * sets that must know every servable page beyond the content graph (the link
+ * checker, the sitemap); dynamic (`[param]`) and private segments are skipped
+ * because their concrete URLs can't be enumerated statically.
+ */
+export declare const customStaticRoutes: (pages: {
+    pattern: string;
+}[]) => string[];

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

@@ -1,7 +1,8 @@
+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, SearchProvider } from "./schema.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 /**
  * The shape of the `blume:data` virtual module — the resolved, serializable
@@ -102,6 +103,11 @@ export interface BlumeRoute {
     lastModified: string | null;
     /** Resolved locale code (the default locale when not under i18n). */
     locale: string;
+    /**
+     * True when the page's source publishes one language only (GitHub
+     * Releases), so the page renders without a language switcher.
+     */
+    monolingual: boolean;
     path: string;
     title: string;
     /** Resolved docs version (`""` for the current docs). */
@@ -115,7 +121,8 @@ export interface BlumeRoute {
 }
 /** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
 export interface BlumeDataConfig {
-    analytics: NonNullable<ResolvedConfig["analytics"]> | null;
+    /** Analytics adapter descriptors, in configured order; empty when none. */
+    analytics: ResolvedConfig["analytics"];
     /** Apple touch icon, or `null` when none is configured/detected. */
     appleIcon: BlumeFavicon | null;
     /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
@@ -126,23 +133,26 @@ export interface BlumeDataConfig {
     banner: BlumeBanner | null;
     /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */
     basePath: string;
-    /** `markdown.codeBlocks.theme`: light/dark Shiki themes for code surfaces. */
-    codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
+    /** `markdown.code.theme`: light/dark Shiki themes for code surfaces. */
+    codeThemes: ResolvedConfig["markdown"]["code"]["theme"];
     /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
     codeWrap: boolean;
     /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
     dateFormat: ResolvedConfig["dateFormat"];
     description: string | undefined;
     /**
-     * Which agent-discovery resources exist for the layout to advertise in every
-     * page's `<head>` (`seo.agentReadability`, `ai.llmsTxt.enabled`) — the HTML
-     * counterpart of the homepage-only HTTP `Link` header, for agents that enter
-     * on a deep page (see `ai/link-headers.ts`). `sitemap` (`seo.sitemap` with a
+     * Which agent-discovery resources exist for every layout to advertise in its
+     * page's `<head>` (`agents.agentReadability`, `agents.llmsTxt.enabled`) via
+     * the shared `DiscoveryLinks.astro` partial — the HTML counterpart of the
+     * homepage-only HTTP `Link` header, for agents that enter on a deep page
+     * (see `ai/link-headers.ts`). `sitemap` (`seo.sitemap` with a
      * `deployment.site`, the condition under which one is emitted) feeds the
      * 404 page's recovery links rather than the head.
      */
     discovery: {
         agentReadability: boolean;
+        /** Whether the AI Catalog / ARD manifest is published (`agents.catalog`). */
+        aiCatalog: boolean;
         /** Whether the JSON docs API and its `/openapi.json` are published. */
         api: boolean;
         llmsTxt: boolean;
@@ -216,7 +226,8 @@ export interface BlumeDataConfig {
             label: string;
             route: string;
         }[];
-        provider: SearchProvider;
+        /** The configured adapter's kind (`none` when search is disabled). */
+        provider: SearchAdapterKind;
     };
     /** Deployment site URL, or `null` when none is configured/detected. */
     site: string | null;
@@ -226,8 +237,8 @@ export interface BlumeDataConfig {
     /** Table-of-contents settings: whether to show it and the heading range. */
     toc: ResolvedConfig["toc"];
     /**
-     * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
-     * list tool to fetch (`ai.llmsTxt.enabled`).
+     * WebMCP in-page tools (`agents.webmcp`), plus whether llms.txt exists for the
+     * list tool to fetch (`agents.llmsTxt.enabled`).
      */
     /** Docs versioning config; `null` when the site is unversioned. */
     versions: NonNullable<ResolvedConfig["versions"]> | null;
@@ -241,6 +252,12 @@ export interface BlumeDataConfig {
         handle?: string;
     };
 }
+/**
+ * The `discovery` flags the head partial (`components/layout/DiscoveryLinks.astro`)
+ * advertises — every layout's `discovery` prop is typed from here so a renamed
+ * or added flag surfaces in the shells at typecheck instead of drifting.
+ */
+export type DiscoveryHeadLinks = Pick<BlumeDataConfig["discovery"], "agentReadability" | "aiCatalog" | "llmsTxt">;
 /**
  * The compact snapshot the layout serializes into the page for React island
  * hooks (`blume/hooks`). Islands hydrate independently, so this is read from a

package/dist/types/core/define-components.d.ts

@@ -13,18 +13,21 @@ export interface IslandDescriptor {
 }
 /** A component override: a static component or a hydrated island. */
 export type ComponentOverride = ComponentReference | IslandDescriptor;
-/** User-authored component overrides, grouped by surface. */
+/**
+ * User-authored component overrides, grouped by surface. Blume reads this file
+ * statically (never executing it), so every entry must be an imported
+ * identifier, a path string, or a `{ component, client, media }` object literal
+ * — an entry with a `client` mode is an island, hydrated through a generated
+ * wrapper.
+ */
 export interface ComponentOverrides {
-    /**
-     * Interactive framework components made available in every `.mdx` page. Like
-     * `mdx`, but hydrated: entries default to `client: "visible"`. Shorthand for
-     * an `mdx` descriptor with a client mode, and the config-file equivalent of
-     * dropping a component in the `islands/` folder.
-     */
-    islands?: Record<string, ComponentOverride>;
     /** Layout slot overrides (`Header`, `Sidebar`, `Footer`, ...). */
     layout?: Record<string, ComponentOverride>;
-    /** MDX component map overrides (`Callout`, `Card`, ...). */
+    /**
+     * MDX component map overrides (`Callout`, `Card`, ...) and additions,
+     * available in every `.mdx` page. Give an entry a `client` mode to hydrate
+     * it — the config-file equivalent of dropping a component in `islands/`.
+     */
     mdx?: Record<string, ComponentOverride>;
 }
 /**

package/dist/types/core/deployment-env.d.ts

@@ -1,15 +1,10 @@
 import type { ResolvedConfig } from "./schema.ts";
 /**
- * Adapters whose `deployment.site` arrives from platform env vars at deploy
- * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
- * from "site is missing *here*, but the platform will set it".
- */
-export declare const SITE_INFERRING_ADAPTERS: ReadonlySet<string>;
-/**
- * Fill in `deployment.adapter` and `deployment.site` from platform env vars
- * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit
- * config always wins, and the adapter is only inferred for server output (it
- * has no effect on static builds). Mirrors Astro's platform auto-detection so a
- * project deployed to a known host gets a working canonical origin for free.
+ * Fill in the deployment `site` from platform env vars (Vercel, Netlify,
+ * Cloudflare Pages) when the config hasn't set one. Explicit config always
+ * wins. Each adapter's platform declares its own detection and URL vars (see
+ * `deploy/platforms/*`); the configured adapter is asked first, then every
+ * other platform, so a static build deployed to a known host gets a working
+ * canonical origin for free, mirroring Astro's platform auto-detection.
  */
 export declare const applyDeploymentEnv: (config: ResolvedConfig, env?: NodeJS.ProcessEnv) => ResolvedConfig;

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

@@ -0,0 +1,10 @@
+import baseMatter from "gray-matter";
+type MatterInput = Parameters<typeof baseMatter>[0];
+type MatterOptions = Parameters<typeof baseMatter>[1];
+type ReadArgs = Parameters<typeof baseMatter.read>;
+type StringifyArgs = Parameters<typeof baseMatter.stringify>;
+declare const matter: ((input: MatterInput, options?: MatterOptions) => baseMatter.GrayMatterFile<baseMatter.Input>) & typeof baseMatter & {
+    read: (filepath: ReadArgs[0], options?: ReadArgs[1]) => baseMatter.GrayMatterFile<string>;
+    stringify: (file: StringifyArgs[0], data: StringifyArgs[1], options?: StringifyArgs[2]) => string;
+};
+export default matter;

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

@@ -0,0 +1,18 @@
+import type { FolderMeta, ResolvedConfig, ResolvedI18nConfig, ResolvedVersionsConfig } from "./schema.ts";
+import type { ContentGraph, PageRecord } from "./types.ts";
+interface BuildContentGraphOptions {
+    /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
+    basePath?: string;
+    /** The header brand link as configured (`logo.href`, default `/`). */
+    brandHref?: string;
+    /** Routes served outside the content tree that tabs may link to directly. */
+    extraRoutes?: ReadonlySet<string>;
+    folderMeta: Map<string, FolderMeta>;
+    sharedFolderMeta?: Map<string, FolderMeta>;
+    navigation: ResolvedConfig["navigation"];
+    i18n?: ResolvedI18nConfig;
+    versions?: ResolvedVersionsConfig;
+}
+/** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
+export declare const buildContentGraph: (pages: PageRecord[], options: BuildContentGraphOptions) => ContentGraph;
+export {};

package/dist/types/core/heading-markers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Trailing heading markers, matching Fumadocs' syntax so migrated content works
+ * verbatim: `## Heading [#custom-id]` pins the anchor id, `## Heading [!toc]`
+ * keeps the heading on the page but out of the table of contents, and
+ * `## Heading [toc]` shows it only in the table of contents. Markers chain in
+ * any order (`## Heading [toc] [#id]`). The `{#id}` pin of Pandoc, kramdown,
+ * and Markdown-based specification toolchains is accepted as an equivalent of
+ * `[#id]` — in `.md` verbatim, in `.mdx` only as the escape `\{#id\}` (a bare
+ * `{…}` there is a JSX expression; the scan-time scanner reports one as
+ * `BLUME_MDX_CURLY_ANCHOR`). Both pipelines resolve escapes before parsing
+ * markers, so the escaped and bare spellings reach this parser identically.
+ *
+ * Both heading pipelines share this parser — the render-time hast plugin
+ * (`markdown/heading-anchors.ts`) and the scan-time source scanner
+ * (`core/sources/normalize.ts`) — so the rendered `id`, the TOC entry, and the
+ * anchor index `blume validate` checks against always agree.
+ */
+import type GithubSlugger from "github-slugger";
+/**
+ * Frontmatter key carrying the slugs of `[!toc]` headings out of a render. The
+ * hast plugin pushes onto it and the generated page template reads it back via
+ * `remarkPluginFrontmatter` to filter the TOC.
+ */
+export declare const TOC_HIDDEN_KEY = "__blumeTocHidden";
+/**
+ * Register a pinned `[#id]` with the document slugger, the way
+ * `GithubSlugger#slug` registers the slugs it returns — so a later heading
+ * whose auto-slug collides disambiguates (`setup` → `setup-1`) instead of
+ * silently duplicating the anchor id. An id that is already taken is left
+ * untouched (the pin still uses it verbatim; duplicate pins are the author's
+ * explicit choice).
+ */
+export declare const occupySlug: (slugger: GithubSlugger, id: string) => void;
+export interface HeadingMarkers {
+    /** Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never re-slugged). */
+    id?: string;
+    /** The heading text with every trailing marker stripped. */
+    text: string;
+    /** `[!toc]` hides the heading from the TOC; `[toc]` shows it only there. */
+    toc?: "hide" | "only";
+}
+/**
+ * Split trailing markers off a heading's text. Only markers at the very end of
+ * the heading count (mid-text brackets are ordinary prose); when a marker kind
+ * repeats, the last one written wins.
+ *
+ * `isRefDefined` reports whether a link-reference definition exists for a
+ * bracket's label (`toc`, `!toc`, `#id`): a defined bracket is a CommonMark
+ * shortcut link, not a marker — the renderer sees a resolved `<a>` element
+ * there and strips nothing at or before it, so the parse stops the same way.
+ * The render-time hast plugin never passes it (resolved links are already
+ * elements by the time it runs); the raw-source scanner does.
+ */
+export declare const parseHeadingMarkers: (text: string, isRefDefined?: (label: string) => boolean) => HeadingMarkers;

package/dist/types/core/i18n-ui.d.ts

@@ -49,10 +49,11 @@ declare const uiStringsObject: z.ZodObject<{
     }, z.core.$strip>>;
     changelog: z.ZodPrefault<z.ZodObject<{
         description: z.ZodDefault<z.ZodString>;
-        showReleases: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     content: z.ZodPrefault<z.ZodObject<{
+        copyColor: z.ZodDefault<z.ZodString>;
+        copyPrompt: z.ZodDefault<z.ZodString>;
         diagramError: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     feedback: z.ZodPrefault<z.ZodObject<{
@@ -73,6 +74,7 @@ declare const uiStringsObject: z.ZodObject<{
         featured: z.ZodDefault<z.ZodString>;
         githubRepository: z.ZodDefault<z.ZodString>;
         navigation: z.ZodDefault<z.ZodString>;
+        opensInNewTab: z.ZodDefault<z.ZodString>;
         primary: z.ZodDefault<z.ZodString>;
         sections: z.ZodDefault<z.ZodString>;
         toggleNavigation: z.ZodDefault<z.ZodString>;
@@ -163,10 +165,11 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
     }, z.core.$strip>>;
     changelog: z.ZodPrefault<z.ZodObject<{
         description: z.ZodDefault<z.ZodString>;
-        showReleases: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     content: z.ZodPrefault<z.ZodObject<{
+        copyColor: z.ZodDefault<z.ZodString>;
+        copyPrompt: z.ZodDefault<z.ZodString>;
         diagramError: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     feedback: z.ZodPrefault<z.ZodObject<{
@@ -187,6 +190,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
         featured: z.ZodDefault<z.ZodString>;
         githubRepository: z.ZodDefault<z.ZodString>;
         navigation: z.ZodDefault<z.ZodString>;
+        opensInNewTab: z.ZodDefault<z.ZodString>;
         primary: z.ZodDefault<z.ZodString>;
         sections: z.ZodDefault<z.ZodString>;
         toggleNavigation: z.ZodDefault<z.ZodString>;

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

@@ -0,0 +1,87 @@
+import type { ResolvedConfig, ResolvedI18nConfig, ResolvedVersionsConfig } from "./schema.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+/** True when the project opts into i18n. */
+export declare const i18nEnabled: (config: ResolvedConfig) => config is ResolvedConfig & {
+    i18n: ResolvedI18nConfig;
+};
+/** All configured locale codes, default first as authored. */
+export declare const localeCodes: (i18n: ResolvedI18nConfig) => string[];
+/** Text direction for a locale (`ltr` when unknown). */
+export declare const localeDir: (code: string, i18n: ResolvedI18nConfig) => "ltr" | "rtl";
+/**
+ * The locale a missing translation falls back to: `fallbackLocale` when set,
+ * the default locale when `fallbackLocale` is omitted, or `null` (disabled)
+ * when explicitly set to `null`.
+ */
+export declare const resolveFallbackLocale: (i18n: ResolvedI18nConfig) => string | null;
+/**
+ * The slice of the i18n settings URL routing reads. `ResolvedI18nConfig` and
+ * the `blume:data` runtime shape both satisfy it, so route helpers serve the
+ * Node-side graph and the rendered page alike.
+ */
+export interface LocaleRouting {
+    defaultLocale: string;
+    hideDefaultLocalePrefix: boolean;
+    locales: {
+        code: string;
+    }[];
+}
+/** URL prefix for a locale: `""` for the hidden default, else `/<code>`. */
+export declare const localePrefix: (code: string, i18n: LocaleRouting) => string;
+/**
+ * Prefix a locale-agnostic route (e.g. `/guides/x` or `/`) with its locale.
+ * `/` becomes `/fr` (or stays `/` for the hidden default).
+ */
+export declare const localizeRoute: (logicalRoute: string, code: string, i18n: LocaleRouting) => string;
+/**
+ * Localize a configured link target the way header tabs are: a root-relative
+ * internal path (`/`, `/docs`) moves into `code`'s prefix, and anything else —
+ * an absolute URL, a fragment, a relative path — passes through. `//host/path`
+ * is protocol-relative, an external URL that happens to start with a slash, so
+ * it must not pick up a locale prefix (`withBasePath` draws the same line).
+ * With no i18n (`null`) the path is returned as-is.
+ */
+export declare const localizeInternalPath: (path: string, code: string, i18n: LocaleRouting | null) => string;
+/**
+ * Detect a leading non-default locale directory in a path's segments. The
+ * default locale lives at the content root, so only non-default codes are
+ * matched as a leading segment. Returns the resolved locale and the remaining
+ * (locale-stripped) segments.
+ */
+export declare const detectLocale: (parts: string[], i18n: ResolvedI18nConfig) => {
+    locale: string;
+    rest: string[];
+};
+/**
+ * Resolve where a content file lives across locales, by parser:
+ * - `dir`: a leading locale directory (`fr/page.mdx`)
+ * - `dot`: a filename suffix (`page.fr.mdx`)
+ *
+ * A `.$.` infix (e.g. `changelog.$.mdx`) marks a shared, locale-agnostic file
+ * that is materialized into every configured locale. Returns the locale-stripped
+ * path (used for nav grouping) and the locale codes the file maps to (one for a
+ * normal file, all locales for a shared one).
+ */
+export declare const localePlacement: (rel: string, ext: string, i18n: ResolvedI18nConfig) => {
+    locales: string[];
+    navPath: string;
+};
+/**
+ * The inverse of {@link localePlacement}: where a default-locale file's
+ * translation into `locale` lives, by parser:
+ * - `dir`: a leading locale directory (`guides/x.mdx` → `fr/guides/x.mdx`)
+ * - `dot`: a filename suffix (`guides/x.mdx` → `guides/x.fr.mdx`)
+ *
+ * Under `dot`, a source authored with an explicit default-locale suffix
+ * (`x.en.mdx`) swaps it for the target's (`x.fr.mdx`) — same case-insensitive
+ * last-dot-inside-filename logic as `localePlacement`, so both spellings of a
+ * default-locale file resolve to one canonical target.
+ */
+export declare const localeTargetPath: (rel: string, ext: string, locale: string, i18n: ResolvedI18nConfig) => string;
+/**
+ * Warn about top-level content folders that look like a locale (a code Blume
+ * recognizes) but aren't declared in `i18n.locales`. Without this they're
+ * silently treated as default-locale content under a `/<code>/…` route, which
+ * is almost never intended — usually a translation that wasn't registered.
+ */
+export declare const i18nDiagnostics: (pages: PageRecord[], i18n: ResolvedI18nConfig, versions?: ResolvedVersionsConfig) => Diagnostic[];