nimbus-docs 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,9 +1,9 @@
+import { a as SeverityConfig, r as RuleCode } from "./diagnostic-DZf0z79l.js";
 import { BadgeVariant, Breadcrumb, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, SearchProvider, SearchResult, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig } from "./types.js";
 import mdx from "@astrojs/mdx";
 import * as astro_content0 from "astro:content";
 import { CollectionEntry } from "astro:content";
 import { AstroGlobal, AstroIntegration, GetStaticPaths } from "astro";
-import { ShikiTransformer } from "shiki";
 
 //#region src/_internal/content.d.ts
 /**
@@ -63,6 +63,24 @@ interface MarkdownEntry {
  */
 declare function renderEntryAsMarkdown(entry: MarkdownEntry, options?: RenderEntryAsMarkdownOptions): string;
 //#endregion
+//#region src/lint/config.d.ts
+/** A single rule's config: a bare severity, or `[severity, options]`. */
+type RuleSetting = SeverityConfig | [SeverityConfig, Record<string, unknown>];
+/** The `rules` option: code → setting. An empty object = all rules on. */
+type RulesConfig = Partial<Record<RuleCode, RuleSetting>>;
+/** Per-collection lint config — currently just `rules` overrides. */
+interface CollectionLintConfig {
+  rules?: RulesConfig;
+}
+/**
+ * The `collections` option: collection name → per-collection overrides.
+ * Each entry's `rules` shallow-merges over the top-level `rules` for
+ * files in that collection. Per-rule resolution precedence is:
+ * top-level defaults → per-collection → per-file `nimbusDisableRules`
+ * → per-line inline disable. Each layer narrows scope.
+ */
+type CollectionsConfig = Record<string, CollectionLintConfig>;
+//#endregion
 //#region src/integration.d.ts
 interface NimbusIntegrationOptions {
   /** MDX options forwarded to `@astrojs/mdx`. */
@@ -93,9 +111,949 @@ interface NimbusIntegrationOptions {
     contentDirs?: string[];
     skip?: (filePath: string) => boolean;
   };
+  /**
+   * Authoring-lint severity overrides for `nimbus-docs lint`. Maps a rule
+   * code to `"error" | "warn" | "off"` or a `[severity, options]` tuple.
+   * Build validators are rejected here — they have no severity knob.
+   * Omitted = every authoring rule on at `error`.
+   *
+   * These are materialized to `.nimbus/lint.json` at config setup so the
+   * standalone `nimbus-docs lint` CLI can read them. The build itself is
+   * never gated on authoring rules.
+   */
+  rules?: RulesConfig;
+  /**
+   * Per-collection overrides. Each entry's `rules` block shallow-merges
+   * over the top-level `rules` for files in that collection — same shape,
+   * same validation, same build-validator carve-out (build validators
+   * stay global, they can't be configured per-collection).
+   *
+   * @example
+   * collections: {
+   *   partials: { rules: { "nimbus/single-h1": "off", "nimbus/heading-hierarchy": "off" } },
+   * }
+   */
+  collections?: CollectionsConfig;
 }
 declare function nimbus(rawConfig: NimbusConfig, options?: NimbusIntegrationOptions): AstroIntegration;
 //#endregion
