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

package/index.d.ts

@@ -34,6 +34,17 @@ export declare class IncrementalMarkdownRenderer {
   get pendingMarkdown(): string
 }
 
+/**
+ * Splices the caller's highlighting back over the blocks
+ * `highlightHtmlCodeBlocks` left pending.
+ *
+ * `replacements` lines up with the `pending` list it returned: entry `i` is a
+ * full `<pre>` element for pending block `i`, or an empty string to leave that
+ * block as it is. This keeps a page that needs one exotic grammar off the
+ * HTML round trip, instead of surrendering the whole document for it.
+ */
+export declare function applyPendingHighlights(html: string, replacements: Array<string>): string
+
 /**
  * Builds a Markdown collection manifest directly from files on the Rust side.
  *
@@ -59,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>
@@ -85,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>
 
@@ -202,6 +216,36 @@ export declare function getSsgPageLocale(urlPath: string, defaultLocale: string,
 /** Converts a markdown file path to a relative SSG URL path. */
 export declare function getSsgUrlPath(inputPath: string, srcDir: string): string
 
+/**
+ * Highlights one fenced code block, returning the full `<pre>` element.
+ *
+ * Returns `null` when no grammar claims `lang`, which is the caller's signal
+ * to fall back — either to another highlighter or to emitting the code
+ * unhighlighted. Callers that want to decide before paying for the call can
+ * ask [`supports_highlight_language`] instead.
+ */
+export declare function highlightCodeBlock(code: string, lang: string): string | null
+
+/**
+ * Highlights every code block in a rendered document in one call.
+ *
+ * The alternative is walking the page through an HTML parser and serializer
+ * to find the blocks and splice results back, which on the documentation
+ * corpus costs an order of magnitude more than the highlighting itself.
+ */
+export declare function highlightHtmlCodeBlocks(html: string): JsHighlightedDocument
+
+/**
+ * Highlights a document off the main thread, so pages overlap.
+ *
+ * The synchronous binding holds the event loop for the whole pass, which
+ * makes a caller's concurrency worth nothing: `Promise.all` over the
+ * documentation corpus measures the same as awaiting the pages one at a
+ * time. Running the pass as a task lets a build that already asks for
+ * several pages at once actually get them at once.
+ */
+export declare function highlightHtmlCodeBlocksAsync(html: string): Promise<JsHighlightedDocument>
+
 /** Result of i18n checking. */
 export interface I18NCheckResult {
   /** All diagnostics. */
@@ -282,6 +326,12 @@ 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
+}
+
 /** Attribute syntax transform options. */
 export interface JsAttrsOptions {
   /**
@@ -292,6 +342,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
@@ -305,6 +365,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
@@ -379,6 +449,26 @@ 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
+}
+
 /** Normalized documentation entry used by generated API docs. */
 export interface JsDocEntry {
   name: string
@@ -774,6 +864,16 @@ export interface JsFeatureConfig {
   linkText?: string
 }
 
+/** Opt-in static `file-tree` fences. */
+export interface JsFileTreeOptions {
+  /**
+   * Enable `file-tree` fences.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 export interface JsFrameworkComponentIsland {
   name: string
   props: Record<string, any>
@@ -789,6 +889,16 @@ export interface JsGraphOptions {
   externalPackageSources?: Array<JsExternalPackageSource>
 }
 
+/** 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". */
@@ -839,6 +949,24 @@ export interface JsHeroNotice {
   body?: Array<string>
 }
 
+/** Result of highlighting every code block in a rendered document. */
+export interface JsHighlightedDocument {
+  /** The document with each handled block replaced. */
+  html: string
+  /**
+   * Languages of elements the native pass could not read, which means the
+   * caller's own highlighter has to produce the whole page. Non-empty
+   * leaves `html` untouched and `pending` empty.
+   */
+  skipped: Array<string>
+  /**
+   * Well-formed blocks whose language has no native grammar, in document
+   * order. Highlight each one and hand the results to
+   * `applyPendingHighlights`; they are still in `html`, unchanged.
+   */
+  pending: Array<JsPendingBlock>
+}
+
 /** Configuration for generated i18n runtime modules. */
 export interface JsI18NRuntimeConfig {
   /** Default locale tag. */
@@ -859,6 +987,38 @@ export interface JsI18NRuntimeLocale {
   dir?: 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. */
@@ -889,6 +1049,16 @@ 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
+}
+
 export interface JsMarkdownLintDiagnostic {
   ruleId: string
   severity: string
@@ -916,6 +1086,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 {
@@ -936,6 +1108,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 {
   /**
@@ -998,6 +1180,27 @@ export interface JsOgImageData {
   author?: 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.
  *
@@ -1010,6 +1213,12 @@ export interface JsParserOptions {
    * Default: `false`.
    */
   gfm?: boolean
+  /**
+   * Enable MDX JSX, ESM, and expression nodes.
+   *
+   * Default: `false`.
+   */
+  mdx?: boolean
   /**
    * Enable footnote references and definitions.
    *
@@ -1042,6 +1251,14 @@ export interface JsParserOptions {
   autolinks?: boolean
 }
 
+/** A block the native pass left for the caller's highlighter. */
+export interface JsPendingBlock {
+  /** The `language-…` class the block carries. */
+  language: string
+  /** The block's source text, already unescaped. */
+  source: string
+}
+
 /** Options for [`super::transform_pm_embeds`]. */
 export interface JsPmOptions {
   /**
@@ -1072,6 +1289,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
@@ -1130,6 +1375,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. */
@@ -1290,6 +1543,8 @@ export interface JsSsgConfig {
   siteName: string
   /** Base URL path. */
   base: string
+  /** Optional site-root href for breadcrumbs. */
+  breadcrumbRootHref?: string
   /** OG image URL. */
   ogImage?: string
   /** Theme configuration. */
@@ -1298,6 +1553,22 @@ export interface JsSsgConfig {
   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
 }
 
 /** Result of SSG shared asset extraction. */
@@ -1370,6 +1641,16 @@ export interface JsSsgPageData {
   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
 }
 
 /** Resolved SSG output and public route paths. */
@@ -1410,6 +1691,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. */
@@ -1421,6 +1707,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. */
@@ -1447,6 +1771,12 @@ 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
   /** Light mode colors. */
   colors?: JsThemeColors
   /** Dark mode colors. */
@@ -1459,6 +1789,10 @@ export interface JsThemeConfig {
   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. */
@@ -1554,6 +1888,12 @@ export interface JsTransformOptions {
    * Default: `false`.
    */
   gfm?: boolean
+  /**
+   * Enable MDX JSX, ESM, and expression nodes.
+   *
+   * Default: `false`.
+   */
+  mdx?: boolean
   /**
    * Enable footnote references and definitions.
    *
@@ -1715,6 +2055,54 @@ 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 `::: steps` ordered lists.
+   *
+   * Default: disabled.
+   */
+  steps?: JsStepsOptions
+  /**
+   * Opt-in `{badge:variant}` inline badges.
+   *
+   * Default: disabled.
+   */
+  badges?: JsBadgeOptions
+  /**
+   * Opt-in figures, captions, and lazy images.
+   *
+   * Default: disabled.
+   */
+  images?: JsImageOptions
+  /**
+   * 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
 }
 
 /** Type parameter documentation (`<T extends C = D>`) used by generated API docs. */
@@ -1819,6 +2207,9 @@ export interface Mf2ValidateResult {
   astJson?: string
 }
 
+/** Every language name and alias the native highlighter answers to. */
+export declare function nativeHighlightLanguages(): Array<string>
+
 /** Normalizes VitePress-specific frontmatter into ox-content's entry-page shape. */
 export declare function normalizeVitePressFrontmatter(frontmatter: any): any
 
@@ -1914,6 +2305,9 @@ export declare function sanitizeHtml(html: string, options?: JsSanitizeOptions |
  */
 export declare function searchIndex(indexJson: string, query: string, options?: JsSearchOptions | undefined | null): Array<JsSearchResult>
 
+/** Whether a fenced code block tagged `lang` will be highlighted natively. */
+export declare function supportsHighlightLanguage(lang: string): boolean
+
 /** Table of contents entry. */
 export interface TocEntry {
   /** Heading depth (1-6). */

package/index.js

@@ -197,6 +197,7 @@ 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;
@@ -209,6 +210,12 @@ module.exports.collectSearchMarkdownFiles = binding.collectSearchMarkdownFiles;
 module.exports.normalizeVitePressFrontmatter = binding.normalizeVitePressFrontmatter;
 module.exports.generateSsgHtml = binding.generateSsgHtml;
 module.exports.generateSsgBareHtml = binding.generateSsgBareHtml;
+module.exports.highlightCodeBlock = binding.highlightCodeBlock;
+module.exports.applyPendingHighlights = binding.applyPendingHighlights;
+module.exports.highlightHtmlCodeBlocks = binding.highlightHtmlCodeBlocks;
+module.exports.highlightHtmlCodeBlocksAsync = binding.highlightHtmlCodeBlocksAsync;
+module.exports.supportsHighlightLanguage = binding.supportsHighlightLanguage;
+module.exports.nativeHighlightLanguages = binding.nativeHighlightLanguages;
 module.exports.generateSsgBarePage = binding.generateSsgBarePage;
 module.exports.getGitLastUpdated = binding.getGitLastUpdated;
 module.exports.resolveSsgRoutePaths = binding.resolveSsgRoutePaths;

package/package.json

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