@ox-content/napi 2.90.0 → 3.0.0-alpha.10

package/index.d.ts

@@ -70,7 +70,7 @@ export declare function buildSearchIndex(documents: Array<JsSearchDocument>): st
  * File discovery, Markdown parsing, search document extraction, and index
  * construction all run on the Rust side.
  */
-export declare function buildSearchIndexFromDirectory(srcDir: string, base: string, extensions: Array<string>): string
+export declare function buildSearchIndexFromDirectory(srcDir: string, base: string, extensions: Array<string>, options?: JsSearchIndexBuildOptions | undefined | null): string
 
 /** Builds SSG navigation groups from markdown files. */
 export declare function buildSsgNavItems(markdownFiles: Array<string>, srcDir: string, base: string, extension: string): Array<JsSsgNavGroup>
@@ -96,6 +96,9 @@ export declare function checkI18n(dictDir: string, usedKeys: Array<string>): I18
  */
 export declare function checkI18nProject(dictDir: string, srcDirs: Array<string>, functionNames: Array<string>, defaultLocale: string): I18NCheckResult
 
+/** Classifies already-parsed frontmatter JSON against publish-state options. */
+export declare function classifyPublishState(frontmatterJson: string, options?: JsPublishStateOptions | undefined | null): JsPublishDecision
+
 /** Collects source files for generated API documentation. */
 export declare function collectDocsSourceFiles(srcDir: string, include: Array<string>, exclude: Array<string>): Array<string>
 
