@ox-content/napi 2.8.0 → 2.10.0

package/index.d.ts

@@ -7,6 +7,12 @@
  */
 export declare function buildSearchIndex(documents: Array<JsSearchDocument>): string
 
+/** Builds SSG navigation groups from markdown files. */
+export declare function buildSsgNavItems(markdownFiles: Array<string>, srcDir: string, base: string, extension: string): Array<JsSsgNavGroup>
+
+/** Builds SSG navigation groups from an explicit theme sidebar tree. */
+export declare function buildSsgThemeNavItems(sidebar: Array<JsSsgSidebarItem>, base: string, extension: string): Array<JsSsgNavGroup>
+
 /**
  * Runs i18n checks on dictionaries against used translation keys.
  *
@@ -15,6 +21,12 @@ export declare function buildSearchIndex(documents: Array<JsSearchDocument>): st
  */
 export declare function checkI18n(dictDir: string, usedKeys: Array<string>): I18NCheckResult
 
+/** Extracts shared CSS and JavaScript assets from generated SSG pages. */
+export declare function externalizeSsgAssets(pages: Array<JsSsgGeneratedHtmlPage>, outDir: string, base: string): JsSsgExternalizedAssets
+
+/** Extracts normalized documentation entries from a JavaScript/TypeScript file using Oxc. */
+export declare function extractFileDocEntries(filePath: string, includePrivate?: boolean | undefined | null): Array<JsDocEntry>
+
 /** Extracts documented declarations from a JavaScript/TypeScript file using Oxc. */
 export declare function extractFileDocs(filePath: string, includePrivate?: boolean | undefined | null): Array<JsSourceDocItem>
 
