@ox-content/napi 2.88.0 → 2.90.0

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.
  *
@@ -178,6 +189,9 @@ export declare function generateSearchModuleFromOptions(options: JsSearchRuntime
 /** Generates a bare SSG HTML page without navigation or styles. */
 export declare function generateSsgBareHtml(content: string, title: string): string
 
+/** Generates a bare SSG HTML page carrying head metadata and injected markup. */
+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
 
@@ -199,6 +213,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. */
@@ -836,6 +880,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. */
@@ -1039,6 +1101,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 {
   /**
@@ -1250,6 +1320,37 @@ export interface JsSourceOrigin {
   column: number
 }
 
+/**
+ * Head metadata and injected markup for a bare SSG page.
+ *
+ * Every field is optional. A value with none of them set renders the same
+ * document bare mode emitted before any of this existed.
+ */
+export interface JsSsgBarePage {
+  /** Page title. */
+  title: string
+  /** Rendered page body. */
+  content: string
+  /** `lang` attribute. Defaults to `en`. */
+  lang?: string
+  /** `dir` attribute. Omitted when absent. */
+  dir?: string
+  /** Page description for `description` and the OG/Twitter variants. */
+  description?: string
+  /** Absolute page URL for `<link rel="canonical">` and `og:url`. */
+  canonicalUrl?: string
+  /** Site name for `og:site_name`. */
+  siteName?: string
+  /** Image URL for `og:image` and `twitter:image`. */
+  ogImage?: string
+  /** Raw markup appended to `<head>`. */
+  head?: string
+  /** Raw markup inserted directly after `<body>`. */
+  bodyStart?: string
+  /** Raw markup inserted directly before `</body>`. */
+  bodyEnd?: string
+}
+
 /** SSG configuration. */
 export interface JsSsgConfig {
   /** Site name. */
@@ -1785,6 +1886,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
 
@@ -1880,6 +1984,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

@@ -209,6 +209,13 @@ 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;
 module.exports.getSsgOutputPath = binding.getSsgOutputPath;

package/package.json

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