cudoc

API reference

English | 한국어 · Usage guides

This reference describes the current implementation: public imports, option defaults, data contracts, side effects and internal processing.

For authoring documents and installing adapters, start with the usage guides. Supported versions says which of this reference is a compatibility promise and which describes how the current release works.

Reference pages

Each page owns one layer: the document model, the Node-side library and the host adapters.

Page Contents
Document APIs Syntax options, page metadata, compilation, semantic AST, presentation, rendering, sections and projection
Node APIs Collection, library files, embedding, reference checking, datasets, output safety, CLI and language server
Adapters remark, capture, host ordering, markdown-it tokens and HTML generation

Packages

Install only what your host needs. Every package is ESM and needs Node.js 22 or later. Each usage guide opens with the exact install line for its host.

Package Purpose
@cudoment/cudoc Shared document processing, compilation, queries, collection and datasets
cudoc-remark Connect remark and MDX pipelines
cudoc-docusaurus Docusaurus integration
cudoc-nextra Nextra integration
cudoc-markdown-it Connect markdown-it pipelines
cudoc-vitepress VitePress rendering and collection
cudoc-eleventy Eleventy rendering and collection
cudoc-export HTML (site, single pages, review pages), PDF and Word generation

Next.js needs no adapter package of its own. @next/mdx hands over the remark pipeline directly, and there is no native heading-id or table-of-contents pass to order cudoc against, so cudoc-remark with host: "next" is the whole integration. The Docusaurus and Nextra adapters exist because those hosts do have such a pass. → MDX hosts

Only the core package is scoped: cudoc was already taken on npm, so it publishes as @cudoment/cudoc.

Package boundaries

Each package owns one layer of the work:

The core has no React runtime dependency. React is used only by cudoc-remark/components, the named-component output. Import Node-only entry points from build scripts or server code, not client components.

Public entry points

Prefixes below are relative to @cudoment/cudoc unless a full package name is shown. The package exports are the authoritative import boundary.

Import Purpose Reference
@cudoment/cudoc, /ast, /syntax, /mdx AST validation, traversal, selectors and low-level construction Core helpers
/document Options and in-place normalization Document model
/markdown Standalone compilation Compilation
/render HAST and HTML rendering Rendering
/present Screen-only markup: code titles and tabs Presentation
/query, /sections Section selection, query helpers and page metadata Sections
/dataset Immutable projection Projection
/node/library Collect and load complete libraries Collection
/node/roots Source roots and library paths, without a compiler Collection
/node/resolve-embed Parse and resolve embed requests Embedding
/node/prepare-embeds Prepare/read build-time embed data Preparation
/node/watch Repeated, incremental collection Watching
/node/dataset Generate filtered AST directories Datasets
/node/check, /node/report Whole-library reference checking and its rendering Reference checking
/node/lsp Language server over stdio, as cudoc lsp runs it Language server
/node/local-target Resolve a local link or image to a document, file or URL Reference checking
/node/image-size Header-read pixel sizes of PNG, JPEG, GIF and BMP files Library files
/node/storage Filesystem and staged output helpers Storage
/embed, /node/export-ast, /node/load-ast-file, /node/paths Individual AST snapshots and path helpers Individual snapshots
/transforms/table-cell-list, /transforms/table-column-layout Low-level syntax transforms Core helpers
/styles.css Theme-aware callout, badge, tree, code, note and tab styles Host stylesheet
/paged Page-break and tree constants the paginated writers share Paginated output
cudoc-remark and its subpaths remark integration, capture, TOC and embed runtime remark
cudoc-docusaurus, cudoc-nextra Host plugin arrays MDX hosts
cudoc-markdown-it Shared markdown-it pipeline for host adapters markdown-it
cudoc-vitepress VitePress host definition and compiler VitePress and Eleventy
cudoc-eleventy Eleventy host definition, renderer and compiler VitePress and Eleventy
cudoc-export Site, PDF and Word builders, and the design tokens Export
cudoc-export/docx, /pdf, /print The Word writer, the PDF printer and the print-ready HTML Paginated output

Every package also exports ./package.json, so tools can read a package's manifest through its export map. /embed is an individual-snapshot Node barrel. It does not re-export the document-library or fenced-embed APIs. Import those from their listed node/* paths. /sections exports collectSections; /query also includes the lower-level lookup helpers.

Processing flow

A document flows from the configured compiler through normalization to the library, and from there to embedding and rendering or to dataset projection.

flowchart LR
  Source[Markdown or MDX] --> Compiler[Configured compiler]
  Compiler --> Normalize[Common document semantics]
  Normalize --> Library[AST and source snapshots]
  Library --> Embed[Select, replace and resolve embeds]
  Embed --> Render[Host or HTML rendering]
  Library --> Dataset[Immutable dataset projection]

Syntax-only rendering does not need library storage. Cross-document embedding uses the persisted library; source replacement recompiles original source with the original configuration. Host adapters must capture actual host processing rather than assume the standalone parser produces an identical result.

The same collected library can feed both the primary host and HTML export. HTML's library mode consumes prepared blocks without rerunning the host compiler or changing the shared files. See Export input paths and link policies.

Maintenance

Update the relevant reference page in the same change as a function, export, option, default, schema, diagnostic or pipeline change. Check the usage guides and runnable examples whenever a caller's workflow changes.

cudoc