@ox-content/napi 3.0.0-alpha.1 → 3.0.0-alpha.11

package/index.d.ts

@@ -149,6 +149,12 @@ export declare function extractSsgTitle(content: string, frontmatterTitle?: stri
  */
 export declare function extractTranslationKeys(source: string, filePath: string, functionNames?: Array<string> | undefined | null): Array<I18NKeyUsage>
 
+/**
+ * Extracts a YouTube video id from a bare id or a watch / share / embed /
+ * shorts URL, returning `null` when the input names no video.
+ */
+export declare function extractYoutubeVideoId(input: string): string | null
+
 /** Formats a file or directory segment as an SSG title. */
 export declare function formatSsgTitle(name: string): string
 
@@ -172,6 +178,9 @@ export declare function generateDocsNavMetadata(files: Array<string>, basePath?:
  */
 export declare function generateDocsNavMetadataFromDocs(docs: Array<JsDocsMarkdownModule>, options?: JsDocsNavOptions | undefined | null): Array<JsDocsNavItem>
 
+/** Builds RSS / Atom / JSON Feed bodies without writing files. */
+export declare function generateFeedBodies(options: JsFeedsOptions, items: Array<JsFeedItem>): JsFeedsOutput
+
 /** Generates the `virtual:ox-content/i18n` runtime module. */
 export declare function generateI18nModule(dictDir: string, config: JsI18NRuntimeConfig): string
 
@@ -183,12 +192,18 @@ 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
 
 /** Generates the client-side search runtime module from typed options. */
 export declare function generateSearchModuleFromOptions(options: JsSearchRuntimeOptions, indexPath: string): string
 
+/** Builds `sitemap.xml`, `robots.txt`, and `llms.txt` bodies without writing files. */
+export declare function generateSiteMapBodies(options: JsSiteMapsOptions, pages: Array<JsSiteMapPage>): JsSiteMapsOutput
+
 /** Generates a bare SSG HTML page without navigation or styles. */
 export declare function generateSsgBareHtml(content: string, title: string): string
 
@@ -196,7 +211,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
@@ -326,12 +344,37 @@ export interface IncrementalMarkdownRenderResult {
   errors: Array<string>
 }
 
+/** Same-origin path check: leading `/`, not `//`, and no scheme. */
+export declare function isSafeRedirectDest(value: string): boolean
+
 /** 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 {
   /**
@@ -424,6 +467,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 {
   /**
@@ -449,6 +502,22 @@ export interface JsCollectionDefinition {
   include: Array<string>
 }
 
+/** Opt-in static `::: if` / `::: else` conditional blocks. */
+export interface JsConditionalBlockOptions {
+  /**
+   * Enable conditional block evaluation.
+   *
+   * Default: `true` when the options object is supplied.
+   */
+  enabled?: boolean
+  /**
+   * Build-time values available as `config.*` or bare identifiers.
+   *
+   * Default: `{}`.
+   */
+  values?: Record<string, any>
+}
+
 /** Opt-in `::: tip` custom containers. */
 export interface JsContainerOptions {
   /**
@@ -469,6 +538,81 @@ export interface JsContainerTypeOptions {
   tag?: string
 }
 
+/** One rule the document broke. */
+export interface JsCrossReferenceDiagnostic {
+  /** `"error"` or `"warn"`, as the options asked. */
+  policy: string
+  message: string
+}
+
+/** One numbered target the document defines. */
+export interface JsCrossReferenceEntry {
+  id: string
+  /** `"figure"`, `"table"`, or `"section"`. */
+  kind: string
+  number: string
+  label: string
+  text: string
+  href: string
+  title?: string
+}
+
+/** The word placed before each number, per kind. */
+export interface JsCrossReferenceLabels {
+  figure?: string
+  table?: string
+  section?: string
+}
+
+/** The annotated HTML, what it defined, and what it got wrong. */
+export interface JsCrossReferenceOutput {
+  html: string
+  references: Array<JsCrossReferenceEntry>
+  diagnostics: Array<JsCrossReferenceDiagnostic>
+}
+
+/** Switches and labels for the cross-reference pass. */
+export interface JsCrossReferencesOptions {
+  enabled: boolean
+  /** `"warn"` reports and carries on; anything else fails the build. */
+  missing?: string
+  duplicates?: string
+  mismatches?: string
+  labels?: JsCrossReferenceLabels
+}
+
+/** 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
@@ -754,6 +898,24 @@ export interface JsEditThisPageOptions {
   label?: string
 }
 
+/**
+ * Transform opt-in static media embed components in already-rendered HTML.
+ * One tag an enabled provider refused, and what the transform did instead.
+ */
+export interface JsEmbedDiagnostic {
+  /** Tag name as the provider registers it, for example `speakerdeck`. */
+  provider: string
+  /** The URL the tag carried, when it carried one worth naming. */
+  url?: string
+  /** 1-based line of the opening tag in the transformed HTML. */
+  line: number
+  /**
+   * `"linked"` when the tag became a plain link, `"kept"` when its markup
+   * was left as authored.
+   */
+  fallback: string
+}
+
 /** Emoji-shortcode transform options. */
 export interface JsEmojiShortcodeOptions {
   /**
@@ -864,6 +1026,65 @@ export interface JsFeatureConfig {
   linkText?: string
 }
 
+/** A file carried alongside a feed item. */
+export interface JsFeedAttachment {
+  url: string
+  mimeType?: string
+  title?: string
+  sizeInBytes?: number
+  durationInSeconds?: number
+}
+
+/** A person credited on a feed item. */
+export interface JsFeedAuthor {
+  name: string
+  url?: string
+}
+
+/** One collection entry considered for a feed. */
+export interface JsFeedItem {
+  title: string
+  description?: string
+  loc: string
+  date?: string
+  lastUpdated?: string
+  draft?: boolean
+  unlisted?: boolean
+  content?: string
+  id?: string
+  authors?: Array<JsFeedAuthor>
+  image?: string
+  attachments?: Array<JsFeedAttachment>
+  language?: string
+}
+
+/** Switches and site metadata for feed generation. */
+export interface JsFeedsOptions {
+  enabled: boolean
+  siteUrl?: string
+  siteName: string
+  siteDescription?: string
+  homePageUrl: string
+  rssUrl: string
+  atomUrl: string
+  jsonUrl: string
+  /** Any of `"rss"`, `"atom"`, `"json"`. Unknown names are ignored. */
+  formats: Array<string>
+  limit: number
+  language?: string
+  image?: string
+  favicon?: string
+  copyright?: string
+}
+
+/** Generated feed bodies, or a warning when generation is skipped. */
+export interface JsFeedsOutput {
+  rssXml?: string
+  atomXml?: string
+  jsonFeed?: string
+  warning?: string
+}
+
 /** Opt-in static `file-tree` fences. */
 export interface JsFileTreeOptions {
   /**
@@ -872,6 +1093,26 @@ export interface JsFileTreeOptions {
    * 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 {
@@ -881,6 +1122,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
@@ -889,6 +1146,12 @@ 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. */
@@ -987,6 +1250,34 @@ 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 {
   /**
@@ -1039,6 +1330,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. */
@@ -1059,6 +1392,52 @@ export interface JsLocalePath {
   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
@@ -1126,6 +1505,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.
    *
@@ -1144,12 +1535,124 @@ export interface JsMediaEmbedsOptions {
    * Default: `false`.
    */
   bluesky?: boolean
+  /**
+   * Render `<GoogleMaps>` static place cards.
+   *
+   * Default: `false`.
+   */
+  googleMaps?: boolean
+  /**
+   * Render `<Qiita>` static article cards.
+   *
+   * Default: `false`.
+   */
+  qiita?: boolean
+  /**
+   * Render `<Zenn>` static article cards.
+   *
+   * Default: `false`.
+   */
+  zenn?: boolean
+  /**
+   * Render package registry cards for npm, crates.io, PyPI, and Docker Hub.
+   *
+   * Default: `false`.
+   */
+  packageRegistry?: boolean
+  /**
+   * Render `<CodePen>`, `<JSFiddle>`, and `<Observable>` playground cards.
+   *
+   * Default: `false`.
+   */
+  playgrounds?: boolean
+  /**
+   * Render `<Vimeo>` video cards.
+   *
+   * Default: `false`.
+   */
+  vimeo?: boolean
+  /**
+   * Render `<Twitch>` video, clip, and channel cards.
+   *
+   * Default: `false`.
+   */
+  twitch?: boolean
+  /**
+   * Render `<Discord>` static invite/message cards.
+   *
+   * Default: `false`.
+   */
+  discord?: boolean
+  /**
+   * Render `<Fediverse>`, `<Mastodon>`, `<Misskey>`, and `<Mixi2>` static post cards.
+   *
+   * Default: `false`.
+   */
+  fediverse?: boolean
+  /**
+   * Render `<Facebook>` static post cards.
+   *
+   * Default: `false`.
+   */
+  facebook?: boolean
+  /**
+   * Render `<Threads>` static post cards.
+   *
+   * Default: `false`.
+   */
+  threads?: boolean
+  /**
+   * Render `<Instagram>` static post cards.
+   *
+   * Default: `false`.
+   */
+  instagram?: boolean
   /**
    * Render `<WebContainer>` lazy placeholder blocks.
    *
    * Default: `false`.
    */
   webContainer?: boolean
+  /**
+   * Render `<Audio>` native players.
+   *
+   * Default: `false`.
+   */
+  audio?: boolean
+  /**
+   * Render `<Video>` native players.
+   *
+   * Default: `false`.
+   */
+  video?: boolean
+}
+
+/** Rewritten HTML plus every tag an enabled provider refused. */
+export interface JsMediaEmbedsResult {
+  html: string
+  diagnostics: Array<JsEmbedDiagnostic>
+}
+
+/** 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. */
@@ -1180,6 +1683,19 @@ 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
@@ -1201,6 +1717,31 @@ export interface JsPagerOverride {
   href?: string
 }
 
+/**
+ * A feed date after parsing: the instant, its civil parts in UTC, and the two
+ * serializations the feed formats ask for.
+ */
+export interface JsParsedFeedDate {
+  /** Seconds since the Unix epoch. */
+  unix: number
+  /** Civil year in UTC. */
+  year: number
+  /** Civil month, 1-12. */
+  month: number
+  /** Civil day of month, 1-31. */
+  day: number
+  /** Hour, 0-23. */
+  hour: number
+  /** Minute, 0-59. */
+  minute: number
+  /** Second, 0-60. */
+  second: number
+  /** `YYYY-MM-DDTHH:MM:SSZ`, as Atom and JSON Feed want it. */
+  rfc3339: string
+  /** `Day, DD Mon YYYY HH:MM:SS +0000`, as RSS wants it. */
+  rfc822: string
+}
+
 /**
  * Parser options for JavaScript.
  *
@@ -1251,6 +1792,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. */
@@ -1317,12 +1886,63 @@ export interface JsReaderChrome {
   backToTop?: boolean
 }
 
+/** One planned static HTML redirect. */
+export interface JsRedirectEntry {
+  from: string
+  to: string
+  html: string
+  relativePath: string
+}
+
+/** One entry of the config rewrite map, in author order. */
+export interface JsRedirectMapEntry {
+  from: string
+  to: string
+}
+
+/** One page that other paths can redirect to. */
+export interface JsRedirectPage {
+  dest: string
+  aliases?: Array<string>
+  redirect?: string
+}
+
+/** Switches and the config rewrite map. */
+export interface JsRedirectsOptions {
+  enabled: boolean
+  map: Array<JsRedirectMapEntry>
+  netlify: boolean
+  headers: boolean
+  json: boolean
+  allowExternal: boolean
+  html: boolean
+  base?: string
+}
+
+/** Planned redirect pages and optional host files. */
+export interface JsRedirectsOutput {
+  pages: Array<JsRedirectEntry>
+  netlify?: string
+  headers?: string
+  json?: string
+}
+
 /** Resolved source module. */
 export interface JsResolvedModule {
   path: string
   exports: Array<JsPublicExport>
 }
 
+/** One page after cascade and optional permalink / slug rewriting. */
+export interface JsResolvedSsgRoutePage {
+  /** Source path relative to the content root. */
+  source: string
+  /** Resolved URL path. */
+  urlPath: string
+  /** Frontmatter after cascade fills. */
+  frontmatter: Record<string, unknown>
+}
+
 /** HTML sanitizer options. */
 export interface JsSanitizeOptions {
   /**
@@ -1381,6 +2001,8 @@ export interface JsSearchIndexBuildOptions {
   publishState?: JsPublishStateOptions
   /** Explicit MDX parser override. When omitted, `.mdx` files enable MDX. */
   mdx?: boolean
+  /** Conditional blocks are resolved before extracting searchable content. */
+  conditionalBlocks?: JsConditionalBlockOptions
 }
 
 /** Search options for JavaScript. */
@@ -1419,12 +2041,54 @@ 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
+}
+
+/** One page considered for the crawl manifests. */
+export interface JsSiteMapPage {
+  loc: string
+  title: string
+  description?: string
+  /** Source-file git commit time in milliseconds. `None` omits `<lastmod>`. */
+  lastUpdated?: number
+  draft?: boolean
+  unlisted?: boolean
+}
+
+/** Switches and site metadata for crawl-manifest generation. */
+export interface JsSiteMapsOptions {
+  enabled: boolean
+  siteUrl?: string
+  sitemapLoc: string
+  siteName: string
+  siteDescription?: string
+  robots: boolean
+  llms: boolean
+}
+
+/** Generated crawl-manifest bodies, or a warning when generation is skipped. */
+export interface JsSiteMapsOutput {
+  sitemapXml?: string
+  robotsTxt?: string
+  llmsTxt?: string
+  warning?: string
+}
+
 /** Custom social link for JavaScript. */
 export interface JsSocialLink {
   /** Icon label. */
@@ -1539,14 +2203,12 @@ export interface JsSsgBarePage {
 
 /** SSG configuration. */
 export interface JsSsgConfig {
-  /** Site name. */
   siteName: string
-  /** Base URL path. */
   base: string
-  /** Optional site-root href for breadcrumbs. */
   breadcrumbRootHref?: string
-  /** OG image URL. */
   ogImage?: string
+  siteUrl?: string
+  headValidation?: string
   /** Theme configuration. */
   theme?: JsThemeConfig
   /** Current locale for this page. */
@@ -1569,6 +2231,16 @@ export interface JsSsgConfig {
   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. */
@@ -1589,6 +2261,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. */
@@ -1637,6 +2315,8 @@ 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). */
@@ -1651,6 +2331,30 @@ export interface JsSsgPageData {
   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 page routes plus collision and rejection diagnostics. */
+export interface JsSsgPageRouteOutput {
+  /** Pages that still have a unique URL. */
+  pages: Array<JsResolvedSsgRoutePage>
+  /** Human-readable collision and rejection messages. */
+  errors: Array<string>
+}
+
+/** One page considered for cascade and permalink resolution. */
+export interface JsSsgRoutePageInput {
+  /** Source path relative to the content root. */
+  source: string
+  /** File-tree URL before permalink or slug rewriting. */
+  fileUrl: string
+  /** Parsed frontmatter object. */
+  frontmatter: Record<string, unknown>
 }
 
 /** Resolved SSG output and public route paths. */
@@ -1777,15 +2481,15 @@ export interface JsThemeConfig {
   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
@@ -1875,6 +2579,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.
  *
@@ -1900,6 +2638,12 @@ export interface JsTransformOptions {
    * 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.
    *
@@ -1999,6 +2743,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.
    *
@@ -2067,24 +2817,84 @@ export interface JsTransformOptions {
    * 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 static `::: if` / `::: else` conditional blocks.
+   *
+   * Default: disabled.
+   */
+  conditionalBlocks?: JsConditionalBlockOptions
   /**
    * Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks.
    *
@@ -2103,6 +2913,12 @@ export interface JsTransformOptions {
    * 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. */
@@ -2186,6 +3002,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
 
@@ -2210,6 +3044,9 @@ export interface Mf2ValidateResult {
 /** Every language name and alias the native highlighter answers to. */
 export declare function nativeHighlightLanguages(): Array<string>
 
+/** Strips a trailing slash except for `/`. Unsafe values return `None`. */
+export declare function normalizeRedirectPath(value: string): string | null
+
 /** Normalizes VitePress-specific frontmatter into ox-content's entry-page shape. */
 export declare function normalizeVitePressFrontmatter(frontmatter: any): any
 
@@ -2226,6 +3063,13 @@ export declare function parseAndRender(source: string, options?: JsParserOptions
 /** Parses Markdown and renders to HTML asynchronously (runs on worker thread). */
 export declare function parseAndRenderAsync(source: string, options?: JsParserOptions | undefined | null): Promise<unknown>
 
+/**
+ * Parses a feed date — an epoch seconds/milliseconds integer, or a civil
+ * date-time with an optional zone offset — returning `null` when the value
+ * names no instant.
+ */
+export declare function parseFeedDate(value?: string | undefined | null): JsParsedFeedDate | null
+
 /** Parses Markdown source into a raw mdast memory block for JavaScript-side deserialization. */
 export declare function parseMdastRaw(source: string, options?: JsParserOptions | undefined | null): Uint8Array
 
@@ -2248,6 +3092,9 @@ export declare function parseScopedSearchQuery(query: string): JsScopedSearchQue
  */
 export declare function parseTransferRaw(source: string, kind: string, options?: JsParserOptions | undefined | null): Uint8Array
 
+/** Plans redirect pages and host files without writing anything. */
+export declare function planRedirects(options: JsRedirectsOptions, pages: Array<JsRedirectPage>): JsRedirectsOutput
+
 /** Prepared Markdown source with parsed frontmatter. */
 export interface PreparedSourceResult {
   /** Markdown content after optional frontmatter removal. */
@@ -2280,6 +3127,12 @@ 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
+
+/** Static HTML redirect body. `dest` is escaped; callers still validate it. */
+export declare function renderRedirectHtml(dest: string): string
+
 /** Render result containing the HTML output. */
 export interface RenderResult {
   /** The rendered HTML. */
@@ -2288,9 +3141,15 @@ 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>
 
+/** Resolves permalink / slug routes and `_index` frontmatter cascade. */
+export declare function resolveSsgPageRoutes(pages: Array<JsSsgRoutePageInput>, permalinksEnabled: boolean, cascadeEnabled: boolean): JsSsgPageRouteOutput
+
 /** Resolves all output and public route paths for an SSG page. */
 export declare function resolveSsgRoutePaths(inputPath: string, srcDir: string, outDir: string, base: string, extension: string, siteUrl?: string | undefined | null): JsSsgRoutePaths
 
@@ -2330,6 +3189,9 @@ export declare function transform(source: string, options?: JsTransformOptions |
 /** Transforms Markdown source asynchronously (runs on worker thread). */
 export declare function transformAsync(source: string, options?: JsTransformOptions | undefined | null): Promise<unknown>
 
+/** Numbers headings, figures, and tables, and links `@id` references to them. */
+export declare function transformCrossReferences(html: string, options: JsCrossReferencesOptions): JsCrossReferenceOutput
+
 /**
  * Transforms Markdown into a raw mdast transfer buffer.
  *
@@ -2338,9 +3200,11 @@ export declare function transformAsync(source: string, options?: JsTransformOpti
  */
 export declare function transformMdastRaw(source: string, options?: JsTransformOptions | undefined | null): Uint8Array
 
-/** Transform opt-in static media embed components in already-rendered HTML. */
 export declare function transformMediaEmbeds(html: string, options?: JsMediaEmbedsOptions | undefined | null): string
 
+/** Rewrites embeds and reports the tags no provider would render. */
+export declare function transformMediaEmbedsWithDiagnostics(html: string, options?: JsMediaEmbedsOptions | undefined | null): JsMediaEmbedsResult
+
 /** Transforms mermaid code blocks in HTML to rendered SVG diagrams. */
 export declare function transformMermaid(html: string, mmdcPath: string): MermaidTransformResult
 
@@ -2354,7 +3218,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
@@ -2364,6 +3228,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

@@ -173,9 +173,11 @@ module.exports.transformAsync = binding.transformAsync;
 module.exports.transformMdastRaw = binding.transformMdastRaw;
 module.exports.sanitizeHtml = binding.sanitizeHtml;
 module.exports.transformMediaEmbeds = binding.transformMediaEmbeds;
+module.exports.transformMediaEmbedsWithDiagnostics = binding.transformMediaEmbedsWithDiagnostics;
 module.exports.transformPmEmbeds = binding.transformPmEmbeds;
 module.exports.transformTabsEmbeds = binding.transformTabsEmbeds;
 module.exports.transformYoutubeEmbeds = binding.transformYoutubeEmbeds;
+module.exports.extractYoutubeVideoId = binding.extractYoutubeVideoId;
 module.exports.extractCodeBlocks = binding.extractCodeBlocks;
 module.exports.lintCodeBlocks = binding.lintCodeBlocks;
 module.exports.extractDocsTests = binding.extractDocsTests;
@@ -191,6 +193,7 @@ 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;
@@ -209,6 +212,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;
@@ -218,6 +222,8 @@ 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.resolveSsgPageRoutes = binding.resolveSsgPageRoutes;
 module.exports.resolveSsgRoutePaths = binding.resolveSsgRoutePaths;
 module.exports.getSsgOutputPath = binding.getSsgOutputPath;
 module.exports.getSsgUrlPath = binding.getSsgUrlPath;
@@ -239,4 +245,13 @@ 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.parseFeedDate = binding.parseFeedDate;
+module.exports.generateFeedBodies = binding.generateFeedBodies;
+module.exports.transformCrossReferences = binding.transformCrossReferences;
+module.exports.planRedirects = binding.planRedirects;
+module.exports.renderRedirectHtml = binding.renderRedirectHtml;
+module.exports.isSafeRedirectDest = binding.isSafeRedirectDest;
+module.exports.normalizeRedirectPath = binding.normalizeRedirectPath;
+module.exports.generateSiteMapBodies = binding.generateSiteMapBodies;
 module.exports.escapeSvelteMarkup = binding.escapeSvelteMarkup;

package/package.json

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