@ox-content/napi 3.0.0-alpha.10 → 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
 
@@ -192,6 +201,9 @@ export declare function generateSearchModule(optionsJson: string, indexPath: str
 /** 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
 
@@ -332,6 +344,9 @@ 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". */
@@ -487,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 {
   /**
@@ -507,6 +538,49 @@ 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 {
   /**
@@ -824,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 {
   /**
@@ -934,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 {
   /**
@@ -1384,6 +1535,78 @@ 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.
    *
@@ -1404,6 +1627,12 @@ export interface JsMediaEmbedsOptions {
   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 {
   /**
@@ -1488,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.
  *
@@ -1632,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 {
   /**
@@ -1696,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. */
@@ -1752,6 +2059,36 @@ export interface JsSectionIndexItem {
   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. */
@@ -2002,6 +2339,24 @@ export interface JsSsgPageData {
   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. */
 export interface JsSsgRoutePaths {
   /** HTML output file path. */
@@ -2534,6 +2889,12 @@ export interface JsTransformOptions {
    * Default: disabled.
    */
   timelines?: JsTimelineOptions
+  /**
+   * Opt-in static `::: if` / `::: else` conditional blocks.
+   *
+   * Default: disabled.
+   */
+  conditionalBlocks?: JsConditionalBlockOptions
   /**
    * Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks.
    *
@@ -2683,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
 
@@ -2699,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
 
@@ -2721,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. */
@@ -2756,6 +3130,9 @@ export declare function renderFrameworkComponentCode(html: string, target: strin
 /** 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. */
@@ -2770,6 +3147,9 @@ export declare function renderSsgSectionIndex(title: string, items: Array<JsSect
 /** 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
 
@@ -2809,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.
  *
@@ -2817,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
 

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;
@@ -221,6 +223,7 @@ 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;
@@ -243,4 +246,12 @@ 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.10",
+  "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.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"
+    "@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"
   }
 }