+//#region ../../node_modules/.pnpm/@types+unist@3.0.3/node_modules/@types/unist/index.d.ts
+// ## Interfaces
+/**
+ * Info associated with nodes by the ecosystem.
+ *
+ * This space is guaranteed to never be specified by unist or specifications
+ * implementing unist.
+ * But you can use it in utilities and plugins to store data.
+ *
+ * This type can be augmented to register custom data.
+ * For example:
+ *
+ * ```ts
+ * declare module 'unist' {
+ *   interface Data {
+ *     // `someNode.data.myId` is typed as `number | undefined`
+ *     myId?: number | undefined
+ *   }
+ * }
+ * ```
+ */
+interface Data$1 {}
+/**
+ * One place in a source file.
+ */
+interface Point {
+  /**
+   * Line in a source file (1-indexed integer).
+   */
+  line: number;
+  /**
+   * Column in a source file (1-indexed integer).
+   */
+  column: number;
+  /**
+   * Character in a source file (0-indexed integer).
+   */
+  offset?: number | undefined;
+}
+/**
+ * Position of a node in a source document.
+ *
+ * A position is a range between two points.
+ */
+interface Position$1 {
+  /**
+   * Place of the first character of the parsed source region.
+   */
+  start: Point;
+  /**
+   * Place of the first character after the parsed source region.
+   */
+  end: Point;
+}
+/**
+ * Abstract unist node.
+ *
+ * The syntactic unit in unist syntax trees are called nodes.
+ *
+ * This interface is supposed to be extended.
+ * If you can use {@link Literal} or {@link Parent}, you should.
+ * But for example in markdown, a `thematicBreak` (`***`), is neither literal
+ * nor parent, but still a node.
+ */
+interface Node$1 {
+  /**
+   * Node type.
+   */
+  type: string;
+  /**
+   * Info from the ecosystem.
+   */
+  data?: Data$1 | undefined;
+  /**
+   * Position of a node in a source document.
+   *
+   * Nodes that are generated (not in the original source document) must not
+   * have a position.
+   */
+  position?: Position$1 | undefined;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@types+hast@3.0.4/node_modules/@types/hast/index.d.ts
+// ## Interfaces
+/**
+ * Info associated with hast nodes by the ecosystem.
+ *
+ * This space is guaranteed to never be specified by unist or hast.
+ * But you can use it in utilities and plugins to store data.
+ *
+ * This type can be augmented to register custom data.
+ * For example:
+ *
+ * ```ts
+ * declare module 'hast' {
+ *   interface Data {
+ *     // `someNode.data.myId` is typed as `number | undefined`
+ *     myId?: number | undefined
+ *   }
+ * }
+ * ```
+ */
+interface Data extends Data$1 {}
+/**
+ * Info associated with an element.
+ */
+interface Properties {
+  [PropertyName: string]: boolean | number | string | null | undefined | Array<string | number>;
+}
+// ## Content maps
+/**
+ * Union of registered hast nodes that can occur in {@link Element}.
+ *
+ * To register mote custom hast nodes, add them to {@link ElementContentMap}.
+ * They will be automatically added here.
+ */
+type ElementContent = ElementContentMap[keyof ElementContentMap];
+/**
+ * Registry of all hast nodes that can occur as children of {@link Element}.
+ *
+ * For a union of all {@link Element} children, see {@link ElementContent}.
+ */
+interface ElementContentMap {
+  comment: Comment;
+  element: Element;
+  text: Text;
+}
+/**
+ * Union of registered hast nodes that can occur in {@link Root}.
+ *
+ * To register custom hast nodes, add them to {@link RootContentMap}.
+ * They will be automatically added here.
+ */
+type RootContent = RootContentMap[keyof RootContentMap];
+/**
+ * Registry of all hast nodes that can occur as children of {@link Root}.
+ *
+ * > 👉 **Note**: {@link Root} does not need to be an entire document.
+ * > it can also be a fragment.
+ *
+ * For a union of all {@link Root} children, see {@link RootContent}.
+ */
+interface RootContentMap {
+  comment: Comment;
+  doctype: Doctype;
+  element: Element;
+  text: Text;
+}
+// ## Abstract nodes
+/**
+ * Abstract hast node.
+ *
+ * This interface is supposed to be extended.
+ * If you can use {@link Literal} or {@link Parent}, you should.
+ * But for example in HTML, a `Doctype` is neither literal nor parent, but
+ * still a node.
+ *
+ * To register custom hast nodes, add them to {@link RootContentMap} and other
+ * places where relevant (such as {@link ElementContentMap}).
+ *
+ * For a union of all registered hast nodes, see {@link Nodes}.
+ */
+interface Node extends Node$1 {
+  /**
+   * Info from the ecosystem.
+   */
+  data?: Data | undefined;
+}
+/**
+ * Abstract hast node that contains the smallest possible value.
+ *
+ * This interface is supposed to be extended if you make custom hast nodes.
+ *
+ * For a union of all registered hast literals, see {@link Literals}.
+ */
+interface Literal extends Node {
+  /**
+   * Plain-text value.
+   */
+  value: string;
+}
+/**
+ * Abstract hast node that contains other hast nodes (*children*).
+ *
+ * This interface is supposed to be extended if you make custom hast nodes.
+ *
+ * For a union of all registered hast parents, see {@link Parents}.
+ */
+interface Parent extends Node {
+  /**
+   * List of children.
+   */
+  children: RootContent[];
+}
+// ## Concrete nodes
+/**
+ * HTML comment.
+ */
+interface Comment extends Literal {
+  /**
+   * Node type of HTML comments in hast.
+   */
+  type: "comment";
+  /**
+   * Data associated with the comment.
+   */
+  data?: CommentData | undefined;
+}
+/**
+ * Info associated with hast comments by the ecosystem.
+ */
+interface CommentData extends Data {}
+/**
+ * HTML document type.
+ */
+interface Doctype extends Node$1 {
+  /**
+   * Node type of HTML document types in hast.
+   */
+  type: "doctype";
+  /**
+   * Data associated with the doctype.
+   */
+  data?: DoctypeData | undefined;
+}
+/**
+ * Info associated with hast doctypes by the ecosystem.
+ */
+interface DoctypeData extends Data {}
+/**
+ * HTML element.
+ */
+interface Element extends Parent {
+  /**
+   * Node type of elements.
+   */
+  type: "element";
+  /**
+   * Tag name (such as `'body'`) of the element.
+   */
+  tagName: string;
+  /**
+   * Info associated with the element.
+   */
+  properties: Properties;
+  /**
+   * Children of element.
+   */
+  children: ElementContent[];
+  /**
+   * When the `tagName` field is `'template'`, a `content` field can be
+   * present.
+   */
+  content?: Root | undefined;
+  /**
+   * Data associated with the element.
+   */
+  data?: ElementData | undefined;
+}
+/**
+ * Info associated with hast elements by the ecosystem.
+ */
+interface ElementData extends Data {}
+/**
+ * Document fragment or a whole document.
+ *
+ * Should be used as the root of a tree and must not be used as a child.
+ *
+ * Can also be used as the value for the content field on a `'template'` element.
+ */
+interface Root extends Parent {
+  /**
+   * Node type of hast root.
+   */
+  type: "root";
+  /**
+   * Children of root.
+   */
+  children: RootContent[];
+  /**
+   * Data associated with the hast root.
+   */
+  data?: RootData | undefined;
+}
+/**
+ * Info associated with hast root nodes by the ecosystem.
+ */
+interface RootData extends Data {}
+/**
+ * HTML character data (plain text).
+ */
+interface Text extends Literal {
+  /**
+   * Node type of HTML character data (plain text) in hast.
+   */
+  type: "text";
+  /**
+   * Data associated with the text.
+   */
+  data?: TextData | undefined;
+}
+/**
+ * Info associated with hast texts by the ecosystem.
+ */
+interface TextData extends Data {}
+//#endregion
+//#region ../../node_modules/.pnpm/@shikijs+vscode-textmate@10.0.2/node_modules/@shikijs/vscode-textmate/dist/index.d.ts
+/**
+ * An expression language of ScopePathStr with a binary comma (to indicate alternatives) operator.
+ * Examples: `foo.bar boo.baz,quick quack`
+*/
+type ScopePattern = string;
+/**
+ * A TextMate theme.
+ */
+interface IRawTheme {
+  readonly name?: string;
+  readonly settings: IRawThemeSetting[];
+}
+/**
+ * A single theme setting.
+ */
+interface IRawThemeSetting {
+  readonly name?: string;
+  readonly scope?: ScopePattern | ScopePattern[];
+  readonly settings: {
+    readonly fontStyle?: string;
+    readonly foreground?: string;
+    readonly background?: string;
+  };
+}
+declare const enum FontStyle {
+  NotSet = -1,
+  None = 0,
+  Italic = 1,
+  Bold = 2,
+  Underline = 4,
+  Strikethrough = 8
+}
+/**
+ * **IMPORTANT** - Immutable!
+ */
+interface StateStack {
+  _stackElementBrand: void;
+  readonly depth: number;
+  clone(): StateStack;
+  equals(other: StateStack): boolean;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@shikijs+types@4.1.0/node_modules/@shikijs/types/dist/index.d.mts
+interface Nothing {}
+/**
+ * type StringLiteralUnion<'foo'> = 'foo' | string
+ * This has auto completion whereas `'foo' | string` doesn't
+ * Adapted from https://github.com/microsoft/TypeScript/issues/29729
+ */
+type StringLiteralUnion<T extends U, U = string> = T | (U & Nothing); //#endregion
+//#region src/engines.d.ts
+//#endregion
+//#region src/langs.d.ts
+type PlainTextLanguage = 'text' | 'plaintext' | 'txt' | 'plain';
+type AnsiLanguage = 'ansi';
+type SpecialLanguage = PlainTextLanguage | AnsiLanguage;
+//#endregion
+//#region src/decorations.d.ts
+interface DecorationOptions {
+  /**
+   * Custom decorations to wrap highlighted tokens with.
+   */
+  decorations?: DecorationItem[];
+}
+interface DecorationItem {
+  /**
+   * Start offset or position of the decoration.
+   */
+  start: OffsetOrPosition;
+  /**
+   * End offset or position of the decoration.
+   */
+  end: OffsetOrPosition;
+  /**
+   * Tag name of the element to create.
+   * @default 'span'
+   */
+  tagName?: string;
+  /**
+   * Properties of the element to create.
+   */
+  properties?: Element['properties'];
+  /**
+   * A custom function to transform the element after it has been created.
+   */
+  transform?: (element: Element, type: DecorationTransformType) => Element | void;
+  /**
+   * By default when the decoration contains only one token, the decoration will be applied to the token.
+   *
+   * Set to `true` to always wrap the token with a new element
+   *
+   * @default false
+   */
+  alwaysWrap?: boolean;
+}
+type DecorationTransformType = 'wrapper' | 'line' | 'token';
+interface Position {
+  line: number;
+  character: number;
+}
+type Offset = number;
+type OffsetOrPosition = Position | Offset;
+//#endregion
+//#region src/themes.d.ts
+type SpecialTheme = 'none';
+interface ThemeRegistrationRaw extends IRawTheme, Partial<Omit<ThemeRegistration, 'name' | 'settings'>> {}
+interface ThemeRegistration extends Partial<ThemeRegistrationResolved> {}
+interface ThemeRegistrationResolved extends IRawTheme {
+  /**
+   * Theme name
+   */
+  name: string;
+  /**
+   * Display name
+   *
+   * @field shiki custom property
+   */
+  displayName?: string;
+  /**
+   * Light/dark theme
+   *
+   * @field shiki custom property
+   */
+  type: 'light' | 'dark';
+  /**
+   * Token rules
+   */
+  settings: IRawThemeSetting[];
+  /**
+   * Same as `settings`, will use as fallback if `settings` is not present.
+   */
+  tokenColors?: IRawThemeSetting[];
+  /**
+   * Default foreground color
+   *
+   * @field shiki custom property
+   */
+  fg: string;
+  /**
+   * Background color
+   *
+   * @field shiki custom property
+   */
+  bg: string;
+  /**
+   * A map of color names to new color values.
+   *
+   * The color key starts with '#' and should be lowercased.
+   *
+   * @field shiki custom property
+   */
+  colorReplacements?: Record<string, string>;
+  /**
+   * Color map of VS Code options
+   *
+   * Will be used by shiki on `lang: 'ansi'` to find ANSI colors, and to find the default foreground/background colors.
+   */
+  colors?: Record<string, string>;
+  /**
+   * JSON schema path
+   *
+   * @field not used by shiki
+   */
+  $schema?: string;
+  /**
+   * Enable semantic highlighting
+   *
+   * @field not used by shiki
+   */
+  semanticHighlighting?: boolean;
+  /**
+   * Tokens for semantic highlighting
+   *
+   * @field not used by shiki
+   */
+  semanticTokenColors?: Record<string, string>;
+}
+type ThemeRegistrationAny = ThemeRegistrationRaw | ThemeRegistration | ThemeRegistrationResolved;
+//#endregion
+//#region src/tokens.d.ts
+/**
+ * GrammarState is a special reference object that holds the state of a grammar.
+ *
+ * It's used to highlight code snippets that are part of the target language.
+ */
+interface GrammarState {
+  readonly lang: string;
+  readonly theme: string;
+  readonly themes: string[];
+  /**
+   * @internal
+   */
+  getInternalStack: (theme?: string) => StateStack | undefined;
+  getScopes: (theme?: string) => string[] | undefined;
+}
+interface CodeToTokensBaseOptions<Languages extends string = string, Themes extends string = string> extends TokenizeWithThemeOptions {
+  lang?: Languages | SpecialLanguage;
+  theme?: Themes | ThemeRegistrationAny | SpecialTheme;
+}
+type CodeToTokensOptions<Languages extends string = string, Themes extends string = string> = Omit<CodeToTokensBaseOptions<Languages, Themes>, 'theme'> & CodeOptionsThemes<Themes>;
+interface ThemedTokenScopeExplanation {
+  scopeName: string;
+  themeMatches?: IRawThemeSetting[];
+}
+interface ThemedTokenExplanation {
+  content: string;
+  scopes: ThemedTokenScopeExplanation[];
+}
+/**
+ * A single token with color, and optionally with explanation.
+ *
+ * For example:
+ *
+ * ```json
+ * {
+ *   "content": "shiki",
+ *   "color": "#D8DEE9",
+ *   "explanation": [
+ *     {
+ *       "content": "shiki",
+ *       "scopes": [
+ *         {
+ *           "scopeName": "source.js",
+ *           "themeMatches": []
+ *         },
+ *         {
+ *           "scopeName": "meta.objectliteral.js",
+ *           "themeMatches": []
+ *         },
+ *         {
+ *           "scopeName": "meta.object.member.js",
+ *           "themeMatches": []
+ *         },
+ *         {
+ *           "scopeName": "meta.array.literal.js",
+ *           "themeMatches": []
+ *         },
+ *         {
+ *           "scopeName": "variable.other.object.js",
+ *           "themeMatches": [
+ *             {
+ *               "name": "Variable",
+ *               "scope": "variable.other",
+ *               "settings": {
+ *                 "foreground": "#D8DEE9"
+ *               }
+ *             },
+ *             {
+ *               "name": "[JavaScript] Variable Other Object",
+ *               "scope": "source.js variable.other.object",
+ *               "settings": {
+ *                 "foreground": "#D8DEE9"
+ *               }
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+interface ThemedToken extends TokenStyles, TokenBase {}
+interface TokenBase {
+  /**
+   * The content of the token
+   */
+  content: string;
+  /**
+   * The start offset of the token, relative to the input code. 0-indexed.
+   */
+  offset: number;
+  /**
+   * Explanation of
+   *
+   * - token text's matching scopes
+   * - reason that token text is given a color (one matching scope matches a rule (scope -> color) in the theme)
+   */
+  explanation?: ThemedTokenExplanation[];
+}
+interface TokenStyles {
+  /**
+   * 6 or 8 digit hex code representation of the token's color
+   */
+  color?: string;
+  /**
+   * 6 or 8 digit hex code representation of the token's background color
+   */
+  bgColor?: string;
+  /**
+   * Font style of token. Can be None/Italic/Bold/Underline
+   */
+  fontStyle?: FontStyle;
+  /**
+   * Override with custom inline style for HTML renderer.
+   * When specified, `color` and `fontStyle` will be ignored.
+   * Prefer use object style for merging with other styles.
+   */
+  htmlStyle?: Record<string, string>;
+  /**
+   * Extra HTML attributes for the token.
+   */
+  htmlAttrs?: Record<string, string>;
+}
+interface TokenizeWithThemeOptions {
+  /**
+   * Include explanation of why a token is given a color.
+   *
+   * You can optionally pass `scopeName` to only include explanation for scopes,
+   * which is more performant than full explanation.
+   *
+   * @default false
+   */
+  includeExplanation?: boolean | 'scopeName';
+  /**
+   * A map of color names to new color values.
+   *
+   * The color key starts with '#' and should be lowercased.
+   *
+   * This will be merged with theme's `colorReplacements` if any.
+   */
+  colorReplacements?: Record<string, string | Record<string, string>>;
+  /**
+   * Lines above this length will not be tokenized for performance reasons.
+   *
+   * @default 0 (no limit)
+   */
+  tokenizeMaxLineLength?: number;
+  /**
+   * Time limit in milliseconds for tokenizing a single line.
+   *
+   * @default 500 (0.5s)
+   */
+  tokenizeTimeLimit?: number;
+  /**
+   * Represent the state of the grammar, allowing to continue tokenizing from a intermediate grammar state.
+   *
+   * You can get the grammar state from `getLastGrammarState`.
+   */
+  grammarState?: GrammarState;
+  /**
+   * The code context of the grammar.
+   * Consider it a prepended code to the input code, that only participate the grammar inference but not presented in the final output.
+   *
+   * This will be ignored if `grammarState` is provided.
+   */
+  grammarContextCode?: string;
+}
+/**
+ * Result of `codeToTokens`, an object with 2D array of tokens and meta info like background and foreground color.
+ */
+interface TokensResult {
+  /**
+   * 2D array of tokens, first dimension is lines, second dimension is tokens in a line.
+   */
+  tokens: ThemedToken[][];
+  /**
+   * Foreground color of the code.
+   */
+  fg?: string;
+  /**
+   * Background color of the code.
+   */
+  bg?: string;
+  /**
+   * A string representation of themes applied to the token.
+   */
+  themeName?: string;
+  /**
+   * Custom style string to be applied to the root `<pre>` element.
+   * When specified, `fg` and `bg` will be ignored.
+   */
+  rootStyle?: string | false;
+  /**
+   * The last grammar state of the code snippet.
+   */
+  grammarState?: GrammarState;
+} //#endregion
+//#region src/transformers.d.ts
+interface TransformerOptions {
+  /**
+   * Transformers for the Shiki pipeline.
+   */
+  transformers?: ShikiTransformer[];
+}
+interface ShikiTransformerContextMeta {}
+/**
+ * Common transformer context for all transformers hooks
+ */
+interface ShikiTransformerContextCommon {
+  meta: ShikiTransformerContextMeta;
+  options: CodeToHastOptions;
+  codeToHast: (code: string, options: CodeToHastOptions) => Root;
+  codeToTokens: (code: string, options: CodeToTokensOptions) => TokensResult;
+}
+interface ShikiTransformerContextSource extends ShikiTransformerContextCommon {
+  readonly source: string;
+}
+/**
+ * Transformer context for HAST related hooks
+ */
+interface ShikiTransformerContext extends ShikiTransformerContextSource {
+  readonly tokens: ThemedToken[][];
+  readonly root: Root;
+  readonly pre: Element;
+  readonly code: Element;
+  readonly lines: Element[];
+  readonly structure: CodeToHastOptions['structure'];
+  /**
+   * Utility to append class to a hast node
+   *
+   * If the `property.class` is a string, it will be splitted by space and converted to an array.
+   */
+  addClassToHast: (hast: Element, className: string | string[]) => Element;
+}
+interface ShikiTransformer {
+  /**
+   * Name of the transformer
+   */
+  name?: string;
+  /**
+   * Enforce plugin invocation tier similar to webpack loaders. Hooks ordering
+   * is still subject to the `order` property in the hook object.
+   *
+   * Plugin invocation order:
+   * - `enforce: 'pre'` plugins
+   * - normal plugins
+   * - `enforce: 'post'` plugins
+   * - shiki post plugins
+   */
+  enforce?: 'pre' | 'post';
+  /**
+   * Transform the raw input code before passing to the highlighter.
+   */
+  preprocess?: (this: ShikiTransformerContextCommon, code: string, options: CodeToHastOptions) => string | void;
+  /**
+   * Transform the full tokens list before converting to HAST.
+   * Return a new tokens list will replace the original one.
+   */
+  tokens?: (this: ShikiTransformerContextSource, tokens: ThemedToken[][]) => ThemedToken[][] | void;
+  /**
+   * Transform the entire generated HAST tree. Return a new Node will replace the original one.
+   */
+  root?: (this: ShikiTransformerContext, hast: Root) => Root | void;
+  /**
+   * Transform the `<pre>` element. Return a new Node will replace the original one.
+   */
+  pre?: (this: ShikiTransformerContext, hast: Element) => Element | void;
+  /**
+   * Transform the `<code>` element. Return a new Node will replace the original one.
+   */
+  code?: (this: ShikiTransformerContext, hast: Element) => Element | void;
+  /**
+   * Transform each line `<span class="line">` element.
+   *
+   * @param hast
+   * @param line 1-based line number
+   */
+  line?: (this: ShikiTransformerContext, hast: Element, line: number) => Element | void;
+  /**
+   * Transform each token `<span>` element.
+   */
+  span?: (this: ShikiTransformerContext, hast: Element, line: number, col: number, lineElement: Element, token: ThemedToken) => Element | void;
+  /**
+   * Transform the generated HTML string before returning.
+   * This hook will only be called with `codeToHtml`.
+   */
+  postprocess?: (this: ShikiTransformerContextCommon, html: string, options: CodeToHastOptions) => string | void;
+} //#endregion
+//#region src/options.d.ts
+interface CodeOptionsSingleTheme<Themes extends string = string> {
+  theme: ThemeRegistrationAny | StringLiteralUnion<Themes>;
+}
+interface CodeOptionsMultipleThemes<Themes extends string = string> {
+  /**
+   * A map of color names to themes.
+   * This allows you to specify multiple themes for the generated code.
+   *
+   * ```ts
+   * highlighter.codeToHtml(code, {
+   *   lang: 'js',
+   *   themes: {
+   *     light: 'vitesse-light',
+   *     dark: 'vitesse-dark',
+   *   }
+   * })
+   * ```
+   *
+   * Will generate:
+   *
+   * ```html
+   * <span style="color:#111;--shiki-dark:#fff;">code</span>
+   * ```
+   *
+   * @see https://shiki.style/guide/dual-themes
+   */
+  themes: Partial<Record<string, ThemeRegistrationAny | StringLiteralUnion<Themes>>>;
+  /**
+   * The default theme applied to the code (via inline `color` style).
+   * The rest of the themes are applied via CSS variables, and toggled by CSS overrides.
+   *
+   * For example, if `defaultColor` is `light`, then `light` theme is applied to the code,
+   * and the `dark` theme and other custom themes are applied via CSS variables:
+   *
+   * ```html
+   * <span style="color:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+   * ```
+   *
+   * When set to `false`, no default styles will be applied, and totally up to users to apply the styles:
+   *
+   * ```html
+   * <span style="--shiki-light:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+   * ```
+   *
+   * When set to `light-dark()`, the default color will be rendered as `light-dark(#{light}, #{dark})`.
+   *
+   * ```html
+   * <span style="color:light-dark(#{light}, #{dark});--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+   * ```
+   *
+   * @default 'light'
+   */
+  defaultColor?: StringLiteralUnion<'light' | 'dark'> | 'light-dark()' | false;
+  /**
+   * The strategy to render multiple colors.
+   *
+   * - `css-vars`: Render the colors via CSS variables.
+   * - `none`: Do not render the colors, only use the default color.
+   *
+   * @default 'css-vars'
+   */
+  colorsRendering?: 'css-vars' | 'none';
+  /**
+   * Prefix of CSS variables used to store the color of the other theme.
+   *
+   * @default '--shiki-'
+   */
+  cssVariablePrefix?: string;
+}
+type CodeOptionsThemes<Themes extends string = string> = CodeOptionsSingleTheme<Themes> | CodeOptionsMultipleThemes<Themes>;
+type CodeToHastOptions<Languages extends string = string, Themes extends string = string> = CodeToHastOptionsCommon<Languages> & CodeOptionsThemes<Themes> & CodeOptionsMeta;
+interface CodeToHastOptionsCommon<Languages extends string = string> extends TransformerOptions, DecorationOptions, Pick<TokenizeWithThemeOptions, 'colorReplacements' | 'tokenizeMaxLineLength' | 'tokenizeTimeLimit' | 'grammarState' | 'grammarContextCode' | 'includeExplanation'> {
+  /**
+   * Data to be added to the root `<pre>` element.
+   */
+  data?: Record<string, unknown>;
+  /**
+   * The grammar name for the code.
+   */
+  lang: StringLiteralUnion<Languages | SpecialLanguage>;
+  /**
+   * Custom style string to be applied to the root `<pre>` element.
+   *
+   * When set to `false`, no style will be applied.
+   */
+  rootStyle?: string | false;
+  /**
+   * Merge whitespace tokens to saving extra `<span>`.
+   *
+   * When set to true, it will merge whitespace tokens with the next token.
+   * When set to false, it keep the output as-is.
+   * When set to `never`, it will force to separate leading and trailing spaces from tokens.
+   *
+   * @default true
+   */
+  mergeWhitespaces?: boolean | 'never';
+  /**
+   * Merge consecutive tokens with the same style to reduce the number of DOM nodes.
+   * This can improve rendering performance but may affect the structure of the output.
+   *
+   * @default false
+   */
+  mergeSameStyleTokens?: boolean;
+  /**
+   * The structure of the generated HAST and HTML.
+   *
+   * - `classic`: The classic structure with `<pre>` and `<code>` elements, each line wrapped with a `<span class="line">` element.
+   * - `inline`: All tokens are rendered as `<span>`, line breaks are rendered as `<br>`. No `<pre>` or `<code>` elements. Default forground and background colors are not applied.
+   *
+   * @default 'classic'
+   */
+  structure?: 'classic' | 'inline';
+  /**
+   * Tab index of the root `<pre>` element.
+   *
+   * Set to `false` to disable tab index.
+   *
+   * @default 0
+   */
+  tabindex?: number | string | false;
+}
+interface CodeOptionsMeta {
+  /**
+   * Meta data passed to Shiki, usually used by plugin integrations to pass the code block header.
+   *
+   * Key values in meta will be serialized to the attributes of the root `<pre>` element.
+   *
+   * Keys starting with `_` will be ignored.
+   *
+   * A special key `__raw` key will be used to pass the raw code block header (if the integration supports it).
+   */
+  meta?: {
+    /**
+     * Raw string of the code block header.
+     */
+    __raw?: string;
+    [key: string]: any;
+  };
+}
+//#endregion
 //#region src/_internal/code-transformers.d.ts
 /**
  * The canonical Shiki transformer chain for Nimbus. Returns a fresh
@@ -124,14 +1082,25 @@ interface IndexedEntry {
   /** Description — undefined when the schema doesn't expose one or it's empty. */
   description: string | undefined;
   /**
-   * Page URL path under the site (no origin, no trailing slash unless
-   * empty). Computed via the convention that the **primary** docs
-   * collection mounts at the site root (e.g. `/getting-started`) while
-   * every other collection mounts under its name (`/api/payments/create`,
-   * `/blog/my-first-post`). Routes building `.md` alternates append
-   * `/index.md`; chrome building HTML links append a trailing slash.
+   * Page URL path under the site (no origin). Browser-facing form:
+   * trailing slash on HTML document routes (`/getting-started/`) so
+   * `<a href>` consumers don't trigger a redirect on static hosts that
+   * canonicalize directory-index pages. The primary docs collection
+   * mounts at the site root, every other collection mounts under its
+   * name (`/api/payments/create/`, `/blog/my-first-post/`). Routes
+   * building `.md` alternates should consume `markdownUrl` rather than
+   * deriving from this field — the root-index case (`/`) needs a
+   * different shape than the trailing-slash-strip recipe produces.
    */
   url: string;
+  /**
+   * Site-relative URL of the page's clean-markdown alternate. Mirrors
+   * the path the per-page `.md` route emits: `/getting-started/index.md`
+   * for an entry at `/getting-started/`, `/index.md` for the root-index
+   * entry. Consumers (`llms.txt`, the `.md` route's `Source:` line)
+   * should use this directly instead of synthesizing from `url`.
+   */
+  markdownUrl: string;
 }
 interface IndexedTopLevelGroup {
   /** Top-level slug — first URL segment under root. */
@@ -174,6 +1143,28 @@ interface IndexedTopLevel {
    */
   groups: IndexedTopLevelGroup[];
 }
+/**
+ * Cross-collection entry list for the agent-facing routes
+ * (`llms.txt`, per-page `.md` alternates, future `llms-full.txt` and
+ * `rag.jsonl`). Implements the indexing baseline of the two-layer
+ * architecture documented at `/features/llms-txt`:
+ *
+ *   - **Multi-collection by default, zero opt-in.** Iterates every
+ *     collection registered in `src/content.config.ts` except names
+ *     matching `partials` or starting with `_` (reserved).
+ *   - **Schema-tolerant.** Reads `title` and `description` if present;
+ *     falls back to the entry id for the title and omits the
+ *     description otherwise.
+ *   - **Per-page filters baked in.** Drops entries with `draft: true`;
+ *     absent fields read as the docs-schema default (`draft: false`).
+ *     All published pages are indexed — there is no per-page opt-out.
+ *     A page that genuinely shouldn't be agent-readable should be kept
+ *     out of the content collection entirely.
+ *
+ * The returned shape is identical regardless of which factory created
+ * the collection: hand-rolled `defineCollection({ loader, schema })`
+ * collections work without modification.
+ */
 declare function getIndexedEntries(): Promise<IndexedEntry[]>;
 /**
  * Partition the indexed entries into the shape the root `/llms.txt`
@@ -237,6 +1228,14 @@ declare function getSidebarSections(currentSlug: string, options?: {
  *
  * Walks the flattened sidebar; returns the surrounding entries. Honors
  * `prev`/`next` frontmatter overrides if provided.
+ *
+ * When an override uses the object form with an internal `link`
+ * (e.g. `prev: { link: "/getting-started" }`), the link is validated
+ * against every visible content entry's URL at build time. A pointer
+ * to a missing page fails the build with a clear error — the same
+ * staleness-detection mechanism used for `previousSlug` in versioning.
+ * The string form (`prev: "Custom label"`) is a label-only override
+ * and doesn't go through link validation.
  */
 declare function getPrevNext(currentSlug: string, options?: {
   overrides?: PrevNextOverrides;