@markup-carve/carve weekly downloads statistics

carve-js

Reference TypeScript implementation of the Carve markup language. It implements Carve spec 0.1 and passes the shared specification corpus. Try it in the playground and review the versioning contract.

Install

npm install @markup-carve/carve

Node 20 or newer.

Render Carve

import { carveToHtml, carveToHtmlWithReport } from '@markup-carve/carve'

carveToHtml('# Hello\n\nThis is /italic/ and *bold*.')

The package also exports carveToMarkdown, carveToPlainText, and carveToAnsi. Lower-level parse, resolve, and render* functions expose the typed AST for inspection or transformation.

import { parse, renderHtml, resolve } from '@markup-carve/carve'

const document = resolve(parse(source))
const html = renderHtml(document)

Checked render functions report content omitted for the selected target and can throw before publishing a value:

const result = carveToHtmlWithReport('`x`{=latex}')
carveToHtmlWithReport('`x`{=latex}', { strictLosses: true })

See the full usage reference for checked output, custom renderers, symbols, profiles, and static output.

Straight quotes with smart typography

Pass { smartTypography: { quotes: false } } to carveToHtml, carveToMarkdown, carveToPlainText, or carveToAnsi to keep quote source runs, including apostrophes. Other smart substitutions still render as glyphs. An empty family object or { quotes: true } keeps the default output. false and 'source' still emit every source run. Parsing and heading IDs are unchanged; typed curly quotes and escapes keep their existing behavior.

Browser and CLI

The package works as an ES module, a browser bundle, or through the carve CLI:

npx carve README.crv
npx carve lint README.crv
npx carve fmt -w README.crv

# Align table pipes by Unicode display width when desired:
npx carve fmt --align-tables -w README.crv

See Browser use, Command line, and Integrations.

Migration and editing

HTML migration produces Carve with a structured fidelity report. Markdown, Djot, and BBCode importers return Carve source. Source-preserving patches let editors apply canonical formatting without replacing unrelated bytes.

Convert a Markdown directory with the installed CLI:

npx carve migrate --from markdown --directory docs --output docs-carve --check-loss

The command copies assets and writes docs-carve/migration-report.json with files that need review.

• Migration
• Djot image alternative text: multiline values and export diagnostics.
• HTML import
• Source-preserving patches
• Reversible patches
• AST sidecars

Includes

The parser leaves {{ path }} literal. Hosts opt into expandIncludes and supply a resolver, containment rules, and source identities. Included nodes retain their source identity for diagnostics and dependency tracking.

The complete API and include reference covers expansion, positioned warnings, resolver behavior, rendering parsed trees, and editor integrations.

Security

Raw HTML, custom renderers, symbols, and include resolvers cross different trust boundaries. Use profiles and safe rendering for untrusted documents, and do not treat symbol values or renderer output as escaped text. On the CLI use --safe; in the library set allowRawHtml: false and choose a profile. See Security.

Documentation

The docs/ directory covers extensions, accessibility linting, streaming, browser use, the CLI, migration, rendering, and integrations.

Development

Start with CONTRIBUTING.md for the toolchain, the test commands, and what a spec-affecting change involves. The development guide has the source map.

Whitespace and annotation offsets

An escaped space produces a non_breaking_space node. Preserved line-block columns use the same node. Text and verbatim values keep literal Unicode, including U+E000. HTML renders generated spaces as  ; Markdown uses U+00A0, and plain text and ANSI use ordinary spaces.

Annotation offsets count Unicode codepoints in the contract's fixed field order. They do not depend on JSON property insertion order or source positions. The shared annotation fixture covers image alt text, math, breaks and reversed ranges.

Table body partitions and source attributes are documented in Table source metadata.

Check table preservation…