@ox-content/vite-plugin 2.67.0 → 2.68.0

package/dist/index.d.cts

@@ -264,15 +264,30 @@ interface GitHubSourceData {
   language: string | null;
 }
 interface GitHubOptions {
-  /** GitHub API token for higher rate limits. */
+  /**
+   * GitHub API token used for higher rate limits and private repository access.
+   * @default ''
+   */
   token?: string;
-  /** Cache fetched data. Default: true */
+  /**
+   * Cache fetched repository and source data in memory for the current process.
+   * @default true
+   */
   cache?: boolean;
-  /** Cache TTL in milliseconds. Default: 3600000 (1 hour) */
+  /**
+   * Cache TTL in milliseconds.
+   * @default 3600000
+   */
   cacheTTL?: number;
-  /** Maximum source file size to inline in bytes. Default: 200000 */
+  /**
+   * Maximum source file size to inline in bytes.
+   * @default 200000
+   */
   maxSourceBytes?: number;
-  /** Maximum source lines to inline when no line range is specified. Default: 120 */
+  /**
+   * Maximum source lines to inline when no line range is specified.
+   * @default 120
+   */
   maxSourceLines?: number;
 }
 declare function parseGitHubLineRange(value: string | undefined): GitHubLineRange | undefined;
@@ -322,13 +337,25 @@ interface OgpData {
   favicon?: string;
 }
 interface OgpOptions {
-  /** Request timeout in milliseconds. Default: 10000 */
+  /**
+   * Request timeout in milliseconds.
+   * @default 10000
+   */
   timeout?: number;
-  /** Cache fetched data. Default: true */
+  /**
+   * Cache fetched Open Graph metadata in memory for the current process.
+   * @default true
+   */
   cache?: boolean;
-  /** Cache TTL in milliseconds. Default: 3600000 (1 hour) */
+  /**
+   * Cache TTL in milliseconds.
+   * @default 3600000
+   */
   cacheTTL?: number;
-  /** User agent for requests */
+  /**
+   * User agent sent with metadata fetch requests.
+   * @default 'ox-content-ogp-bot/1.0 (compatible; +https://github.com/ubugeeei-prod/ox-content)'
+   */
   userAgent?: string;
 }
 /**
@@ -371,7 +398,8 @@ interface PmOptions {
    * Enable opt-in synced package-manager tab groups. When `true`, a
    * `data-ox-tab-group="pkg-manager"` attribute is emitted so the client runtime
    * syncs the active package manager across every pm group on the page and
-   * persists the choice in localStorage. Default: false.
+   * persists the choice in localStorage.
+   * @default false
    */
   sync?: boolean;
 }