@@ -180,6 +183,9 @@ export declare function generateI18nModule(dictDir: string, config: JsI18NRuntim
  */
 export declare function generateOgImageSvg(data: JsOgImageData, config?: JsOgImageConfig | undefined | null): string
 
+/** Generates static OpenAPI reference Markdown pages from local JSON/YAML files. */
+export declare function generateOpenApiDocs(inputs: Array<JsOpenApiDocsInput>, options?: JsOpenApiDocsOptions | undefined | null): JsGeneratedOpenApiDocs
+
 /** Generates the client-side search runtime module. */
 export declare function generateSearchModule(optionsJson: string, indexPath: string): string
 
@@ -193,7 +199,10 @@ export declare function generateSsgBareHtml(content: string, title: string): str
 export declare function generateSsgBarePage(page: JsSsgBarePage): string
 
 /** Generates SSG HTML page with navigation and search. */
-export declare function generateSsgHtml(pageData: JsSsgPageData, navGroups: Array<JsSsgNavGroup>, config: JsSsgConfig): string
+export declare function generateSsgHtml(pageData: JsSsgPageData, navGroups: Array<JsSsgNavGroup>, config: JsSsgConfig): JsSsgHtmlResult
+
+/** Returns unique git authors for a file. Empty when git is missing or fails. */
+export declare function getGitContributors(filePath: string, root?: string | undefined | null): Array<JsGitContributor>
 
 /** Returns the last git commit timestamp for a file in milliseconds. */
 export declare function getGitLastUpdated(filePath: string, root?: string | undefined | null): number | null
@@ -323,6 +332,34 @@ export interface IncrementalMarkdownRenderResult {
   errors: Array<string>
 }
 
+/** Opt-in skip link and print styles. Presence of the object enables the feature. */
+export interface JsA11y {
+  /** Override for the skip-link label. Empty / omitted uses "Skip to content". */
+  skipLinkLabel?: string
+}
+
+/** Opt-in abbreviation and glossary expansion. */
+export interface JsAbbreviationsOptions {
+  /**
+   * Enable `*[TERM]: expansion` and config-term rewriting.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Central glossary terms. Keys are matched with Unicode word boundaries.
+   *
+   * Default: `{}`.
+   */
+  terms?: Record<string, string>
+  /**
+   * Wrap only the first occurrence of each term.
+   *
+   * Default: `false` (every occurrence).
+   */
+  firstUseOnly?: boolean
+}
+
 /** Attribute syntax transform options. */
 export interface JsAttrsOptions {
   /**
@@ -333,6 +370,16 @@ export interface JsAttrsOptions {
   enabled?: boolean
 }
 
+/** Opt-in `{badge:variant}` inline badges. */
+export interface JsBadgeOptions {
+  /**
+   * Enable `{badge:variant}text{/badge}` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 export interface JsBuildCollectionManifestOptions {
   /** Source directory containing Markdown files. */
   srcDir: string
@@ -346,6 +393,16 @@ export interface JsBuildCollectionManifestOptions {
   transformOptions?: JsTransformOptions
 }
 
+/** Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks. */
+export interface JsCardOptions {
+  /**
+   * Enable card, link-card, and card-grid containers.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 /** Extracted fenced code block. */
 export interface JsCodeBlock {
   language: string
@@ -395,6 +452,16 @@ export interface JsCodeBlockLintOptions {
   trailingSpaces?: boolean
 }
 
+/** Opt-in `::: code-group` fence groups. */
+export interface JsCodeGroupOptions {
+  /**
+   * Enable VitePress-style `::: code-group` rewriting.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 /** Code import / snippet injection options. */
 export interface JsCodeImportOptions {
   /**
@@ -420,6 +487,58 @@ export interface JsCollectionDefinition {
   include: Array<string>
 }
 
+/** Opt-in `::: tip` custom containers. */
+export interface JsContainerOptions {
+  /**
+   * Enable `::: type` containers.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /** Extra or overriding container types. */
+  types?: Record<string, JsContainerTypeOptions>
+}
+
+/** Custom container transform options. */
+export interface JsContainerTypeOptions {
+  /** Title used when the opener does not set one. */
+  title?: string
+  /** `"details"` renders `<details>`/`<summary>`; anything else is a `<div>`. */
+  tag?: string
+}
+
+/** Opt-in static `csv-table` / `json-table` fences. */
+export interface JsDataTableOptions {
+  /**
+   * Enable `csv-table` and `json-table` fences.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Root directory used for `@/` and absolute data-table imports.
+   *
+   * Default: project root from the JavaScript caller.
+   */
+  rootDir?: string
+  /**
+   * What to do when an imported file is missing.
+   *
+   * Default: `"error"`.
+   */
+  missing?: string
+}
+
+/** Opt-in PHP Markdown Extra / mdBook-style definition lists. */
+export interface JsDefinitionListOptions {
+  /**
+   * Enable `Term` / `: definition` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 /** Normalized documentation entry used by generated API docs. */
 export interface JsDocEntry {
   name: string
@@ -815,6 +934,36 @@ export interface JsFeatureConfig {
   linkText?: string
 }
 
+/** Opt-in static `file-tree` fences. */
+export interface JsFileTreeOptions {
+  /**
+   * Enable `file-tree` fences.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Open directory `<details>` by default.
+   *
+   * Default: `true`.
+   */
+  defaultOpen?: boolean
+  /**
+   * Render folder and file icons.
+   *
+   * Default: `true`.
+   */
+  icons?: boolean
+  /** Trusted SVG markup or class tokens for collapsed folders. */
+  iconFolder?: string
+  /** Trusted SVG markup or class tokens for open folders. */
+  iconFolderOpen?: string
+  /** Trusted SVG markup or class tokens for files. */
+  iconFile?: string
+  /** Trusted SVG markup or class tokens keyed by file extension. */
+  iconFiles?: Record<string, string>
+}
+
 export interface JsFrameworkComponentIsland {
   name: string
   props: Record<string, any>
@@ -822,6 +971,22 @@ export interface JsFrameworkComponentIsland {
   content?: string
 }
 
+/** Generated OpenAPI Markdown pages and navigation metadata. */
+export interface JsGeneratedOpenApiDocs {
+  pages: Record<string, string>
+  nav: Array<JsDocsNavItem>
+}
+
+/** One unique git author returned by `getGitContributors`. */
+export interface JsGitContributor {
+  /** Author name from `%an`. */
+  name: string
+  /** Author email from `%ae`. Never rendered into `href`. */
+  email?: string
+  /** Number of commits attributed to this author on the file. */
+  commits?: number
+}
+
 /** Export graph resolution options. */
 export interface JsGraphOptions {
   root?: string
@@ -830,6 +995,22 @@ export interface JsGraphOptions {
   externalPackageSources?: Array<JsExternalPackageSource>
 }
 
+/** One page-head validation finding. */
+export interface JsHeadDiagnostic {
+  strict: boolean
+  message: string
+}
+
+/** Header nav link or dropdown. */
+export interface JsHeaderNavItem {
+  /** Display label. */
+  text: string
+  /** Link URL. */
+  link?: string
+  /** Dropdown children. */
+  items?: Array<JsHeaderNavItem>
+}
+
 /** Hero action for entry page. */
 export interface JsHeroAction {
   /** Button theme: "brand" or "alt". */
@@ -918,6 +1099,66 @@ export interface JsI18NRuntimeLocale {
   dir?: string
 }
 
+/** Opt-in static `::: gallery` image groups. */
+export interface JsImageGalleryOptions {
+  /**
+   * Enable static image gallery blocks.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Add `loading="lazy"` to images inside galleries.
+   *
+   * Default: follows `images.lazy`, or `true` when `images` is disabled.
+   */
+  lazy?: boolean
+  /**
+   * Validation mode for images with empty alt text.
+   *
+   * Default: `"error"`.
+   */
+  missingAlt?: string
+  /**
+   * Validation mode for galleries without image items.
+   *
+   * Default: `"error"`.
+   */
+  empty?: string
+}
+
+/** Opt-in figures, captions, and lazy images. */
+export interface JsImageOptions {
+  /**
+   * Enable figure captions, lazy loading, and safe dimensions.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Add `loading="lazy"` to transformed images.
+   *
+   * Default: `true`.
+   */
+  lazy?: boolean
+}
+
+/** Markdown file include options. */
+export interface JsIncludeOptions {
+  /**
+   * Enable `<!-- @include: PATH -->` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Root directory used for `@/` and absolute include paths.
+   *
+   * Default: project root from the JavaScript caller.
+   */
+  rootDir?: string
+}
+
 /** Options for appending to an incremental parser. */
 export interface JsIncrementalParseOptions {
   /** Treat this append as the final stream chunk. */
@@ -938,6 +1179,48 @@ export interface JsIncrementalRenderOptions {
   completeInline?: boolean
 }
 
+/** Opt-in JSON-LD structured data. Presence of the object enables the feature. */
+export interface JsJsonLd {
+  /** When false, omit BreadcrumbList even if a visible trail exists. */
+  breadcrumbs?: boolean
+  /** Optional publisher. Missing fields are not invented. */
+  publisher?: JsJsonLdPublisher
+  /** Site origin used for `@id` / `url`. */
+  siteUrl?: string
+  pageType?: string
+  graph?: Array<string>
+}
+
+/** Optional JSON-LD publisher. Only configured fields are emitted. */
+export interface JsJsonLdPublisher {
+  /** Organization name. */
+  name?: string
+  /** Organization URL. Unsafe schemes are dropped. */
+  url?: string
+}
+
+/** Opt-in `{kbd:...}` inline keyboard keys. */
+export interface JsKeyboardKeysOptions {
+  /**
+   * Enable `{kbd:Ctrl+K}` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Build-time key aliases. Keys are matched case-insensitively.
+   *
+   * Default: `{}`.
+   */
+  aliases?: Record<string, string>
+  /**
+   * Label style for built-in aliases: `"words"` or `"symbols"`.
+   *
+   * Default: `"words"`.
+   */
+  style?: string
+}
+
 /** Locale information for the locale switcher. */
 export interface JsLocaleInfo {
   /** BCP 47 locale tag. */
@@ -948,6 +1231,62 @@ export interface JsLocaleInfo {
   dir: string
 }
 
+/** Sibling page or locale-root href for one locale. */
+export interface JsLocalePath {
+  /** BCP 47 locale tag. */
+  code: string
+  /** Href of the same page in this locale, when that translation exists. */
+  href?: string
+  /** Locale home href used when `href` is missing. */
+  root?: string
+}
+
+/** One configured magic-link alias. */
+export interface JsMagicLinkAlias {
+  /** Absolute `http:` / `https:` URL. */
+  href: string
+  /** Optional display label. Defaults to the alias key. */
+  label?: string
+  /** Optional avatar or favicon URL. */
+  image?: string
+}
+
+/** Replace the resolved image for matching hrefs. */
+export interface JsMagicLinkImageOverride {
+  /** Exact href to replace. */
+  href?: string
+  /** Href prefix to replace. */
+  prefix?: string
+  /** Replacement image URL. Must be `http:` or `https:`. */
+  image: string
+}
+
+/** Opt-in `{link:...}` rich magic links. */
+export interface JsMagicLinkOptions {
+  /**
+   * Enable `{link:@user}`, `{link:alias}`, and `{link:label|url}`.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /** Named aliases mapped to href / label / image. */
+  aliases?: Record<string, JsMagicLinkAlias>
+  /**
+   * Emit a favicon URL for explicit links that have no image.
+   *
+   * Default: `false`. No transform-time network request.
+   */
+  favicon?: boolean
+  /**
+   * Favicon URL template with a `{host}` placeholder.
+   *
+   * Default: `https://{host}/favicon.ico` when `favicon` is true.
+   */
+  faviconTemplate?: string
+  /** Image replacements applied after alias / GitHub / favicon resolution. */
+  imageOverrides?: Array<JsMagicLinkImageOverride>
+}
+
 export interface JsMarkdownLintDiagnostic {
   ruleId: string
   severity: string
@@ -975,6 +1314,8 @@ export interface JsMarkdownLintOptions {
   languages?: Array<string>
   rules?: JsMarkdownLintRuleOptions
   dictionary?: JsMarkdownLintDictionaryOptions
+  /** Enable MDX-aware syntax masking while linting visible prose. */
+  mdx?: boolean
 }
 
 export interface JsMarkdownLintResult {
@@ -995,6 +1336,16 @@ export interface JsMarkdownLintRuleOptions {
   trailingSpaces?: boolean
 }
 
+/** Opt-in `$…$` inline and `$$…$$` block math. */
+export interface JsMathOptions {
+  /**
+   * Enable `$…$` inline and `$$…$$` block math.
+   *
+   * Default: `false` when the whole option is omitted; `true` when this object is present.
+   */
+  enabled?: boolean
+}
+
 /** Built-in media embed transform switches. */
 export interface JsMediaEmbedsOptions {
   /**
@@ -1003,6 +1354,18 @@ export interface JsMediaEmbedsOptions {
    * Default: `false`.
    */
   spotify?: boolean
+  /**
+   * Render `<AppleMusic>` embeds.
+   *
+   * Default: `false`.
+   */
+  appleMusic?: boolean
+  /**
+   * Render `<SpeakerDeck>` embeds.
+   *
+   * Default: `false`.
+   */
+  speakerDeck?: boolean
   /**
    * Render `<StackBlitz>` embeds.
    *
@@ -1027,6 +1390,40 @@ export interface JsMediaEmbedsOptions {
    * Default: `false`.
    */
   webContainer?: boolean
+  /**
+   * Render `<Audio>` native players.
+   *
+   * Default: `false`.
+   */
+  audio?: boolean
+  /**
+   * Render `<Video>` native players.
+   *
+   * Default: `false`.
+   */
+  video?: boolean
+}
+
+/** Opt-in `<NotByAI />` authorship badge. */
+export interface JsNotByAiOptions {
+  /**
+   * Enable `<NotByAI />` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Accessible label for the badge link.
+   *
+   * Default: `"Written by human, not by AI"`.
+   */
+  label?: string
+  /**
+   * Destination URL. Unsafe values fall back to `https://notbyai.fyi`.
+   *
+   * Default: `"https://notbyai.fyi"`.
+   */
+  href?: string
 }
 
 /** OG image configuration for JavaScript. */
@@ -1057,6 +1454,40 @@ export interface JsOgImageData {
   author?: string
 }
 
+/** One local OpenAPI file consumed by the generated docs pipeline. */
+export interface JsOpenApiDocsInput {
+  path: string
+  name?: string
+  failOnUnresolvedRefs?: boolean
+}
+
+/** Options shared by all OpenAPI docs inputs. */
+export interface JsOpenApiDocsOptions {
+  root?: string
+  basePath?: string
+}
+
+/** Per-page frontmatter chrome flags. */
+export interface JsPageChromeFlags {
+  sidebar?: boolean
+  outline?: boolean
+  aside?: boolean
+  footer?: boolean
+  navbar?: boolean
+  lastUpdated?: boolean
+  editLink?: boolean
+}
+
+/** Frontmatter override for one previous/next pager side. */
+export interface JsPagerOverride {
+  /** Hide this side when true. */
+  hidden?: boolean
+  /** Replacement title. */
+  text?: string
+  /** Replacement href. */
+  href?: string
+}
+
 /**
  * Parser options for JavaScript.
  *
@@ -1069,6 +1500,12 @@ export interface JsParserOptions {
    * Default: `false`.
    */
   gfm?: boolean
+  /**
+   * Enable MDX JSX, ESM, and expression nodes.
+   *
+   * Default: `false`.
+   */
+  mdx?: boolean
   /**
    * Enable footnote references and definitions.
    *
@@ -1101,6 +1538,34 @@ export interface JsParserOptions {
   autolinks?: boolean
 }
 
+/** Opt-in parameterized Markdown partials. */
+export interface JsPartialsOptions {
+  /**
+   * Enable `<!-- @partial: PATH k="v" -->` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Root directory used for `@/` and absolute partial paths.
+   *
+   * Default: project root from the JavaScript caller.
+   */
+  rootDir?: string
+  /**
+   * Directory used for bare partial names such as `install.md`.
+   *
+   * Default: `"_partials"`.
+   */
+  root?: string
+  /**
+   * Missing `{{ name }}` substitutions: `"literal"` (default) or `"error"`.
+   *
+   * Default: `"literal"`.
+   */
+  missing?: string
+}
+
 /** A block the native pass left for the caller's highlighter. */
 export interface JsPendingBlock {
   /** The `language-…` class the block carries. */
@@ -1139,6 +1604,34 @@ export interface JsPublicExport {
   source: JsExportSource
 }
 
+/** Whether a page should be written and listed. */
+export interface JsPublishDecision {
+  /** Write HTML for this page. */
+  output: boolean
+  /** Include the page in nav, sitemap, and search. */
+  listed: boolean
+}
+
+/** JavaScript publish-state options. */
+export interface JsPublishStateOptions {
+  /** When false, every page stays published and listed. */
+  enabled?: boolean
+  /** Injected ISO-8601 clock used for scheduled / expiry comparison. */
+  now?: string
+  /** Keep draft and not-yet-scheduled pages visible (dev preview). */
+  includeDrafts?: boolean
+}
+
+/** Opt-in reader chrome flags. Presence of the object enables the feature. */
+export interface JsReaderChrome {
+  /** Copy button on fenced code blocks. */
+  copy?: boolean
+  /** Icon and `rel` on outbound links. */
+  externalLinks?: boolean
+  /** Back-to-top control that appears after scroll. */
+  backToTop?: boolean
+}
+
 /** Resolved source module. */
 export interface JsResolvedModule {
   path: string
@@ -1197,6 +1690,14 @@ export interface JsSearchDocument {
   code: Array<string>
 }
 
+/** Optional filters for directory search-index construction. */
+export interface JsSearchIndexBuildOptions {
+  /** Publish-state filter applied while walking Markdown files. */
+  publishState?: JsPublishStateOptions
+  /** Explicit MDX parser override. When omitted, `.mdx` files enable MDX. */
+  mdx?: boolean
+}
+
 /** Search options for JavaScript. */
 export interface JsSearchOptions {
   /** Maximum number of results. */
@@ -1233,12 +1734,24 @@ export interface JsSearchRuntimeOptions {
   limit: number
   /** Enable prefix matching. */
   prefix: boolean
+  /** Enable fuzzy typo-tolerant matching. */
+  fuzzy: boolean
   /** Search input placeholder. */
   placeholder: string
   /** Keyboard shortcut to focus search. */
   hotkey: string
 }
 
+/** One child link on a generated section index. */
+export interface JsSectionIndexItem {
+  /** Visible title. Escaped in HTML. */
+  title: string
+  /** Destination. `javascript:` and other schemes are rejected. */
+  href: string
+  /** Optional card description. Escaped in HTML. */
+  description?: string
+}
+
 /** Custom social link for JavaScript. */
 export interface JsSocialLink {
   /** Icon label. */
@@ -1353,18 +1866,44 @@ export interface JsSsgBarePage {
 
 /** SSG configuration. */
 export interface JsSsgConfig {
-  /** Site name. */
   siteName: string
-  /** Base URL path. */
   base: string
-  /** OG image URL. */
+  breadcrumbRootHref?: string
   ogImage?: string
+  siteUrl?: string
+  headValidation?: string
   /** Theme configuration. */
   theme?: JsThemeConfig
   /** Current locale for this page. */
   locale?: string
   /** Available locales for locale switcher. */
   availableLocales?: Array<JsLocaleInfo>
+  /** When true, render previous/next page links after the article. */
+  pagination?: boolean
+  /** When true, render a breadcrumb trail above the article. */
+  breadcrumbs?: boolean
+  /** Opt-in copy, external-link, and back-to-top chrome. */
+  readerChrome?: JsReaderChrome
+  /** Opt-in header locale switcher. */
+  localeSwitcher?: boolean
+  /** Existing sibling hrefs and locale roots. */
+  localePaths?: Array<JsLocalePath>
+  /** Opt-in skip link and print styles. Presence enables the feature. */
+  a11y?: JsA11y
+  /** Opt-in team / members page. Omitted stays off. */
+  team?: JsTeamOptions
+  /** When true, honor per-page frontmatter chrome flags. */
+  pageChrome?: boolean
+  /** Opt-in JSON-LD structured data. Presence enables the feature. */
+  jsonLd?: JsJsonLd
+}
+
+/** One rendered git author on an SSG page. */
+export interface JsSsgContributor {
+  /** Display name. Escaped in HTML. */
+  name: string
+  /** Optional `https:` avatar URL. Emails are never accepted here. */
+  avatar?: string
 }
 
 /** Result of SSG shared asset extraction. */
@@ -1385,6 +1924,12 @@ export interface JsSsgGeneratedHtmlPage {
   html: string
 }
 
+/** Themed SSG HTML plus page-head diagnostics. */
+export interface JsSsgHtmlResult {
+  html: string
+  diagnostics: Array<JsHeadDiagnostic>
+}
+
 /** Navigation group for SSG. */
 export interface JsSsgNavGroup {
   /** Group title. */
@@ -1433,10 +1978,28 @@ export interface JsSsgPageData {
   toc: Array<TocEntry>
   /** Last updated timestamp in milliseconds since the Unix epoch. */
   lastUpdated?: number
+  /** Unique git authors for this page. Empty unless the site opted in. */
+  contributors?: Array<JsSsgContributor>
   /** URL path. */
   path: string
   /** Entry page configuration (if layout: entry). */
   entryPage?: JsEntryPageConfig
+  /** Frontmatter override for the previous-page link. */
+  prev?: JsPagerOverride
+  /** Frontmatter override for the next-page link. */
+  next?: JsPagerOverride
+  /** Frontmatter `breadcrumbs: false` hides the trail on this page. */
+  breadcrumbs?: boolean
+  /** Frontmatter `layout`. `team` renders member cards when the option is on. */
+  layout?: string
+  /** Per-page chrome flags. Honored only when page chrome is enabled. */
+  chrome?: JsPageChromeFlags
+  /** Frontmatter `robots`. */
+  robots?: string
+  /** Frontmatter `canonical`. */
+  canonical?: string
+  /** Companion `.md` URL when copy-as-markdown chrome is on. */
+  markdownSource?: string
 }
 
 /** Resolved SSG output and public route paths. */
@@ -1477,6 +2040,11 @@ export interface JsSsgSidebarItem {
   stickyCollapsed?: boolean
 }
 
+/** Opt-in `::: steps` wrappers. `enabled` defaults to `false`. */
+export interface JsStepsOptions {
+  enabled?: boolean
+}
+
 /** Result of [`super::transform_tabs_embeds`]. */
 export interface JsTabsTransformResult {
   /** HTML with every `<tabs>` block expanded. */
@@ -1488,6 +2056,44 @@ export interface JsTabsTransformResult {
   groupCount: number
 }
 
+/** One link on a team member card. */
+export interface JsTeamLink {
+  /** Visible label. */
+  label: string
+  /** Destination URL. */
+  href: string
+}
+
+/** One person on the team page. */
+export interface JsTeamMember {
+  /** Display name. */
+  name: string
+  /** Optional role or title. */
+  role?: string
+  /** Avatar URL. */
+  avatar?: string
+  /** Optional profile or social links. */
+  links?: Array<JsTeamLink>
+}
+
+/** Opt-in team / members page. Presence of the object enables the feature. */
+export interface JsTeamOptions {
+  /** When false, `layout: team` is ignored. */
+  enabled?: boolean
+  /** Members rendered as static cards. */
+  members?: Array<JsTeamMember>
+}
+
+/** Announcement bar for JavaScript. */
+export interface JsThemeAnnouncement {
+  /** Escaped bar text. */
+  text: string
+  /** Optional https or same-origin link. */
+  link?: string
+  /** localStorage key used to persist dismiss. */
+  dismissKey?: string
+}
+
 /** Theme colors for JavaScript. */
 export interface JsThemeColors {
   /** Primary accent color. */
@@ -1514,18 +2120,28 @@ export interface JsThemeColors {
 
 /** Theme configuration for JavaScript. */
 export interface JsThemeConfig {
+  /** Progressive cross-document transitions for same-origin MPA navigation. */
+  viewTransitions?: boolean
+  /** Right-hand "On this page" outline. Omitted and `false` hide it. */
+  aside?: boolean
+  /** Breadcrumb trail from the site root through sidebar ancestors. */
+  breadcrumbs?: boolean
+  /** Heading permalink visibility. `"hover"` or `"always"`. CSS only. */
+  headingPermalink?: string
   /** Light mode colors. */
   colors?: JsThemeColors
   /** Dark mode colors. */
   darkColors?: JsThemeColors
-  /** Font configuration. */
   fonts?: JsThemeFonts
   /** Entry page configuration. */
   entryPage?: JsThemeEntryPage
-  /** Layout configuration. */
   layout?: JsThemeLayout
   /** Header configuration. */
   header?: JsThemeHeader
+  /** Opt-in header nav items. */
+  nav?: Array<JsHeaderNavItem>
+  /** Opt-in announcement bar. */
+  announcement?: JsThemeAnnouncement
   /** Footer configuration. */
   footer?: JsThemeFooter
   /** Social links configuration. */
@@ -1608,6 +2224,40 @@ export interface JsThemeLayout {
   maxContentWidth?: string
 }
 
+/** Opt-in static `::: timeline` milestone lists. */
+export interface JsTimelineOptions {
+  /**
+   * Enable static timeline blocks.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Render timelines as ordered lists unless a block overrides it.
+   *
+   * Default: `true`.
+   */
+  ordered?: boolean
+  /**
+   * Validation mode for malformed dates.
+   *
+   * Default: `"error"`.
+   */
+  invalidDate?: string
+  /**
+   * Validation mode for unsupported item metadata.
+   *
+   * Default: `"error"`.
+   */
+  unknownMeta?: string
+  /**
+   * Validation mode for timeline blocks without items.
+   *
+   * Default: `"error"`.
+   */
+  empty?: string
+}
+
 /**
  * Transform options for JavaScript.
  *
@@ -1621,12 +2271,24 @@ export interface JsTransformOptions {
    * Default: `false`.
    */
   gfm?: boolean
+  /**
+   * Enable MDX JSX, ESM, and expression nodes.
+   *
+   * Default: `false`.
+   */
+  mdx?: boolean
   /**
    * Enable footnote references and definitions.
    *
    * Default: `false`, or `true` when `gfm` is `true`.
    */
   footnotes?: boolean
+  /**
+   * Render footnotes as a semantic ordered section with numeric markers.
+   *
+   * Default: `false`.
+   */
+  semanticFootnotes?: boolean
   /**
    * Enable GFM task-list item markers.
    *
@@ -1726,6 +2388,12 @@ export interface JsTransformOptions {
    * Default: `true`; ignored when [`Self::autolink_urls`] is off.
    */
   autolinkTargetBlank?: boolean
+  /**
+   * Opt-in visible heading permalinks (`<a class="header-anchor" href="#id">`).
+   *
+   * Default: disabled. Existing HTML stays unchanged until this is enabled.
+   */
+  headingPermalinks?: boolean
   /**
    * Opt-in Obsidian-style wiki links.
    *
@@ -1782,6 +2450,114 @@ export interface JsTransformOptions {
    * Default: disabled.
    */
   editThisPage?: JsEditThisPageOptions
+  /**
+   * Opt-in `::: tip` custom containers.
+   *
+   * Default: disabled.
+   */
+  containers?: JsContainerOptions
+  /**
+   * Opt-in Markdown file includes via `<!-- @include: PATH -->`.
+   *
+   * Default: disabled.
+   */
+  includes?: JsIncludeOptions
+  /**
+   * Opt-in parameterized Markdown partials via `<!-- @partial: PATH k="v" -->`.
+   *
+   * Default: disabled.
+   */
+  partials?: JsPartialsOptions
+  /**
+   * Opt-in `::: steps` ordered lists.
+   *
+   * Default: disabled.
+   */
+  steps?: JsStepsOptions
+  /**
+   * Opt-in `::: code-group` fence groups.
+   *
+   * Default: disabled.
+   */
+  codeGroups?: JsCodeGroupOptions
+  /**
+   * Opt-in `{badge:variant}` inline badges.
+   *
+   * Default: disabled.
+   */
+  badges?: JsBadgeOptions
+  /**
+   * Opt-in `<NotByAI />` authorship badge.
+   *
+   * Default: disabled.
+   */
+  notByAi?: JsNotByAiOptions
+  /**
+   * Opt-in `{kbd:...}` inline keyboard keys.
+   *
+   * Default: disabled.
+   */
+  keyboardKeys?: JsKeyboardKeysOptions
+  /**
+   * Opt-in abbreviation and glossary expansion.
+   *
+   * Default: disabled.
+   */
+  abbreviations?: JsAbbreviationsOptions
+  /**
+   * Opt-in PHP Markdown Extra / mdBook-style definition lists.
+   *
+   * Default: disabled.
+   */
+  definitionLists?: JsDefinitionListOptions
+  /**
+   * Opt-in `{link:...}` rich magic links.
+   *
+   * Default: disabled.
+   */
+  magicLinks?: JsMagicLinkOptions
+  /**
+   * Opt-in figures, captions, and lazy images.
+   *
+   * Default: disabled.
+   */
+  images?: JsImageOptions
+  /**
+   * Opt-in static `::: gallery` image groups.
+   *
+   * Default: disabled.
+   */
+  imageGalleries?: JsImageGalleryOptions
+  /**
+   * Opt-in static `::: timeline` milestone lists.
+   *
+   * Default: disabled.
+   */
+  timelines?: JsTimelineOptions
+  /**
+   * Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks.
+   *
+   * Default: disabled.
+   */
+  cards?: JsCardOptions
+  /**
+   * Opt-in `$…$` inline and `$$…$$` block math.
+   *
+   * Default: disabled.
+   */
+  math?: boolean | JsMathOptions
+  /**
+   * Opt-in static `file-tree` fences.
+   *
+   * Default: disabled.
+   */
+  fileTree?: JsFileTreeOptions
+  /**
+   * Opt-in static `csv-table` / `json-table` fences.
+   *
+   * Default: disabled.
+   */
+  dataTables?: JsDataTableOptions
 }
 
 /** Type parameter documentation (`<T extends C = D>`) used by generated API docs. */
@@ -1865,6 +2641,24 @@ export declare function loadDictionariesFlat(dir: string): Record<string, Record
 /** Returns true when a document belongs to at least one requested search scope. */
 export declare function matchesSearchScopes(id: string, url: string, scopes: Array<string>): boolean
 
+/** One `import` statement collected from MDX ESM. */
+export interface MdxImport {
+  /** Module specifier string. */
+  source: string
+  /** Bindings created by the import. */
+  specifiers: Array<MdxImportSpecifier>
+}
+
+/** How a specifier was imported. */
+export interface MdxImportSpecifier {
+  /** Imported name (`default`, `*`, or the named export). */
+  imported: string
+  /** Local binding name. */
+  local: string
+  /** `default`, `named`, or `namespace`. */
+  kind: 'default' | 'named' | 'namespace'
+}
+
 /** Restores code block metadata after JavaScript-side syntax highlighting. */
 export declare function mergeHighlightedCodeBlocks(originalHtml: string, highlightedHtml: string): string
 
@@ -1959,6 +2753,9 @@ export declare function render(astJson: string): RenderResult
  */
 export declare function renderFrameworkComponentCode(html: string, target: string, islands?: Array<JsFrameworkComponentIsland> | undefined | null, mode?: string | undefined | null): string
 
+/** Resolve Unhead-compatible page-head descriptors to HTML. */
+export declare function renderHead(inputJson: string): JsSsgHtmlResult
+
 /** Render result containing the HTML output. */
 export interface RenderResult {
   /** The rendered HTML. */
@@ -1967,6 +2764,9 @@ export interface RenderResult {
   errors: Array<string>
 }
 
+/** Renders escaped section-index listing HTML. Hostile hrefs are dropped. */
+export declare function renderSsgSectionIndex(title: string, items: Array<JsSectionIndexItem>, style: string): string
+
 /** Resolves manual SSG navigation groups. */
 export declare function resolveSsgNavigationGroups(navigation: Array<JsSsgNavigationGroup>, base: string, extension: string): Array<JsSsgNavGroup>
 
@@ -2033,7 +2833,7 @@ export declare function transformMermaid(html: string, mmdcPath: string): Mermai
  */
 export declare function transformPmEmbeds(html: string, startGroup: number, options?: JsPmOptions | undefined | null): JsPmTransformResult
 
-/** Transform result containing HTML, frontmatter, and TOC. */
+/** Transform result containing HTML, frontmatter, TOC, and MDX metadata. */
 export interface TransformResult {
   /** The rendered HTML. */
   html: string
@@ -2043,6 +2843,12 @@ export interface TransformResult {
   toc: Array<TocEntry>
   /** Parse/render errors, if any. */
   errors: Array<string>
+  /** MDX `import` statements (empty when MDX is off or no ESM nodes). */
+  imports: Array<MdxImport>
+  /** Export names from MDX ESM (empty when MDX is off or no exports). */
+  exports: Array<string>
+  /** Unique JSX component names in document order (empty when none). */
+  components: Array<string>
 }
 
 /**

package/index.js

@@ -191,12 +191,14 @@ module.exports.generateDocsNavCode = binding.generateDocsNavCode;
 module.exports.collectDocsSourceFiles = binding.collectDocsSourceFiles;
 module.exports.generateDocsDataJson = binding.generateDocsDataJson;
 module.exports.generateDocsMarkdown = binding.generateDocsMarkdown;
+module.exports.generateOpenApiDocs = binding.generateOpenApiDocs;
 module.exports.writeGeneratedDocs = binding.writeGeneratedDocs;
 module.exports.buildCollectionManifest = binding.buildCollectionManifest;
 module.exports.mergeHighlightedCodeBlocks = binding.mergeHighlightedCodeBlocks;
 module.exports.generateOgImageSvg = binding.generateOgImageSvg;
 module.exports.buildSearchIndex = binding.buildSearchIndex;
 module.exports.buildSearchIndexFromDirectory = binding.buildSearchIndexFromDirectory;
+module.exports.classifyPublishState = binding.classifyPublishState;
 module.exports.writeSearchIndex = binding.writeSearchIndex;
 module.exports.searchIndex = binding.searchIndex;
 module.exports.extractSearchContent = binding.extractSearchContent;
@@ -208,6 +210,7 @@ module.exports.generateSearchModuleFromOptions = binding.generateSearchModuleFro
 module.exports.collectSearchMarkdownFiles = binding.collectSearchMarkdownFiles;
 module.exports.normalizeVitePressFrontmatter = binding.normalizeVitePressFrontmatter;
 module.exports.generateSsgHtml = binding.generateSsgHtml;
+module.exports.renderHead = binding.renderHead;
 module.exports.generateSsgBareHtml = binding.generateSsgBareHtml;
 module.exports.highlightCodeBlock = binding.highlightCodeBlock;
 module.exports.applyPendingHighlights = binding.applyPendingHighlights;
@@ -217,6 +220,7 @@ module.exports.supportsHighlightLanguage = binding.supportsHighlightLanguage;
 module.exports.nativeHighlightLanguages = binding.nativeHighlightLanguages;
 module.exports.generateSsgBarePage = binding.generateSsgBarePage;
 module.exports.getGitLastUpdated = binding.getGitLastUpdated;
+module.exports.getGitContributors = binding.getGitContributors;
 module.exports.resolveSsgRoutePaths = binding.resolveSsgRoutePaths;
 module.exports.getSsgOutputPath = binding.getSsgOutputPath;
 module.exports.getSsgUrlPath = binding.getSsgUrlPath;
@@ -238,4 +242,5 @@ module.exports.checkI18n = binding.checkI18n;
 module.exports.checkI18nProject = binding.checkI18nProject;
 module.exports.extractTranslationKeys = binding.extractTranslationKeys;
 module.exports.renderFrameworkComponentCode = binding.renderFrameworkComponentCode;
+module.exports.renderSsgSectionIndex = binding.renderSsgSectionIndex;
 module.exports.escapeSvelteMarkup = binding.escapeSvelteMarkup;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ox-content/napi",
-  "version": "2.90.0",
+  "version": "3.0.0-alpha.10",
   "description": "Node.js bindings for Ox Content - High-performance Markdown parser",
   "keywords": [
     "markdown",
@@ -47,12 +47,12 @@
     ]
   },
   "optionalDependencies": {
-    "@ox-content/binding-darwin-x64": "2.90.0",
-    "@ox-content/binding-darwin-arm64": "2.90.0",
-    "@ox-content/binding-linux-x64-gnu": "2.90.0",
-    "@ox-content/binding-linux-x64-musl": "2.90.0",
-    "@ox-content/binding-linux-arm64-gnu": "2.90.0",
-    "@ox-content/binding-linux-arm64-musl": "2.90.0",
-    "@ox-content/binding-win32-x64-msvc": "2.90.0"
+    "@ox-content/binding-darwin-x64": "3.0.0-alpha.10",
+    "@ox-content/binding-darwin-arm64": "3.0.0-alpha.10",
+    "@ox-content/binding-linux-x64-gnu": "3.0.0-alpha.10",
+    "@ox-content/binding-linux-x64-musl": "3.0.0-alpha.10",
+    "@ox-content/binding-linux-arm64-gnu": "3.0.0-alpha.10",
+    "@ox-content/binding-linux-arm64-musl": "3.0.0-alpha.10",
+    "@ox-content/binding-win32-x64-msvc": "3.0.0-alpha.10"
   }
 }