blume 2.1.2 → 2.2.0

package/dist/types/components/openapi/helpers.d.ts

@@ -83,7 +83,10 @@ export declare const soleAllOfMember: (schema: SchemaLike) => SchemaLike | undef
 /**
  * Resolve one level of `$ref` against the document's component schemas. A
  * single-member `allOf` wrapper resolves like its member, with the wrapper's
- * own keywords on top: its `description` is about this field.
+ * own keywords on top: its `description` is about this field. So does a
+ * `$ref` with keywords beside it, which OpenAPI 3.1 allows and .NET writes
+ * for every enum-typed property: the `description` beside the `$ref` is the
+ * property's, the referenced one the type's.
  */
 export declare const resolveSchema: (schemas: Record<string, SchemaLike>, schema?: SchemaLike) => SchemaLike;
 /**
@@ -121,16 +124,30 @@ export interface ObjectPropertySet {
  * the merged required set.
  */
 export declare const objectProperties: (schema: SchemaLike, schemas: Record<string, SchemaLike>) => ObjectPropertySet;
+/** Which way an example travels: to the API, or back from it. */
+export type ExampleDirection = "request" | "response";
+/**
+ * An example value with the properties that don't travel `direction` left
+ * out, at every depth its schema describes: `readOnly` ones from a request,
+ * which the server sets, and `writeOnly` ones from a response, which it
+ * never returns. openapi-sampler skips those only in the values it builds; a
+ * declared example (a model's `example`, which TypeSpec writes, or a media
+ * type's) keeps them, so a request sample would send the model's `id`. A
+ * property the schema doesn't describe stays as written.
+ */
+export declare const forDirection: (value: SpecValue, schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction: ExampleDirection) => SpecValue;
 /**
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
- * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * and circular `$ref` chains — which keeping refs intact allows — terminate
- * safely. A request sample skips `readOnly` fields (a server-generated field
- * has no place in one); a response sample skips `writeOnly` fields (a
- * password the client sends never comes back) and keeps the `readOnly` ones.
+ * win, a value beside a `$ref` included, formats produce realistic
+ * placeholders (`email`, `uuid`, `date-time`), and circular `$ref` chains —
+ * which keeping refs intact allows — terminate safely. A request sample
+ * leaves out `readOnly` fields (a server-generated field has no place in
+ * one); a response sample leaves out `writeOnly` fields (a password the
+ * client sends never comes back) and keeps the `readOnly` ones. That holds
+ * inside a declared value the sampler copies too (see {@link forDirection}).
  */