@@ -400,13 +428,25 @@ declare function generateTabsCSS(groupCount: number): string;
  * check so pages without a `<youtube>` element never cross the NAPI boundary.
  */
 interface YouTubeOptions {
-  /** Use privacy-enhanced mode (youtube-nocookie.com). Default: true */
+  /**
+   * Use privacy-enhanced mode (`youtube-nocookie.com`).
+   * @default true
+   */
   privacyEnhanced?: boolean;
-  /** Default aspect ratio. Default: "16/9" */
+  /**
+   * Default iframe aspect ratio.
+   * @default '16/9'
+   */
   aspectRatio?: string;
-  /** Allow fullscreen. Default: true */
+  /**
+   * Allow fullscreen playback.
+   * @default true
+   */
   allowFullscreen?: boolean;
-  /** Lazy load iframe. Default: true */
+  /**
+   * Lazy load the iframe.
+   * @default true
+   */
   lazyLoad?: boolean;
 }
 /**
@@ -427,7 +467,10 @@ declare function transformYouTube(html: string, options?: YouTubeOptions): Promi
  * extracts mermaid code blocks from HTML and renders them using mmdc.
  */
 interface MermaidOptions {
-  /** Mermaid theme. Default: "neutral" */
+  /**
+   * Mermaid theme used by the CLI renderer.
+   * @default 'neutral'
+   */
   theme?: "default" | "dark" | "forest" | "neutral" | "base";
 }
 /**
@@ -578,42 +621,76 @@ interface SsgNavigationGroup {
   items: SsgNavigationItem[];
 }
 /**
- * SSG (Static Site Generation) options.
+ * Static Site Generation options.
+ *
+ * These options control the HTML files emitted at build time and the matching
+ * dev-server preview behavior. Pass `false` to the top-level `ssg` option to
+ * disable the whole SSG pipeline, or pass an object to customize the defaults.
  */
 interface SsgOptions {
   /**
-   * Enable SSG mode.
+   * Enable the SSG pipeline.
+   *
+   * Keep this enabled when ox-content owns page rendering. Disable it only when
+   * another framework integration will consume the Markdown modules directly.
+   *
    * @default true
    */
   enabled?: boolean;
   /**
-   * Output file extension.
+   * File extension used for generated routes.
+   *
+   * The value should include the leading dot. For example, `.html` emits
+   * `guide.html`, while an empty string can be used by custom deployments that
+   * map extensionless output themselves.
+   *
    * @default '.html'
    */
   extension?: string;
   /**
-   * Clean output directory before build.
+   * Remove previously generated files from the output directory before writing
+   * the new SSG result.
+   *
+   * Leave this disabled when the output directory also contains assets produced
+   * by other Vite plugins or external build steps.
+   *
    * @default false
    */
   clean?: boolean;
   /**
-   * Bare HTML output (no navigation, no styles).
-   * Useful for benchmarking or when using custom layouts.
+   * Emit bare HTML with only the rendered Markdown body.
+   *
+   * This skips the default navigation, layout shell, and theme styles. It is
+   * mainly useful for benchmarking, fixture generation, or projects that wrap
+   * the output in their own shell.
+   *
    * @default false
    */
   bare?: boolean;
   /**
-   * Site name for header and title suffix.
+   * Site name shown in the default theme header and title suffix.
+   *
+   * When omitted, the renderer falls back to project metadata where available.
+   *
+   * @default undefined
    */
   siteName?: string;
   /**
-   * OG image URL for social sharing (static URL).
-   * If generateOgImage is enabled, this serves as the fallback.
+   * Static Open Graph image URL used for social sharing.
+   *
+   * When `generateOgImage` is enabled, this value is still useful as a fallback
+   * for pages that cannot produce a generated image.
+   *
+   * @default undefined
    */
   ogImage?: string;
   /**
-   * Generate OG images per page using Rust-based generator.
-   * When enabled, each page will have a unique OG image.
+   * Generate one Open Graph image per page.
+   *
+   * Generated images are written alongside the SSG output and referenced from
+   * each page's metadata. Configure rendering details with the top-level
+   * `ogImageOptions` option.
+   *
    * @default false
    */
   generateOgImage?: boolean;
@@ -623,19 +700,36 @@ interface SsgOptions {
    */
   lastUpdated?: boolean;
   /**
-   * Site URL for generating absolute OG image URLs.
-   * Required for proper SNS sharing.
-   * Example: 'https://example.com'
+   * Absolute site URL used when generating social metadata.
+   *
+   * Set this when pages need absolute Open Graph image URLs. Include the origin
+   * and any deployment base path, without a trailing page path.
+   *
+   * @example
+   * ```ts
+   * siteUrl: 'https://example.com/docs'
+   * ```
+   *
+   * @default undefined
    */
   siteUrl?: string;
   /**
-   * Theme configuration for customizing the SSG output.
-   * Use defineTheme() to create a theme configuration.
+   * Theme configuration for generated pages.
+   *
+   * Use `defineTheme()` to build this object so custom theme modules and the
+   * default theme extension points keep their expected shape.
+   *
+   * @default defaultTheme
    */
   theme?: ThemeConfig;
   /**
-   * Override the auto-generated sidebar navigation.
-   * Useful when migrating from tools with explicit navigation config such as VitePress.
+   * Sidebar navigation override.
+   *
+   * When omitted, ox-content derives navigation from the Markdown file tree.
+   * Provide this when migrating from systems such as VitePress where navigation
+   * is intentionally hand-authored.
+   *
+   * @default undefined
    */
   navigation?: SsgNavigationGroup[];
 }
@@ -656,32 +750,61 @@ interface ResolvedSsgOptions {
   navigation?: SsgNavigationGroup[];
 }
 /**
- * Plugin options.
+ * Options for the core `oxContent()` Vite plugin.
+ *
+ * The top-level options describe where content lives, which Markdown features
+ * are enabled, and which build-time features should run. Feature toggles that
+ * accept `boolean | Options` follow the same convention:
+ *
+ * - `false` disables the feature.
+ * - `true` enables the feature with its documented defaults.
+ * - an object enables the feature and overrides only the provided fields.
  */
 interface OxContentOptions {
   /**
-   * Source directory for Markdown files.
+   * Directory containing Markdown source files.
+   *
+   * The path is resolved from the Vite project root. SSG, search indexing, and
+   * dev-server routing all use this directory as the content root.
+   *
    * @default 'content'
    */
   srcDir?: string;
   /**
-   * Output directory for built files.
+   * Directory where generated files are written.
+   *
+   * SSG HTML, search indexes, and generated assets are emitted under this
+   * directory during production builds.
+   *
    * @default 'dist'
    */
   outDir?: string;
   /**
-   * Base path for the site.
+   * Base path prepended to generated internal URLs.
+   *
+   * Use this when the site is deployed below a sub-path, such as GitHub Pages or
+   * a documentation route inside a larger application.
+   *
    * @default '/'
    */
   base?: string;
   /**
    * Markdown-like file extensions to process.
+   *
+   * Extensions are normalized with a leading dot and matched case-insensitively.
+   * Add custom extensions when another authoring format is compiled to Markdown
+   * before ox-content sees it.
+   *
    * @default ['.md', '.markdown', '.mdx']
    */
   extensions?: string[];
   /**
-   * SSG (Static Site Generation) options.
-   * Set to false to disable SSG completely.
+   * Static Site Generation options.
+   *
+   * Passing `true` or omitting this option enables SSG with defaults. Passing
+   * `false` disables the SSG plugin while still allowing Markdown module
+   * transforms to run.
+   *
    * @default { enabled: true }
    */
   ssg?: SsgOptions | boolean;
@@ -724,47 +847,81 @@ interface OxContentOptions {
    * Additional languages for syntax highlighting.
    * Accepts Shiki LanguageRegistration objects (e.g., TextMate grammars).
    * These are loaded alongside the built-in languages.
+   * @default []
    */
   highlightLangs?: LanguageRegistration$1[];
   /**
-   * Opt-in code block annotations for fenced code blocks.
+   * Code block line annotations for fenced code blocks.
    *
-   * Supports the configurable attribute syntax by default, and can also opt
-   * into VitePress-compatible fence metadata and inline notation.
+   * This feature is opt-in because it changes rendered code-block markup. Pass
+   * `true` to enable ox-content's attribute syntax, or pass an options object to
+   * change the meta key or enable VitePress-compatible notation.
    *
-   * Example:
-   * ` ```ts annotate="highlight:1,3-4;warning:6;error:7" `
+   * @example
+   * ~~~md
+   * ```ts annotate="highlight:1,3-4;warning:6;error:7"
+   * const value = compute()
+   * ```
+   * ~~~
    *
    * @default false
    */
   codeAnnotations?: boolean | CodeAnnotationsOptions;
   /**
    * Expand Obsidian-style `[[page]]` and `[[page|label]]` links.
+   *
+   * Use this for knowledge-base style content where authors prefer short,
+   * document-relative link syntax. Pass an object to override the base URL used
+   * when resolving generated hrefs.
+   *
    * @default false
    */
   wikiLinks?: boolean | WikiLinkOptions;
   /**
    * Expand `:shortcode:` emoji aliases to Unicode.
+   *
+   * Built-in aliases cover common emoji names. Provide `custom` entries for
+   * project-specific aliases or to override a built-in mapping.
+   *
    * @default false
    */
   emojiShortcodes?: boolean | EmojiShortcodeOptions;
   /**
    * Enable markdown-it-attrs style `{#id .class key=value}` attributes.
+   *
+   * Attribute blocks can be attached to headings, paragraphs, links, images, and
+   * other supported Markdown nodes depending on parser context.
+   *
    * @default false
    */
   attrs?: boolean | AttrsOptions;
   /**
    * Import source snippets into fences with `<<< @/path/to/file.ts{region}`.
+   *
+   * This is useful for documentation that must stay synchronized with examples
+   * in the repository. Use `rootDir` when snippets should resolve from a
+   * directory other than the Vite project root.
+   *
    * @default false
    */
   codeImports?: boolean | CodeImportOptions;
   /**
    * Sanitize rendered HTML with safe defaults or explicit allow lists.
+   *
+   * Enable this for untrusted Markdown. The default allow lists are conservative;
+   * pass an options object only when the content model intentionally needs extra
+   * tags, attributes, or URL schemes.
+   *
    * @default false
    */
   sanitize?: boolean | SanitizeOptions;
   /**
    * Append an "edit this page" link to rendered Markdown.
+   *
+   * The feature is enabled only when `repoUrl` is provided in the options object.
+   * Passing `true` keeps the feature disabled because there is not enough
+   * repository information to generate valid links.
+   *
    * @default false
    */
   editThisPage?: boolean | EditThisPageOptions;
@@ -776,16 +933,30 @@ interface OxContentOptions {
   cjkEmphasis?: boolean;
   /**
    * Lint fenced code blocks during Markdown transforms.
+   *
+   * Use this as a lightweight authoring check for missing languages or trailing
+   * whitespace inside fences. For project-wide linting, prefer the exported
+   * `lintCodeBlocks()` helper or the Markdown lint APIs.
+   *
    * @default false
    */
   codeBlockLint?: boolean | CodeBlockLintOptions;
   /**
    * Type-check TypeScript/TSX code fences via tsgo.
+   *
+   * By default only fences with explicit opt-in metadata are checked. This keeps
+   * incidental examples cheap while allowing docs-as-code snippets to fail the
+   * build when configured with `mode: 'error'`.
+   *
    * @default false
    */
   codeBlockTypecheck?: boolean | CodeBlockTypecheckOptions;
   /**
    * Extract runnable fenced examples for Vitest docs-as-tests harnesses.
+   *
+   * Collected examples can be written by the docs test helpers and executed as
+   * part of a normal Vitest suite.
+   *
    * @default false
    */
   docsTests?: boolean | DocsTestOptions;
@@ -816,10 +987,14 @@ interface OxContentOptions {
   ogImage?: boolean;
   /**
    * OG image generation options.
+   * Ignored unless `ogImage` or `ssg.generateOgImage` is enabled.
+   * @default { vuePlugin: 'vitejs', width: 1200, height: 630, cache: true, concurrency: 1 }
    */
   ogImageOptions?: OgImageOptions;
   /**
    * Custom AST transformers.
+   * Transformers run after parsing and before the final JavaScript module is emitted.
+   * @default []
    */
   transformers?: MarkdownTransformer[];
   /**
@@ -969,50 +1144,203 @@ interface ResolvedBuiltinEmbedOptions {
   bluesky: boolean;
   webContainer: boolean;
 }
+/**
+ * Options for expanding Obsidian-style wiki links.
+ *
+ * The transform accepts `[[target]]` and `[[target|label]]` syntax and rewrites
+ * it to regular links before rendering. It is intentionally small: path
+ * resolution is based on the configured base URL rather than a full backlink
+ * graph.
+ */
 interface WikiLinkOptions {
+  /**
+   * Base URL prepended to resolved wiki-link targets.
+   *
+   * When omitted, the top-level `base` option is used.
+   *
+   * @default options.base
+   */
   baseUrl?: string;
 }
+/**
+ * Resolved wiki-link transform options.
+ */
 interface ResolvedWikiLinkOptions {
   enabled: boolean;
   baseUrl: string;
 }
+/**
+ * Options for expanding `:shortcode:` emoji aliases.
+ *
+ * The transform replaces recognized shortcode tokens with their Unicode emoji
+ * equivalents during Markdown transformation. Unknown shortcodes are left
+ * untouched so colon-delimited text can still be used by other tools.
+ */
 interface EmojiShortcodeOptions {
+  /**
+   * Custom shortcode map merged with the built-in emoji aliases.
+   *
+   * Keys should omit the surrounding colons.
+   *
+   * @example
+   * ```ts
+   * custom: { shipit: '\u{1F6A2}' }
+   * ```
+   *
+   * @default {}
+   */
   custom?: Record<string, string>;
 }
+/**
+ * Resolved emoji-shortcode transform options.
+ */
 interface ResolvedEmojiShortcodeOptions {
   enabled: boolean;
   custom: Record<string, string>;
 }
+/**
+ * Options for markdown-it-attrs style attribute blocks.
+ *
+ * Attribute blocks let authors attach IDs, classes, and key/value attributes to
+ * nearby Markdown nodes with syntax such as `{#install .lead}`.
+ */
 interface AttrsOptions {
+  /**
+   * Enable the attrs transform when an options object is supplied.
+   *
+   * Set to `false` to keep the object shape while disabling the transform.
+   * This is mainly useful for config merging where callers want to preserve a
+   * stable object structure.
+   *
+   * @default true
+   */
   enabled?: boolean;
 }
+/**
+ * Resolved attrs transform options.
+ */
 interface ResolvedAttrsOptions {
   enabled: boolean;
 }
+/**
+ * Options for importing source snippets into code fences.
+ *
+ * The transform resolves `<<<` imports before code highlighting and other
+ * code-block features run. Imported snippets therefore behave like ordinary
+ * fenced code in later stages.
+ */
 interface CodeImportOptions {
+  /**
+   * Directory used to resolve `<<<` imports.
+   *
+   * When omitted, imports resolve from the Vite project root and configured aliases.
+   *
+   * @example
+   * ```ts
+   * rootDir: 'examples'
+   * ```
+   *
+   * @default undefined
+   */
   rootDir?: string;
 }
+/**
+ * Resolved code-import transform options.
+ */
 interface ResolvedCodeImportOptions {
   enabled: boolean;
   rootDir?: string;
 }
+/**
+ * Options for sanitizing rendered HTML.
+ *
+ * Sanitization happens after Markdown is rendered to HTML. This makes it useful
+ * for user-authored content, but consumers should avoid enabling extra tags or
+ * schemes unless the rendered output explicitly requires them.
+ */
 interface SanitizeOptions {
+  /**
+   * Allowed HTML tag names. Omit to use the built-in safe tag allow list.
+   *
+   * Provide a full replacement list, not a list of additions.
+   *
+   * @default undefined
+   */
   allowedTags?: string[];
+  /**
+   * Allowed HTML attribute names. Omit to use the built-in safe attribute allow list.
+   *
+   * Provide a full replacement list, not a list of additions.
+   *
+   * @default undefined
+   */
   allowedAttributes?: string[];
+  /**
+   * Allowed URL schemes for link-like attributes.
+   *
+   * Omit to use the built-in safe scheme allow list.
+   *
+   * @default undefined
+   */
   allowedUrlSchemes?: string[];
 }
+/**
+ * Resolved sanitize transform options.
+ */
 interface ResolvedSanitizeOptions {
   enabled: boolean;
   allowedTags?: string[];
   allowedAttributes?: string[];
   allowedUrlSchemes?: string[];
 }
+/**
+ * Options for appending an "edit this page" link.
+ *
+ * The generated link points at the source Markdown file rather than the emitted
+ * HTML route. Configure `branch` and `rootDir` to match the repository layout
+ * users should edit.
+ */
 interface EditThisPageOptions {
+  /**
+   * Repository URL used to build edit links.
+   *
+   * The transform is enabled only when this value is provided.
+   *
+   * @example
+   * ```ts
+   * repoUrl: 'https://github.com/owner/project'
+   * ```
+   */
   repoUrl: string;
+  /**
+   * Branch used in generated edit links.
+   *
+   * Use the branch that accepts documentation changes, not necessarily the
+   * branch that produced the deployed site.
+   *
+   * @default 'main'
+   */
   branch?: string;
+  /**
+   * Source root inside the repository, used before the page path.
+   *
+   * Set this when `srcDir` is nested in a package or docs workspace.
+   *
+   * @default undefined
+   */
   rootDir?: string;
+  /**
+   * Link text rendered in the page footer.
+   *
+   * Keep this short; the default theme renders it as a compact footer action.
+   *
+   * @default 'Edit this page'
+   */
   label?: string;
 }
+/**
+ * Resolved edit-link transform options.
+ */
 interface ResolvedEditThisPageOptions {
   enabled: boolean;
   repoUrl?: string;
@@ -1020,12 +1348,51 @@ interface ResolvedEditThisPageOptions {
   rootDir?: string;
   label: string;
 }
+/**
+ * Options for linting fenced code blocks during Markdown transforms.
+ *
+ * These checks are intentionally local to each fence. They do not execute code
+ * or parse a project graph, so they are safe to run during normal Markdown
+ * transformation.
+ */
 interface CodeBlockLintOptions {
+  /**
+   * Languages to lint. Omit to lint every fenced block language.
+   *
+   * Language names are compared case-insensitively.
+   *
+   * @default undefined
+   */
   languages?: string[];
+  /**
+   * Require every fenced code block to declare a language.
+   *
+   * This is helpful for documentation sites where every example should be
+   * highlighted and searchable by language.
+   *
+   * @default false
+   */
   requireLanguage?: boolean;
+  /**
+   * Report trailing whitespace inside fenced code blocks.
+   *
+   * The check reports the exact line and column range inside the fence content.
+   *
+   * @default true
+   */
   trailingSpaces?: boolean;
+  /**
+   * Diagnostic severity for lint failures.
+   *
+   * Use `'error'` when code-block lint failures should fail the build.
+   *
+   * @default 'warn'
+   */
   mode?: "warn" | "error";
 }
+/**
+ * Resolved code-block lint options.
+ */
 interface ResolvedCodeBlockLintOptions {
   enabled: boolean;
   languages?: string[];
@@ -1033,12 +1400,51 @@ interface ResolvedCodeBlockLintOptions {
   trailingSpaces: boolean;
   mode: "warn" | "error";
 }
+/**
+ * Options for type-checking TypeScript and TSX fenced code blocks.
+ *
+ * Type-checking writes matching snippets to a temporary directory and invokes
+ * `tsgo`. It is best suited for concise examples that should stay synchronized
+ * with the public TypeScript API.
+ */
 interface CodeBlockTypecheckOptions {
+  /**
+   * Fence languages to type-check.
+   *
+   * Language names are compared case-insensitively.
+   *
+   * @default ['ts', 'tsx']
+   */
   languages?: string[];
+  /**
+   * Require an opt-in fence meta marker before type-checking.
+   *
+   * When enabled, only fences with metadata such as `typecheck` or `twoslash`
+   * are checked.
+   *
+   * @default true
+   */
   requireMeta?: boolean;
+  /**
+   * Command used to run the TypeScript checker.
+   *
+   * Override this for package-manager scripts or workspace-local binaries.
+   *
+   * @default 'tsgo'
+   */
   tsgoCommand?: string;
+  /**
+   * Diagnostic severity for type-check failures.
+   *
+   * Use `'error'` to fail the Markdown transform on broken snippets.
+   *
+   * @default 'warn'
+   */
   mode?: "warn" | "error";
 }
+/**
+ * Resolved code-block type-check options.
+ */
 interface ResolvedCodeBlockTypecheckOptions {
   enabled: boolean;
   languages: string[];
@@ -1046,10 +1452,34 @@ interface ResolvedCodeBlockTypecheckOptions {
   tsgoCommand: string;
   mode: "warn" | "error";
 }
+/**
+ * Options for extracting fenced examples into docs-as-tests fixtures.
+ *
+ * The extractor collects code fences that can be written into test files and
+ * executed by the exported docs test harness helpers.
+ */
 interface DocsTestOptions {
+  /**
+   * Fence languages to collect as runnable examples.
+   *
+   * Language names are compared case-insensitively.
+   *
+   * @default ['js', 'jsx', 'ts', 'tsx']
+   */
   languages?: string[];
+  /**
+   * Require an opt-in fence meta marker before collecting an example.
+   *
+   * When enabled, only fences marked with metadata such as `test`, `runnable`,
+   * `vitest`, or `docs-test` are collected.
+   *
+   * @default true
+   */
   requireMeta?: boolean;
 }
+/**
+ * Resolved docs-as-tests extraction options.
+ */
 interface ResolvedDocsTestOptions {
   enabled: boolean;
   languages: string[];
@@ -1261,39 +1691,76 @@ interface ResolvedDocsEntryPoint {
 }
 /**
  * Options for source documentation generation.
+ *
+ * The generator extracts JSDoc/TSDoc comments from JavaScript and TypeScript
+ * source files, normalizes the declarations, and writes Markdown plus optional
+ * navigation metadata. The defaults are optimized for documenting a package's
+ * public `src` tree without exposing private implementation details.
  */
 interface DocsOptions {
   /**
-   * Enable/disable docs generation.
-   * @default true (opt-out)
+   * Enable source documentation generation.
+   *
+   * The top-level `docs` option is opt-out: omitting it enables docs generation
+   * with defaults, while `docs: false` disables the docs plugin entirely.
+   *
+   * @default true
    */
   enabled?: boolean;
   /**
    * Source directories to scan for documentation.
+   *
+   * Paths are resolved from the Vite project root before applying `include` and
+   * `exclude` patterns.
+   *
    * @default ['./src']
    */
   src?: string[];
   /**
    * Output directory for generated documentation.
+   *
+   * The path is resolved from the Vite project root. Markdown pages, `docs.json`,
+   * and generated navigation metadata are written under this directory.
+   *
    * @default 'docs/api'
    */
   out?: string;
   /**
    * Glob patterns for files to include.
+   *
+   * Patterns are evaluated inside each `src` directory.
+   *
    * @default ['**\/*.ts', '**\/*.tsx', '**\/*.js', '**\/*.jsx', '**\/*.mts', '**\/*.mjs', '**\/*.cts', '**\/*.cjs']
    */
   include?: string[];
   /**
    * Glob patterns for files to exclude.
+   *
+   * Excludes run after `include` matching and should cover tests, generated
+   * files, and implementation-only entry points.
+   *
    * @default ['**\/*.test.*', '**\/*.spec.*', 'node_modules']
    */
   exclude?: string[];
   /**
    * Public API entry points used to group re-exported docs.
+   *
+   * When omitted, docs are generated from the discovered source files without
+   * entry-point grouping.
+   *
+   * Use entry points when a package exposes a smaller public surface than its
+   * source tree. Re-exported declarations are grouped under the entry point that
+   * exposes them.
+   *
+   * @default undefined
    */
   entryPoints?: DocsEntryPoint[];
   /**
    * Output format.
+   *
+   * `markdown` is the primary supported format. `json` and `html` are reserved
+   * for consumers that want to post-process extracted documentation data.
+   *
    * @default 'markdown'
    */
   format?: "markdown" | "json" | "html";
@@ -1309,7 +1776,8 @@ interface DocsOptions {
   internal?: boolean;
   /**
    * Generate table of contents for each file.
-   * @default true
+   * Reserved for future use; current generated API pages do not emit this TOC.
+   * @default false
    */
   toc?: boolean;
   /**
@@ -1319,22 +1787,41 @@ interface DocsOptions {
   groupBy?: "file" | "category";
   /**
    * GitHub repository URL for source code links.
-   * When provided, generated documentation will include links to source code.
-   * Example: 'https://github.com/ubugeeei-prod/ox-content'
+   *
+   * When provided, generated documentation includes links back to the source
+   * declaration lines.
+   *
+   * @example
+   * ```ts
+   * githubUrl: 'https://github.com/ubugeeei-prod/ox-content'
+   * ```
+   *
+   * @default undefined
    */
   githubUrl?: string;
   /**
    * Internal documentation link style.
+   *
+   * Use `markdown` for generated `.md` targets and `clean` for route-style links
+   * consumed by static-site frameworks.
+   *
    * @default 'markdown'
    */
   linkStyle?: "markdown" | "clean";
   /**
    * Route prefix used by generated documentation links and nav metadata.
-   * Nav metadata falls back to '/api' when this is not set.
+   *
+   * Nav metadata falls back to `/api` when this is not set.
+   *
+   * @default undefined
    */
   basePath?: string;
   /**
    * Generated Markdown output path strategy.
+   *
+   * `flat` emits one page per source module or category. `typedoc` emits
+   * TypeDoc-like module, kind, and symbol pages for larger API references.
+   *
    * @default 'flat'
    */
   pathStrategy?: "flat" | "typedoc";
@@ -1410,10 +1897,14 @@ interface DocsOptions {
   renderGeneratedBy?: boolean;
   /**
    * TypeDoc-style group order for module index sections and nav groups.
+   * Use `*` as the insertion point for unlisted groups.
+   * @default undefined
    */
   groupOrder?: string[];
   /**
    * TypeDoc-style sort strategies applied to entries and members.
+   * Strategies run in order; later strategies break ties from earlier ones.
+   * @default undefined
    */
   sort?: DocsSortStrategy[];
   /**
@@ -1423,6 +1914,7 @@ interface DocsOptions {
   sortEntryPoints?: boolean;
   /**
    * TypeDoc-style declaration kind ranking for module sections and nav groups.
+   * @default undefined
    */
   kindSortOrder?: string[];
   /**
@@ -1480,117 +1972,196 @@ interface ResolvedDocsOptions {
 }
 /**
  * A single documentation entry extracted from source.
+ *
+ * Entries represent top-level declarations such as functions, classes,
+ * interfaces, type aliases, enums, variables, and modules. Members of compound
+ * declarations are stored in `members`.
  */
 interface DocEntry {
+  /** Exported or declared symbol name. */
   name: string;
+  /** Normalized declaration kind used for grouping and rendering. */
   kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "module";
+  /** Main prose extracted from the leading JSDoc/TSDoc block. */
   description: string;
+  /** Function, method, or constructor parameter documentation. */
   params?: ParamDoc[];
+  /** Return value documentation for callable declarations. */
   returns?: ReturnDoc;
+  /** Code examples collected from `@example` tags. */
   examples?: string[];
+  /** Additional tags preserved by tag name after known tags are normalized. */
   tags?: Record<string, string>;
+  /** True when the entry is marked private or matched by private filtering. */
   private?: boolean;
+  /** Source file path relative to the extraction root when available. */
   file: string;
+  /** 1-based start line of the declaration in the source file. */
   line: number;
+  /** 1-based end line of the declaration in the source file. */
   endLine: number;
+  /** Full declaration signature, when the renderer can extract one. */
   signature?: string;
+  /** Members belonging to classes, interfaces, object types, and enums. */
   members?: DocMember[];
 }
 /**
  * A member belonging to a class, interface, type alias, or enum entry.
  */
 interface DocMember {
+  /** Member name as it appears in the containing declaration. */
   name: string;
+  /** Normalized member kind used for rendering and sorting. */
   kind: "property" | "method" | "constructor" | "getter" | "setter" | "enumMember";
+  /** Main prose extracted from the member's documentation comment. */
   description: string;
+  /** Full member signature, when available. */
   signature?: string;
+  /** Rendered TypeScript type text for properties and enum members. */
   type?: string;
+  /** Default value extracted from syntax or `@default` tags. */
   default?: string;
+  /** Parameter documentation for methods and constructors. */
   params?: ParamDoc[];
+  /** Return value documentation for methods and accessors. */
   returns?: ReturnDoc;
+  /** True when the member is optional in the source declaration. */
   optional?: boolean;
+  /** True when the member is declared readonly. */
   readonly?: boolean;
+  /** True when the member is static. */
   static?: boolean;
+  /** True when the member is marked private or matched by private filtering. */
   private?: boolean;
+  /** Additional tags preserved by tag name after known tags are normalized. */
   tags?: Record<string, string>;
+  /** 1-based start line of the member declaration. */
   line: number;
+  /** 1-based end line of the member declaration. */
   endLine: number;
 }
 /**
  * Parameter documentation.
  */
 interface ParamDoc {
+  /** Parameter name, including dotted names for destructured properties. */
   name: string;
+  /** Rendered TypeScript type text. */
   type: string;
+  /** Prose extracted from `@param` / `@arg` documentation. */
   description: string;
+  /** True when the parameter is optional. */
   optional?: boolean;
+  /** Default value extracted from syntax or `@default` tags. */
   default?: string;
 }
 /**
  * Return type documentation.
  */
 interface ReturnDoc {
+  /** Rendered TypeScript type text for the return value. */
   type: string;
+  /** Prose extracted from `@returns` / `@return` documentation. */
   description: string;
 }
 /**
  * Extracted documentation for a single file.
  */
 interface ExtractedDocs {
+  /** Source module or file identifier used by generated output. */
   file: string;
+  /** Optional module-level description extracted from a file header comment. */
   description?: string;
+  /** Absolute source path, when available for source links and diagnostics. */
   sourcePath?: string;
+  /** Module-level examples collected from a file header comment. */
   examples?: string[];
+  /** Module-level tags preserved by tag name. */
   tags?: Record<string, string>;
+  /** Top-level documented declarations found in this module. */
   entries: DocEntry[];
 }
 /**
  * Summary counts emitted with generated documentation data.
  */
 interface DocsSummary {
+  /** Number of modules included in the generated payload. */
   modules: number;
+  /** Number of top-level entries across all modules. */
   entries: number;
+  /** Entry counts grouped by normalized declaration kind. */
   byKind: Record<string, number>;
+  /** Number of documented parameters. */
   params: number;
+  /** Number of documented return values. */
   returns: number;
+  /** Number of collected examples. */
   examples: number;
+  /** Number of entries or members marked with `@deprecated`. */
   deprecated: number;
 }
 /**
  * Machine-readable payload emitted alongside generated docs.
  */
 interface GeneratedDocsData {
+  /** Payload schema version. Increment when the JSON shape changes incompatibly. */
   version: 1;
+  /** ISO timestamp for the generation run. */
   generatedAt: string;
+  /** Aggregate counts useful for dashboards and generated index pages. */
   summary: DocsSummary;
+  /** Extracted documentation modules in render order. */
   modules: ExtractedDocs[];
 }
 /**
  * Options for full-text search.
+ *
+ * Search indexes are built from Markdown content at build time and loaded by
+ * the client runtime from `search-index.json`. Pass `false` to the top-level
+ * `search` option to disable both index generation and the virtual search
+ * module.
  */
 interface SearchOptions {
   /**
    * Enable search functionality.
+   *
+   * Set this to `false` when config merging requires an object shape but search
+   * should be disabled.
+   *
    * @default true
    */
   enabled?: boolean;
   /**
    * Maximum number of search results.
+   *
+   * This controls client-side result truncation, not the number of documents in
+   * the generated index.
+   *
    * @default 10
    */
   limit?: number;
   /**
    * Enable prefix matching for autocomplete.
+   *
+   * Prefix matching applies to the final query token, which keeps normal terms
+   * precise while still supporting typeahead-style interactions.
+   *
    * @default true
    */
   prefix?: boolean;
   /**
    * Placeholder text for the search input.
+   *
+   * This value is embedded in the virtual search module for UI consumers.
+   *
    * @default 'Search documentation...'
    */
   placeholder?: string;
   /**
    * Keyboard shortcut to focus search (without modifier).
+   *
+   * Use an empty string to let the UI opt out of registering a shortcut.
+   *
    * @default '/'
    */
   hotkey?: string;
@@ -1609,80 +2180,130 @@ interface ResolvedSearchOptions {
  * Search document structure.
  */
 interface SearchDocument {
+  /** Stable document identifier used by the search index. */
   id: string;
+  /** Human-readable document title. */
   title: string;
+  /** URL returned to search consumers. */
   url: string;
+  /** Plain-text body content used for scoring and snippets. */
   body: string;
+  /** Headings extracted from the document. */
   headings: string[];
+  /** Code block text extracted from the document. */
   code: string[];
 }
 /**
  * Search result structure.
  */
 interface SearchResult {
+  /** Matching document identifier. */
   id: string;
+  /** Matching document title. */
   title: string;
+  /** URL to open when the result is selected. */
   url: string;
+  /** Relevance score returned by the BM25 search engine. */
   score: number;
+  /** Query terms that matched the document. */
   matches: string[];
+  /** Context snippet with highlighted terms when available. */
   snippet: string;
+  /** Hierarchical scopes derived from the result URL or document id. */
   scopes?: string[];
 }
 /**
  * Parsed search query with optional scope prefixes.
  */
 interface ScopedSearchQuery {
+  /** Query text after `@scope` prefixes have been removed. */
   text: string;
+  /** Deduplicated lowercase scope prefixes requested by the query. */
   scopes: string[];
 }
 /**
  * Locale configuration.
+ *
+ * Locales define the routing and display metadata used by the i18n plugin.
  */
 interface LocaleConfig {
   /** BCP 47 locale tag (e.g., 'en', 'ja', 'zh-Hans'). */
   code: string;
   /** Display name for this locale (e.g., 'English', '日本語'). */
   name: string;
-  /** Text direction. @default 'ltr' */
+  /**
+   * Text direction for rendered pages.
+   *
+   * @default 'ltr'
+   */
   dir?: "ltr" | "rtl";
 }
 /**
  * i18n (internationalization) options.
+ *
+ * i18n is opt-in because it changes routing and build-time validation. Set
+ * `enabled: true` and configure at least `defaultLocale` / `locales` when the
+ * same content tree should serve multiple languages.
  */
 interface I18nOptions {
   /**
    * Enable i18n.
+   *
+   * The resolver returns `false` unless this is explicitly set to `true`.
+   *
    * @default false
    */
   enabled?: boolean;
   /**
    * Path to i18n dictionary directory (relative to project root).
+   *
+   * Dictionary files are watched in development and checked during builds when
+   * `check` is enabled.
+   *
    * @default 'content/i18n'
    */
   dir?: string;
   /**
    * Default locale tag.
+   *
+   * The default locale is added to `locales` automatically when omitted from the
+   * list.
+   *
    * @default 'en'
    */
   defaultLocale?: string;
   /**
    * Available locales.
+   *
+   * When omitted, ox-content creates a single locale from `defaultLocale`.
+   *
+   * @default [{ code: defaultLocale, name: defaultLocale }]
    */
   locales?: LocaleConfig[];
   /**
    * Hide default locale prefix in URLs.
+   *
    * When true, `/page` serves the default locale and `/ja/page` serves Japanese.
    * When false, all locales get prefixed: `/en/page`, `/ja/page`.
+   *
    * @default true
    */
   hideDefaultLocale?: boolean;
   /**
    * Run i18n checks during build.
+   *
+   * Checks validate dictionary coverage and translation function usage when the
+   * native i18n checker is available.
+   *
    * @default true
    */
   check?: boolean;
   /**
    * Translation function names to detect in source code.
+   *
+   * Add framework-specific wrappers here so build-time checks can find all
+   * translation keys.
+   *
    * @default ['t', '$t']
    */
   functionNames?: string[];
@@ -1732,23 +2353,48 @@ interface IncrementalMarkdownParserOptions {
    * @default true
    */
   gfm?: boolean;
-  /** Enable footnotes. */
+  /**
+   * Enable footnotes.
+   * @default true
+   */
   footnotes?: boolean;
-  /** Enable task list items. */
+  /**
+   * Enable task list items.
+   * @default true
+   */
   taskLists?: boolean;
-  /** Enable GFM tables. */
+  /**
+   * Enable GFM tables.
+   * @default true
+   */
   tables?: boolean;
-  /** Enable strikethrough. */
+  /**
+   * Enable strikethrough.
+   * @default true
+   */
   strikethrough?: boolean;
-  /** Enable Markdown autolinks. */
+  /**
+   * Enable Markdown autolinks.
+   * @default true
+   */
   autolinks?: boolean;
 }
 interface IncrementalMarkdownParseAppendOptions {
-  /** Commit the current chunk as the final stream input. */
+  /**
+   * Commit the current chunk as the final stream input.
+   * @default false
+   */
   final?: boolean;
-  /** Include a provisional AST for the current replaceable tail. */
+  /**
+   * Include a provisional AST for the current replaceable tail.
+   * The constructor-level value is reused when omitted on `append`.
+   * @default false
+   */
   includePendingAst?: boolean;
-  /** Temporarily close unmatched inline delimiters in the provisional AST. */
+  /**
+   * Temporarily close unmatched inline delimiters in the provisional AST.
+   * @default true
+   */
   completeInline?: boolean;
 }
 interface IncrementalMarkdownRendererOptions extends IncrementalMarkdownParserOptions {
@@ -1764,11 +2410,21 @@ interface IncrementalMarkdownRendererOptions extends IncrementalMarkdownParserOp
   completeInline?: boolean;
 }
 interface IncrementalMarkdownRenderAppendOptions {
-  /** Commit the current chunk as the final stream input. */
+  /**
+   * Commit the current chunk as the final stream input.
+   * @default false
+   */
   final?: boolean;
-  /** Render the unstable tail as replaceable provisional HTML. */
+  /**
+   * Render the unstable tail as replaceable provisional HTML.
+   * The constructor-level value is reused when omitted on `append`.
+   * @default true
+   */
   renderPending?: boolean;
-  /** Temporarily close unmatched inline delimiters in provisional HTML. */
+  /**
+   * Temporarily close unmatched inline delimiters in provisional HTML.
+   * @default true
+   */
   completeInline?: boolean;
 }
 type IncrementalMarkdownRenderResult = _$_ox_content_napi0.IncrementalMarkdownRenderResult;
@@ -1920,17 +2576,49 @@ interface CodeBlockDiagnostic {
   language?: string;
 }
 interface CodeBlockLintOptions$1 {
+  /**
+   * Languages to lint. Omit to lint every fenced block language.
+   * @default undefined
+   */
   languages?: string[];
+  /**
+   * Report fences without a language identifier.
+   * @default false
+   */
   requireLanguage?: boolean;
+  /**
+   * Report trailing whitespace in code block lines.
+   * @default true
+   */
   trailingSpaces?: boolean;
 }
 interface DocsTestOptions$1 {
+  /**
+   * Fence languages to collect as runnable examples.
+   * @default ['js', 'jsx', 'ts', 'tsx', 'mjs', 'mts']
+   */
   languages?: string[];
+  /**
+   * Require fence meta such as `test`, `runnable`, `vitest`, or `docs-test`.
+   * @default true
+   */
   requireMeta?: boolean;
 }
 interface TypecheckCodeBlockOptions {
+  /**
+   * Fence languages to type-check.
+   * @default ['ts', 'tsx']
+   */
   languages?: string[];
+  /**
+   * Require fence meta such as `typecheck`, `twoslash`, or `typecheck=...`.
+   * @default true
+   */
   requireMeta?: boolean;
+  /**
+   * Command used to run the TypeScript checker.
+   * @default 'tsgo'
+   */
   tsgoCommand?: string;
 }
 declare function extractCodeBlocks(source: string): Promise<ExtractedCodeBlock[]>;
@@ -2172,6 +2860,7 @@ interface MarkdownLintStandardDictionaryOptions {
    *
    * This can point at installed packages like
    * `@cspell/dict-fr-fr/cspell-ext.json` or local CSpell config files.
+   * @default []
    */
   imports?: string[];
   /**
@@ -2187,14 +2876,17 @@ interface MarkdownLintStandardDictionaryOptions {
 interface MarkdownLintDictionaryOptions {
   /**
    * Words ignored across all configured languages.
+   * @default []
    */
   words?: string[];
   /**
    * Extra words to allow per language.
+   * @default {}
    */
   byLanguage?: Partial<Record<MarkdownLintLanguage, string[]>>;
   /**
    * Words that should never produce diagnostics.
+   * @default []
    */
   ignoredWords?: string[];
   /**
@@ -2202,6 +2894,7 @@ interface MarkdownLintDictionaryOptions {
    *
    * By default the linter stays on a minimal built-in dictionary. Enable this
    * to load larger locale dictionaries from a standard external source.
+   * @default false
    */
   standard?: MarkdownLintStandardDictionaryOptions | false;
 }
@@ -2260,10 +2953,13 @@ interface MarkdownLintOptions {
   languages?: MarkdownLintLanguage[];
   /**
    * Rule configuration.
+   * Omitted fields use `MarkdownLintRuleOptions` defaults.
+   * @default {}
    */
   rules?: MarkdownLintRuleOptions;
   /**
    * Built-in and opt-in standard dictionary overrides.
+   * @default {}
    */
   dictionary?: MarkdownLintDictionaryOptions;
 }
@@ -2364,6 +3060,8 @@ interface MarkdownLintFileOptions extends MarkdownLintOptions {
   exclude?: string[];
   /**
    * Alias of `exclude`.
+   * When omitted, only `exclude` is used.
+   * @default undefined
    */
   ignore?: string[];
 }