@@ -25,6 +37,9 @@ export declare function extractFileDocs(filePath: string, includePrivate?: boole
  */
 export declare function extractSearchContent(source: string, id: string, url: string, options?: JsParserOptions | undefined | null): JsSearchDocument
 
+/** Extracts a page title from frontmatter title or rendered HTML. */
+export declare function extractSsgTitle(content: string, frontmatterTitle?: string | undefined | null): string
+
 /**
  * Extracts translation keys from a TypeScript/JavaScript source string.
  *
@@ -32,6 +47,18 @@ export declare function extractSearchContent(source: string, id: string, url: st
  */
 export declare function extractTranslationKeys(source: string, filePath: string, functionNames?: Array<string> | undefined | null): Array<I18NKeyUsage>
 
+/** Formats a file or directory segment as an SSG title. */
+export declare function formatSsgTitle(name: string): string
+
+/** Generates TypeScript source code for documentation navigation metadata. */
+export declare function generateDocsNavCode(navItems: Array<JsDocsNavItem>, exportName?: string | undefined | null): string
+
+/** Generates sidebar navigation metadata from documentation file paths. */
+export declare function generateDocsNavMetadata(files: Array<string>, basePath?: string | undefined | null): Array<JsDocsNavItem>
+
+/** Generates the `virtual:ox-content/i18n` runtime module. */
+export declare function generateI18nModule(dictDir: string, config: JsI18NRuntimeConfig): string
+
 /**
  * Generates an OG image as SVG.
  *
@@ -40,12 +67,30 @@ export declare function extractTranslationKeys(source: string, filePath: string,
  */
 export declare function generateOgImageSvg(data: JsOgImageData, config?: JsOgImageConfig | undefined | null): string
 
+/** Generates the client-side search runtime module. */
+export declare function generateSearchModule(optionsJson: string, indexPath: string): string
+
 /** Generates SSG HTML page with navigation and search. */
 export declare function generateSsgHtml(pageData: JsSsgPageData, navGroups: Array<JsSsgNavGroup>, config: JsSsgConfig): string
 
 /** Returns the last git commit timestamp for a file in milliseconds. */
 export declare function getGitLastUpdated(filePath: string, root?: string | undefined | null): number | null
 
+/** Derives hierarchical search scopes from a document id or URL. */
+export declare function getSearchDocumentScopes(id: string, url: string): Array<string>
+
+/** Converts a markdown file path to an SSG href. */
+export declare function getSsgHref(inputPath: string, srcDir: string, base: string, extension: string): string
+
+/** Converts a markdown file path to its corresponding SSG HTML output path. */
+export declare function getSsgOutputPath(inputPath: string, srcDir: string, outDir: string, extension: string): string
+
+/** Resolves a page locale from an SSG URL path and configured locale codes. */
+export declare function getSsgPageLocale(urlPath: string, defaultLocale: string, localeCodes: Array<string>): string | null
+
+/** Converts a markdown file path to a relative SSG URL path. */
+export declare function getSsgUrlPath(inputPath: string, srcDir: string): string
+
 /** Result of i18n checking. */
 export interface I18NCheckResult {
   /** All diagnostics. */
@@ -92,6 +137,44 @@ export interface I18NLoadResult {
   errors: Array<string>
 }
 
+/** Normalized documentation entry used by generated API docs. */
+export interface JsDocEntry {
+  name: string
+  kind: string
+  description: string
+  params?: Array<JsDocParam>
+  returns?: JsDocReturn
+  examples?: Array<string>
+  tags?: Record<string, string>
+  private: boolean
+  file: string
+  line: number
+  endLine: number
+  signature?: string
+}
+
+/** Normalized parameter documentation used by generated API docs. */
+export interface JsDocParam {
+  name: string
+  type: string
+  description: string
+  optional?: boolean
+  default?: string
+}
+
+/** Normalized return documentation used by generated API docs. */
+export interface JsDocReturn {
+  type: string
+  description: string
+}
+
+/** Navigation item emitted for generated documentation. */
+export interface JsDocsNavItem {
+  title: string
+  path: string
+  children?: Array<JsDocsNavItem>
+}
+
 /** Entry page configuration. */
 export interface JsEntryPageConfig {
   /** Hero section. */
@@ -164,6 +247,26 @@ export interface JsHeroNotice {
   body?: Array<string>
 }
 
+/** Configuration for generated i18n runtime modules. */
+export interface JsI18NRuntimeConfig {
+  /** Default locale tag. */
+  defaultLocale: string
+  /** Available locales. */
+  locales: Array<JsI18NRuntimeLocale>
+  /** Whether URLs should omit the default locale prefix. */
+  hideDefaultLocale: boolean
+}
+
+/** Locale metadata for generated i18n runtime modules. */
+export interface JsI18NRuntimeLocale {
+  /** BCP 47 locale tag. */
+  code: string
+  /** Display name for this locale. */
+  name: string
+  /** Text direction. */
+  dir?: string
+}
+
 /** Locale information for the locale switcher. */
 export interface JsLocaleInfo {
   /** BCP 47 locale tag. */
@@ -265,6 +368,14 @@ export interface JsParserOptions {
   autolinks?: boolean
 }
 
+/** Search query split into free text and scope prefixes. */
+export interface JsScopedSearchQuery {
+  /** Free-text terms after removing scope prefixes. */
+  text: string
+  /** Deduplicated lowercase scopes. */
+  scopes: Array<string>
+}
+
 /** Search document for JavaScript. */
 export interface JsSearchDocument {
   /** Unique document identifier. */
@@ -309,18 +420,6 @@ export interface JsSearchResult {
   snippet: string
 }
 
-/** Social links for JavaScript. */
-export interface JsSocialLinks {
-  /** GitHub URL. */
-  github?: string
-  /** Twitter/X URL. */
-  twitter?: string
-  /** Discord URL. */
-  discord?: string
-  /** Custom social links. */
-  links?: Array<JsSocialLink>
-}
-
 /** Custom social link for JavaScript. */
 export interface JsSocialLink {
   /** Icon label. */
@@ -333,6 +432,18 @@ export interface JsSocialLink {
   ariaLabel?: string
 }
 
+/** Social links for JavaScript. */
+export interface JsSocialLinks {
+  /** GitHub URL. */
+  github?: string
+  /** Twitter/X URL. */
+  twitter?: string
+  /** Discord URL. */
+  discord?: string
+  /** Custom social links. */
+  links?: Array<JsSocialLink>
+}
+
 /** Source documentation item extracted from a JS/TS file. */
 export interface JsSourceDocItem {
   name: string
@@ -364,6 +475,12 @@ export interface JsSourceDocTag {
   value: string
 }
 
+/** Source preparation options for JavaScript. */
+export interface JsSourceOptions {
+  /** Parse YAML frontmatter before returning the content payload. */
+  frontmatter?: boolean
+}
+
 /** SSG configuration. */
 export interface JsSsgConfig {
   /** Site name. */
@@ -380,6 +497,24 @@ export interface JsSsgConfig {
   availableLocales?: Array<JsLocaleInfo>
 }
 
+/** Result of SSG shared asset extraction. */
+export interface JsSsgExternalizedAssets {
+  /** HTML pages with inline assets replaced. */
+  pages: Array<JsSsgGeneratedHtmlPage>
+  /** Extracted shared assets. */
+  assets: Array<JsSsgSharedAsset>
+}
+
+/** Generated SSG HTML page for shared asset extraction. */
+export interface JsSsgGeneratedHtmlPage {
+  /** Source Markdown path. */
+  inputPath: string
+  /** Output HTML path. */
+  outputPath: string
+  /** HTML content. */
+  html: string
+}
+
 /** Navigation group for SSG. */
 export interface JsSsgNavGroup {
   /** Group title. */
@@ -419,6 +554,42 @@ export interface JsSsgPageData {
   entryPage?: JsEntryPageConfig
 }
 
+/** Resolved SSG output and public route paths. */
+export interface JsSsgRoutePaths {
+  /** HTML output file path. */
+  outputPath: string
+  /** Route path without extension. */
+  urlPath: string
+  /** Public HTML href. */
+  href: string
+  /** OG image output file path. */
+  ogImagePath: string
+  /** OG image public URL. */
+  ogImageUrl: string
+}
+
+/** Shared SSG asset extracted from generated pages. */
+export interface JsSsgSharedAsset {
+  /** Output file path. */
+  outputPath: string
+  /** Public URL path used from HTML. */
+  publicPath: string
+  /** Asset content. */
+  content: string
+}
+
+/** Theme sidebar item for SSG navigation generation. */
+export interface JsSsgSidebarItem {
+  /** Display text. */
+  text?: string
+  /** Link URL or route path. */
+  link?: string
+  /** Child sidebar items. */
+  items?: Array<JsSsgSidebarItem>
+  /** Whether this group is collapsed by default. */
+  collapsed?: boolean
+}
+
 /** Theme colors for JavaScript. */
 export interface JsThemeColors {
   /** Primary accent color. */
@@ -551,6 +722,8 @@ export interface JsTransformOptions {
   strikethrough?: boolean
   /** Enable autolinks. */
   autolinks?: boolean
+  /** Parse YAML frontmatter before transforming. */
+  frontmatter?: boolean
   /** Maximum TOC depth (1-6). */
   tocMaxDepth?: number
   /** Convert `.md` links to `.html` links for SSG output. */
@@ -589,6 +762,9 @@ export declare function loadDictionaries(dir: string): I18NLoadResult
  */
 export declare function loadDictionariesFlat(dir: string): Record<string, Record<string, string>>
 
+/** 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
+
 /** Restores code block metadata after JavaScript-side syntax highlighting. */
 export declare function mergeHighlightedCodeBlocks(originalHtml: string, highlightedHtml: string): string
 
@@ -613,7 +789,7 @@ export interface Mf2ValidateResult {
 /**
  * Parses Markdown source into an AST.
  *
- * Returns the AST as a JSON string for zero-copy transfer to JavaScript.
+ * Returns the AST as a JSON string for compatibility-oriented JavaScript consumers.
  */
 export declare function parse(source: string, options?: JsParserOptions | undefined | null): ParseResult
 
@@ -623,6 +799,9 @@ 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 Markdown source into a raw mdast memory block for JavaScript-side deserialization. */
+export declare function parseMdastRaw(source: string, options?: JsParserOptions | undefined | null): Uint8Array
+
 /** Parse result containing the AST as JSON. */
 export interface ParseResult {
   /** The AST as a JSON string. */
@@ -631,6 +810,25 @@ export interface ParseResult {
   errors: Array<string>
 }
 
+/** Splits a search query into free-text terms and `@scope` prefixes. */
+export declare function parseScopedSearchQuery(query: string): JsScopedSearchQuery
+
+/**
+ * Parses Markdown source into a transfer buffer identified by payload kind.
+ *
+ * Today `mdast` is the primary supported payload. Future payload kinds such as
+ * markdown-it token streams will share the same transfer envelope.
+ */
+export declare function parseTransferRaw(source: string, kind: string, options?: JsParserOptions | undefined | null): Uint8Array
+
+/**
+ * Splits Markdown source into content and frontmatter in a raw transfer buffer.
+ *
+ * This is used by JavaScript-side markdown-it and custom unified parser paths so
+ * frontmatter stripping can stay on the Rust side even when parsing continues in JS.
+ */
+export declare function prepareSourceRaw(source: string, options?: JsSourceOptions | undefined | null): Uint8Array
+
 /** Renders an AST (provided as JSON) to HTML. */
 export declare function render(astJson: string): RenderResult
 
@@ -642,6 +840,9 @@ export interface RenderResult {
   errors: Array<string>
 }
 
+/** 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
+
 /**
  * Searches a serialized index.
  *
@@ -670,6 +871,14 @@ 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>
 
+/**
+ * Transforms Markdown into a raw mdast transfer buffer.
+ *
+ * This keeps frontmatter parsing and mdast generation on the Rust side and
+ * transfers a single external memory block to JavaScript for deserialization.
+ */
+export declare function transformMdastRaw(source: string, options?: JsTransformOptions | undefined | null): Uint8Array
+
 /**
  * Transforms mermaid code blocks in HTML to rendered SVG diagrams.
  *

package/index.js

@@ -70,6 +70,8 @@ const binding = loadBinding();
 // Export individual functions for ESM compatibility
 module.exports = binding;
 module.exports.parse = binding.parse;
+module.exports.parseTransferRaw = binding.parseTransferRaw;
+module.exports.parseMdastRaw = binding.parseMdastRaw;
 module.exports.parseAndRender = binding.parseAndRender;
 module.exports.parseAndRenderAsync = binding.parseAndRenderAsync;
 module.exports.lintMarkdown = binding.lintMarkdown;
@@ -79,14 +81,32 @@ module.exports.transform = binding.transform;
 module.exports.transformAsync = binding.transformAsync;
 module.exports.version = binding.version;
 module.exports.extractFileDocs = binding.extractFileDocs;
+module.exports.extractFileDocEntries = binding.extractFileDocEntries;
+module.exports.generateDocsNavMetadata = binding.generateDocsNavMetadata;
+module.exports.generateDocsNavCode = binding.generateDocsNavCode;
 module.exports.generateOgImageSvg = binding.generateOgImageSvg;
 module.exports.buildSearchIndex = binding.buildSearchIndex;
 module.exports.searchIndex = binding.searchIndex;
 module.exports.extractSearchContent = binding.extractSearchContent;
+module.exports.parseScopedSearchQuery = binding.parseScopedSearchQuery;
+module.exports.getSearchDocumentScopes = binding.getSearchDocumentScopes;
+module.exports.matchesSearchScopes = binding.matchesSearchScopes;
+module.exports.generateSearchModule = binding.generateSearchModule;
 module.exports.generateSsgHtml = binding.generateSsgHtml;
+module.exports.resolveSsgRoutePaths = binding.resolveSsgRoutePaths;
+module.exports.getSsgOutputPath = binding.getSsgOutputPath;
+module.exports.getSsgUrlPath = binding.getSsgUrlPath;
+module.exports.getSsgHref = binding.getSsgHref;
+module.exports.getSsgPageLocale = binding.getSsgPageLocale;
+module.exports.extractSsgTitle = binding.extractSsgTitle;
+module.exports.formatSsgTitle = binding.formatSsgTitle;
+module.exports.buildSsgNavItems = binding.buildSsgNavItems;
+module.exports.buildSsgThemeNavItems = binding.buildSsgThemeNavItems;
+module.exports.externalizeSsgAssets = binding.externalizeSsgAssets;
 module.exports.transformMermaid = binding.transformMermaid;
 module.exports.loadDictionaries = binding.loadDictionaries;
 module.exports.loadDictionariesFlat = binding.loadDictionariesFlat;
+module.exports.generateI18nModule = binding.generateI18nModule;
 module.exports.validateMf2 = binding.validateMf2;
 module.exports.checkI18n = binding.checkI18n;
 module.exports.extractTranslationKeys = binding.extractTranslationKeys;

package/package.json

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