-export declare const exampleValue: (schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction?: "request" | "response") => SpecValue;
+export declare const exampleValue: (schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction?: ExampleDirection) => SpecValue;
 /** Where an author can declare an example: a parameter or a media type. */
 export interface ExampleCarrier {
     example?: SpecValue;
@@ -146,13 +163,38 @@ export interface ExampleCarrier {
  * declared.
  */
 export declare const declaredExample: (carrier: ExampleCarrier, components?: ComponentsLike) => SpecValue;
+/** A media type: the schema of a body and the examples it declares. */
+export type MediaLike = ExampleCarrier & {
+    schema?: SchemaLike;
+};
+/**
+ * A media type's example for a body travelling `direction`: the declared
+ * one, else a sample built from its schema, with the properties that don't
+ * travel that way left out (see {@link forDirection}).
+ */
+export declare const mediaExample: (media: MediaLike, schemas: Record<string, SchemaLike>, direction: ExampleDirection, components?: ComponentsLike) => SpecValue;
 /**
  * A response media type's example for the Response panel: the declared one,
  * else a sample built for the response direction (`readOnly` kept,
- * `writeOnly` skipped).
+ * `writeOnly` left out).
  */
-export declare const responseExample: (media: ExampleCarrier & {
-    schema?: SchemaLike;
-}, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => SpecValue;
+export declare const responseExample: (media: MediaLike, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => SpecValue;
+/** One of a media type's named examples, as a tab or the Markdown copy shows it. */
+export interface NamedExample {
+    /** The example's key in the `examples` map. */
+    key: string;
+    /** Its `summary`, else its key. */
+    label: string;
+    value: SpecValue;
+}
+/**
+ * Every example a media type's `examples` map names, in order, `$ref`s to
+ * `#/components/examples` resolved, each labeled by its `summary` or else
+ * its key, with the properties that don't travel `direction` left out. Empty
+ * unless the map names two or more: Scalar's upgrade files a 3.0 `example`
+ * as the one entry `default`, which is no name to show, and a lone example
+ * is the one {@link mediaExample} already gives.
+ */
+export declare const namedExamples: (media: MediaLike, schemas: Record<string, SchemaLike>, direction: ExampleDirection, components?: ComponentsLike) => NamedExample[];
 /** Pretty-print a JSON value for an example/code block. */
 export declare const toJson: <T>(value: T) => string;

package/dist/types/components/openapi/snippets.d.ts

@@ -53,8 +53,14 @@ export interface SampleLanguageInfo {
 export declare const sampleLanguageInfo: (raw: string) => SampleLanguageInfo | null;
 /** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
 export declare const DEFAULT_SAMPLE_LANGUAGES: string[];
+/**
+ * The configured ids Blume generates no sample for, as written: the ones
+ * {@link sampleLanguages} drops, which the reference source warns about.
+ */
+export declare const unknownSampleLanguages: (ids: string[] | false) => string[];
 /**
  * The sample languages to render, resolved from config ids (unknown ids
- * dropped), in order. `false` and an empty list both render none.
+ * dropped, with a warning from the reference source), in order. `false` and
+ * an empty list both render none.
  */
 export declare const sampleLanguages: (ids: string[] | false) => SampleLanguage[];

package/dist/types/core/alert-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+/**
+ * Warn about GitHub alerts (`> [!NOTE]`) in an `.md` entry, which renders
+ * them as plain quotes that show the marker as text: alerts become callouts
+ * only in `.mdx`, where Blume renders components (see
+ * `markdown/github-alerts.ts`). Lines point into the file the author wrote, a
+ * partial's own file for an alert an `<include>` brought in.
+ */
+export declare const alertDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/builtin-tags.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The MDX component tags Blume ships (the keys of the catch-all's component map,
+ * plus composed sub-parts like `Color.Item`/`Tree.File`). Used by the
+ * missing-component diagnostic to tell an unknown `<Tag>` from a built-in. Keep
+ * in sync with the component map in `astro/templates.ts`.
+ */
+export declare const BUILTIN_MDX_TAGS: Set<string>;
+/**
+ * The props each built-in that shows its children takes, keyed by MDX tag. A
+ * childless use with any other prop renders without the content its author
+ * meant it to carry (VitePress writes `<Badge type="tip" text="beta" />`, and
+ * Blume's Badge shows only its children), which the unknown-prop diagnostic
+ * reports. Each list is the component's own `Props` (or what it reads from
+ * `Astro.props`); a test checks them against the `.astro` files.
+ */
+export declare const BUILTIN_CHILD_PROPS: ReadonlyMap<string, readonly string[]>;

package/dist/types/core/changelog-list.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The policy the changelog index lists by, shared by the surfaces that build
+ * it: the `<Changelog />` component (reading Astro collection entries) and
+ * `ai/changelog-markdown.ts` (reading the build-time page graph for the
+ * `/changelog.md` mirror and MCP `get_page`).
+ *
+ * The data sources genuinely differ — a collection entry on the Astro side, a
+ * `PageRecord` on the Node side — so what lives here is the *decisions*, not
+ * the access: which date a row carries, what order rows come in, and how they
+ * fall into year groups. Keeping them in one place is what stops the rendered
+ * page and the Markdown an agent reads from drifting apart.
+ */
+/**
+ * A changelog entry's date, from `date` or the `changelog.date` it may live
+ * under instead. Front matter hands either a `Date` (an unquoted YAML date) or
+ * a string, and an unparseable value is treated as no date at all rather than
+ * failing the build — a malformed date costs the row its stamp and its year
+ * group, not the page.
+ */
+export declare const parseChangelogDate: (value: Date | string | null | undefined) => Date | null;
+/**
+ * Newest first. An undated entry sorts as the epoch, so undated rows collect
+ * at the end of the list (and, through {@link groupChangelogYears}, into a
+ * final group with no year label).
+ */
+export declare const compareChangelogDates: (a: Date | null, b: Date | null) => number;
+/** One year's run of rows. `year` is `null` for the undated group. */
+export interface ChangelogYearGroup<T> {
+    items: T[];
+    year: string | null;
+}
+/**
+ * Consecutive rows sharing a year, in list order, so the index reads as a year
+ * rail beside its rows. Runs are consecutive rather than keyed, which matters
+ * only for a list that isn't sorted by date: such a list keeps its order and
+ * repeats the year heading instead of silently regrouping around it.
+ *
+ * `yearOf` returns the label the surface wants — a locale-formatted year on the
+ * rendered page, a plain number in Markdown — or `null` for an undated row.
+ */
+export declare const groupChangelogYears: <T>(items: T[], yearOf: (item: T) => string | null) => ChangelogYearGroup<T>[];
+/**
+ * Make each row's anchor unique. Repeated labels slug to the same id (two
+ * entries with neither a title nor a version both fall back to "update"), so
+ * the later ones take a `-2`, `-3`, … suffix and the first keeps the plain
+ * slug — every row ends up with its own hash anchor.
+ */
+export declare const uniqueAnchorIds: (ids: string[]) => string[];

package/dist/types/core/closest-match.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The candidate closest to `name`, when it's close enough to be the likely
+ * intent: at most two edits away, and fewer edits than half the candidate's
+ * length, so a short typo doesn't "suggest" an unrelated short word.
+ */
+export declare const closestMatch: (name: string, candidates: readonly string[]) => string | undefined;

package/dist/types/core/code-fence-diagnostics.d.ts

@@ -0,0 +1,18 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+/**
+ * Warn about code fences that don't render as their author meant:
+ *
+ * - `BLUME_UNKNOWN_CODE_LANGUAGE`: a language Shiki doesn't know, so the block
+ *   renders as plain text. Shiki itself only logs a console line naming the
+ *   language, with no page or line.
+ * - `BLUME_CODE_FENCE_OPTION`: an option another docs tool reads, like MkDocs'
+ *   `hl_lines="2 3"`, Docusaurus' `showLineNumbers`, Mintlify's `lines`, or
+ *   rustdoc's `no_run`, which Blume ignores. None of them becomes part of the
+ *   block's title. The suggestion gives the Blume spelling, or says to remove
+ *   an option Blume has no use for.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * fence an `<include>` brought in.
+ */
+export declare const codeFenceDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/code-fences.d.ts

@@ -1,11 +1,18 @@
-/** The open fence's delimiter char and run length, or null outside one. */
+/**
+ * The open fence's delimiter char, its run length, and the block-quote depth
+ * it opened at, or null outside one.
+ */
 export type FenceState = {
     delimiter: "`" | "~";
     length: number;
+    quotes: number;
 } | null;
 /**
  * Advance the fenced-code state for one line: an opening fence records its
  * delimiter and run length, only a bare run of the same character at least as
  * long closes it (CommonMark), and any other line leaves the state untouched.
+ * A fence inside block quotes is read past the quote markers it opened under,
+ * and a line without them ends the quote, and the fence with it: code takes
+ * no lazy continuation lines (CommonMark).
  */
 export declare const nextFenceState: (line: string, fence: FenceState) => FenceState;

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

@@ -147,7 +147,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[];

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

@@ -10,8 +10,15 @@ 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 declare const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
 /**
  * The endpoint param a colocated image is served under: its project-relative
@@ -21,29 +28,20 @@ export declare const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
  */
 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.
+ * 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 declare const isRelativeImageTarget: (target: string) => boolean;
+export declare const contentAssetUrl: (param: string, deployBase?: string) => string;
 /**
- * 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
+ * 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 declare const rewriteRelativeImages: (options: {
+export declare const rewriteRelativeAssets: (options: {
     source: string;
     sourcePath: string;
     projectRoot: string;
@@ -51,7 +49,7 @@ export declare const rewriteRelativeImages: (options: {
     register?: (param: string, absPath: string) => void;
 }) => string;
 /**
- * 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

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

@@ -10,6 +10,20 @@ export declare const createDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
 export declare const resolveDocsUrl: (code: string) => string | undefined;
 /** Fill in `docsUrl` from the code map where a diagnostic doesn't set its own. */
 export declare const enrichDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
+/**
+ * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`,
+ * `["redirects", 2, "status"]`) in the raw config / frontmatter text. Narrows
+ * segment by segment: a key is found among its parent's own entries (or, where
+ * there are no brackets, in the parent's indented lines), an index picks that
+ * element of an array literal. A segment that isn't there — a missing key —
+ * stops the walk at its parent, so the position never escapes into a sibling.
+ * Returns 1-based line/column, or undefined when not even the first segment
+ * matches.
+ */
+export declare const locatePath: (source: string, path: readonly (string | number)[]) => {
+    column: number;
+    line: number;
+} | undefined;
 /**
  * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
  * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the

package/dist/types/core/directive-diagnostics.d.ts

@@ -1,12 +1,26 @@
 import type { SourceEntry } from "./sources/types.ts";
 import type { Diagnostic } from "./types.ts";
 /**
- * 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.
+ * Warn about the `:::` directives in an entry that don't render as their
+ * author meant. In `.mdx`:
+ *
+ * - `BLUME_UNKNOWN_DIRECTIVE`: a `:::name` container 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.
+ * - `BLUME_DIRECTIVE_OPENING_TEXT`: a callout opener with text after its
+ *   name, which the page drops (`:::tip Some title`).
+ * - `BLUME_DIRECTIVE_CLOSING_TEXT`: a closing fence with text after it, which
+ *   the page drops (`::: card` inside a `:::warning`).
+ * - `BLUME_DIRECTIVE_SPACED_NAME`: a spaced callout opener (`::: tip`), which
+ *   the page shows as text.
+ *
+ * In `.md`, which renders no directives:
+ *
+ * - `BLUME_MD_DIRECTIVE`: a `:::name` opener, which the page shows as text.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * directive an `<include>` brought in.
  */
-export declare const unknownDirectiveDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];
+export declare const directiveDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/former-routes.d.ts

@@ -0,0 +1,14 @@
+import type { ResolvedConfig } from "./schema.ts";
+import type { PageRecord } from "./types.ts";
+type Redirect = ResolvedConfig["redirects"][number];
+/**
+ * Redirects from the routes an earlier Blume published pages at
+ * (`PageRecord.formerRoute`) to where they publish now, so a date-named
+ * page's old URL keeps working. None is added where the old URL is still
+ * served (another page, or a custom page, lives there now), where an authored
+ * redirect already starts, or where two pages once resolved to it: that was a
+ * duplicate route, which failed the build, so the URL never served either.
+ * Both ends are written base-less, like authored redirects.
+ */
+export declare const formerRouteRedirects: (pages: readonly PageRecord[], served: ReadonlySet<string>, config: Pick<ResolvedConfig, "basePath" | "redirects">) => Redirect[];
+export {};

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

@@ -1,10 +1,11 @@
 /**
  * Repository URL derivation for `config.github`.
  *
- * Every repo-derived link — the header mark, per-page edit links, the agent
- * manifest's `repository` — is built from `host`, which defaults to github.com
- * but accepts a GitHub Enterprise origin so self-hosted and data-resident
- * installations get working links instead of ones pointing at the public site.
+ * Every repo-derived link — the footer's repository link, per-page edit links,
+ * the agent manifest's `repository` — is built from `host`, which defaults to
+ * github.com but accepts a GitHub Enterprise origin so self-hosted and
+ * data-resident installations get working links instead of ones pointing at the
+ * public site.
  *
  * The REST base is derived from the host unless `api` is set explicitly, since
  * the two Enterprise flavors expose it differently: Enterprise Cloud with data

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

@@ -13,7 +13,9 @@
  * 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.
+ * anchor index `blume validate` checks against always agree. Both also escape
+ * a pinned id's punctuation before they parse (`core/pinned-ids.ts`), so
+ * smart punctuation never rewrites the id an author pinned.
  */
 import type GithubSlugger from "github-slugger";
 /**
@@ -22,6 +24,64 @@ import type GithubSlugger from "github-slugger";
  * `remarkPluginFrontmatter` to filter the TOC.
  */
 export declare const TOC_HIDDEN_KEY = "__blumeTocHidden";
+/**
+ * Frontmatter key carrying TOC text out of a render, keyed by slug, for the
+ * headings whose TOC entry must read differently from the heading's text
+ * content: a heading holding a `<Badge>` lists without the badge's text. The
+ * page template reads it back the way it reads {@link TOC_HIDDEN_KEY}.
+ */
+export declare const TOC_TEXT_KEY = "__blumeTocText";
+/**
+ * A heading's auto-generated anchor id, registered with the document slugger.
+ * The text is trimmed first: a heading that opens or ends with something that
+ * has no text (an inline component, an image, raw HTML) would otherwise slug
+ * that edge whitespace into a leading or trailing dash. A slug can still end
+ * in dashes when the slugger drops a symbol after a space (`Features ✨`);
+ * those go too, so no id ends in a dash.
+ */
+export declare const headingSlug: (slugger: GithubSlugger, text: string) => string;
+/**
+ * A heading's text with its badges taken out. `pieces` is the heading's text
+ * in order, with `null` where a badge stood; a badge between two words
+ * leaves one space, not the two around it (`Install <Badge>beta</Badge> now`
+ * reads `Install now`).
+ */
+export declare const joinHeadingText: (pieces: readonly (string | null)[]) => string;
+/**
+ * How a raw HTML node in a heading reads for its anchor: a `<Badge>` tag that
+ * opens or closes a run of badge text (a self-closing one is a badge with no
+ * text), the opening tag of an `<a>` (`target` its `id`, else its `name`),
+ * the `</a>` that closes one, or none of these.
+ */
+export type RawHeadingTag = {
+    kind: "anchor-close";
+} | {
+    kind: "anchor-open";
+    selfClosing: boolean;
+    target?: string;
+} | {
+    kind: "badge";
+    selfClosing: boolean;
+    closing: boolean;
+} | {
+    kind: "other";
+};
+/** Classify a raw HTML node in a heading — see {@link RawHeadingTag}. */
+export declare const rawHeadingTag: (value: string) => RawHeadingTag;
+/**
+ * A JSX attribute: a name with a string value or an `{expression}` one, or a
+ * `{...spread}` (no name).
+ */
+export interface JsxAttribute {
+    name?: string;
+    type: string;
+    value?: string | {
+        type: string;
+        value?: string;
+    } | null;
+}
+/** A JSX `<a>`'s own fragment target: its string `id`, else its `name`. */
+export declare const jsxAnchorTarget: (attributes: readonly JsxAttribute[]) => string | undefined;
 /**
  * Register a pinned `[#id]` with the document slugger, the way
  * `GithubSlugger#slug` registers the slugs it returns — so a later heading
@@ -32,7 +92,10 @@ export declare const TOC_HIDDEN_KEY = "__blumeTocHidden";
  */
 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). */
+    /**
+     * Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never
+     * re-slugged, and never smart-punctuated: see `core/pinned-ids.ts`).
+     */
     id?: string;
     /** The heading text with every trailing marker stripped. */
     text: string;

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

@@ -0,0 +1,3 @@
+import type { ContentGraph, PageRecord } from "./types.ts";
+/** Whether a page is hidden from the navigation (see the module comment). */
+export declare const isHiddenPage: (page: PageRecord, graph: ContentGraph) => boolean;

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

@@ -1,3 +1,4 @@
+import type { LinkDefinition } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
 /**
  * Cheap pre-filter so include-free content (the overwhelmingly common case)
@@ -116,6 +117,28 @@ export declare const expandIncludes: (body: string, options: {
     /** Raw-file line of `body`'s first line, minus one (default `0`). */
     lineOffset?: number;
 }) => Promise<IncludeExpansion>;
+/**
+ * `text` with each of `definitions` it doesn't define itself appended, so a
+ * reference in it resolves through a definition written elsewhere in the
+ * page (CommonMark definitions are document-wide). Definitions render
+ * nothing; they're left off a text that ends in an open code fence, where
+ * they'd show as code.
+ */
+export declare const withDefinitions: (text: string, definitions: readonly LinkDefinition[]) => string;
+/**
+ * A page's source with the link-reference definitions its included partials
+ * write appended, for the render to parse. Each partial is spliced after the
+ * page is parsed (see `markdown/include.ts`), so a reference in the page
+ * (`[PEP 508]`) to a definition in a partial would otherwise stay text,
+ * though an include reads as if written inline. The definitions come from
+ * the expansion every surface shares, so a partial's definition of a file
+ * beside it is already rebased onto the page. The page's own definition of
+ * a label wins.
+ */
+export declare const withIncludedDefinitions: (body: string, options: {
+    sourcePath: string;
+    contentRoot?: string;
+}) => Promise<string>;
 /**
  * Resolve one include statement to its fully-expanded markdown text — the
  * render plugin's entry point (it finds the statements as AST nodes and only

package/dist/types/core/last-modified.d.ts

@@ -4,13 +4,23 @@ export interface ResolvedLastModified {
     enabled: boolean;
     source: "git" | "frontmatter";
 }
+export declare const gitEnv: () => NodeJS.ProcessEnv;
 /** Normalize the `lastModified` config (`false | "git" | "frontmatter"`) into `{ enabled, source }`. */
 export declare const resolveLastModifiedConfig: (value: false | "git" | "frontmatter") => ResolvedLastModified;
 /**
- * Parse `git log --format=%x00%cI --name-only` output into a map of
- * repo-root-relative path → most recent committer ISO date. Each commit emits a
- * NUL-prefixed date line followed by the paths it touched; since git logs
- * newest-first, the first date seen for a path wins. Blank lines are ignored.
+ * Parse `git log --format=%x00%cI --name-status -M100%` output into a map of
+ * repo-root-relative path → the committer ISO date of the newest commit that
+ * changed the file. Each commit emits a NUL-prefixed date line followed by a
+ * status line per path it touched (`M\tpath`, `R100\told\tnew`); since git
+ * logs newest-first, the first date seen for a path wins. Blank lines are
+ * ignored.
+ *
+ * A rename (`-M100%` reports only exact ones, where the content is unchanged)
+ * follows the file the way `git log --follow` does for one path: it dates
+ * nothing itself, and the older commits that name the old path date the file
+ * under its current name, so renaming `page.md` to `page.mdx` keeps the page's
+ * date. A file whose visible history starts at a rename (a shallow clone cut
+ * off the commits before it) takes the rename's date.
  */
 export declare const parseGitLog: (output: string) => Map<string, string>;
 /**
@@ -33,8 +43,10 @@ export declare const gitRepositoryRoot: (root: string) => string | null;
 /**
  * Resolve each source file's last-modified date from git history, keyed by
  * absolute source path. Runs a single `git log` over the given content roots
- * (each local source's own root, which may diverge from `content.root`)
- * and maps repo-root-relative paths back to the given absolute paths
+ * (each local source's own root, which may diverge from `content.root`),
+ * following renames within them (see `parseGitLog`; a file moved in from
+ * outside every root dates from the move), and maps repo-root-relative paths
+ * back to the given absolute paths
  * (monorepo-safe via `rev-parse --show-toplevel`). Returns an empty map if git
  * is unavailable or the project isn't a repo — the feature then simply shows
  * no dates.