README

Grammars for the Carve markup language:

a Tiptap integration (editor kit, Carve loader and serializer) that converts between Carve markup and Tiptap/ProseMirror JSON;
Prism and highlight.js syntax-highlighting grammars for rendering Carve source on the web;
a TextMate grammar (textmate/carve.tmLanguage.json) for TextMate-based highlighters such as Shiki (used by VitePress).

Modeled on djot-grammars, adapted to Carve's syntax. The Tiptap mark mapping mirrors carve-php's HtmlToCarve converter; the highlighting grammars mirror the canonical token set in carve/resources/grammar.ebnf and the TextMate grammar in vscode-carve.

Status: Tiptap integration, plus Prism, highlight.js and TextMate grammars. Sibling editor grammars live in their own repos: editor-bundled TextMate copies in vscode-carve and intellij-carve; Tree-sitter in tree-sitter-carve and zed-carve.

Install

npm install @markup-carve/carve-grammars

All peer dependencies are optional - install only what you use: @tiptap/core + @tiptap/starter-kit (v2 or v3) for the editor, prismjs (v1) for Prism, highlight.js (v11) for highlight.js. CI runs the suite against both Tiptap majors.

On Tiptap 3, CarveKit disables StarterKit's bundled Underline and Link, since it registers its own (underline carries Carve's _text_ mapping). Pass starterKit: { underline: true } to opt back in, at the cost of a duplicate mark name.

CarveKit also pulls in several standalone Tiptap marks/extensions (highlight, subscript, superscript, underline, link, image, table, task-list); install the @tiptap/extension-* packages you use, or disable them via CarveKit.configure({ underline: false, ... }).

Usage

import { Editor } from '@tiptap/core'
import { CarveKit, serializeToCarve } from '@markup-carve/carve-grammars/tiptap'

const editor = new Editor({
  element: document.getElementById('editor'),
  extensions: [CarveKit],
  onUpdate: ({ editor }) => {
    const carve = serializeToCarve(editor.getJSON())
    console.log(carve)
  },
})

Individual extensions

import StarterKit from '@tiptap/starter-kit'
import { CarveInsert, CarveDelete, CarveDiv, serializeToCarve } from '@markup-carve/carve-grammars/tiptap'

const editor = new Editor({
  extensions: [StarterKit, CarveInsert, CarveDelete, CarveDiv],
})

Mark mapping

Tiptap mark	Carve token	Renders as
bold	`text` / `{text}`	`<strong>`
italic	`/text/` / `{/text/}`	`<em>`
underline	`_text_` / `{_text_}`	`<u>`
code	`text`	`<code>`
highlight	`=text=` / `{=text=}`	`<mark>`
strike	`~text~` / `{~text~}`	`<s>`
subscript	`{,text,}` (braced only)	`<sub>`
superscript	`{^text^}` (braced only)	`<sup>`
insert	`{+text+}`	`<ins>`
delete	`{-text-}`	`<del>`
link	`[text](url)` / `[text](url "title")`	`<a>`
image	`![alt](src)` / `![alt](src "title")`	`<img>`
span	`[text]{.class}`	`<span class>`
abbreviation	`[text]{abbr="..."}`	`<abbr title>` ***

*** [text]{abbr="..."} renders a real <abbr title> only when carve's SemanticSpanExtension is enabled (the same opt-in extension also maps {kbd} -> <kbd>, {dfn} -> <dfn>, {samp} -> <samp>, {var} -> <var>). Without it, the attribute stays literal: <span abbr="...">. The mark's parseHTML reads back the <abbr title> form.

The tokens target carve-php's parser (the contract: serialized Carve must parse back to the same elements). Carve's inline syntax differs notably from Djot's: emphasis is /text/ (Djot uses _), _text_ is underline, ~text~ is strikethrough, highlight is =text=, and subscript/superscript are the braced {,text,} / {^text^} only (a bare , or ^ is literal text since carve #259).

Each single-char delimiter has two equivalent forms: a bare form (=text=) and a forced brace form ({=text=}) that also works intraword; both parse to the same element. The two columns above list bare / forced. serializeToCarve emits the bare form for * / _ ~ and the forced {…} form for = , ^ (round-trip-safe — those delimiters are likelier to be inert bare); {+…+} / {-…-} (insert / delete) have only the brace form, since + / - are not emphasis delimiters.

Escaping

To honor that round-trip contract, serializeToCarve escapes literal Carve syntax in plain text so it parses back as text rather than markup - inline code, links, footnotes, CriticMarkup, mentions/tags/emoji, and an emphasis delimiter appearing inside its own span. Escaping is contextual: Carve's flanking rules already make most lone delimiters inert (price * 2, intraword x_1, comma,, two, C:\path, a@b.com), so those stay clean. The same logic is exposed as escapeCarve(text).

Block elements

Headings (#), bullet / ordered / task lists, blockquotes (>), fenced code blocks (``` lang), horizontal rules (---), tables (with |= header cells and ^ / < row / column spans), container divs (::: class), and definition lists.

Loading Carve Into Tiptap

Use the AST loader when opening Carve source in an editor. It parses Carve with @markup-carve/carve and builds the ProseMirror JSON shape consumed by CarveKit, avoiding the lossy HTML pivot where attributes disappear unless a Tiptap extension happens to claim them during parseHTML.

import {
  CarveKit,
  carveToProseMirror,
  serializeToCarve,
} from '@markup-carve/carve-grammars/tiptap'

const content = carveToProseMirror(source, { unsupported: 'preserve' })

const editor = new Editor({
  extensions: [CarveKit],
  content,
})

const saved = serializeToCarve(editor.getJSON())

Entry points:

carveToProseMirror(source, options?) parses Carve source and returns a ProseMirror doc.
astToProseMirror(ast, options?) converts an already parsed Carve document AST.

Unsupported handling:

unsupported: 'throw' is the default. The loader throws UnsupportedNodeError instead of silently dropping content.
unsupported: 'preserve' maps an unsupported construct to the opaque carveUnsupported block node, carrying the original source in carveSource. serializeToCarve writes that source back verbatim, so a load/save pass keeps the document content even when the editor cannot model that construct.

The loader models only what CarveKit and serializeToCarve can represent. Known gaps that still stay unsupported or lossy include front matter, figures and captions, table captions and alignment markers, table span filler cells, reference-link definitions, cross references, inline/raw passthrough, line blocks, comments, symbols, smart-punctuation artifacts, and several source-layout edge cases. tiptap/schema-map.json is the public mapping authority; tests/lib/coverage.js records the current skip reasons.

Syntax highlighting

Render Carve source as highlighted HTML on the web. Both grammars cover the full Carve token set: headings, lists, tables, blockquotes, fenced/raw blocks, container divs, front matter and comments, plus inline emphasis (*bold* /italic/ _underline_ ~strike~ =highlight=, braced {^sup^} {,sub,}), code, links, images, spans, attributes, footnotes, math ($`x`), CriticMarkup ({+ins+} {-del-}), mentions, tags and emoji.

Prism

The grammar registers itself against the global Prism, so Prism must be global before the grammar module runs. Because static import statements are hoisted (they all evaluate before any top-level assignment), load the grammar with a dynamic import after assigning globalThis.Prism:

import Prism from 'prismjs'

globalThis.Prism = Prism                       // grammar reads the global Prism
await import('@markup-carve/carve-grammars/prism/carve.js')  // registers Prism.languages.carve

const html = Prism.highlight(source, Prism.languages.carve, 'carve')

In the browser, load prismjs first (it sets the global Prism), then load @markup-carve/carve-grammars/prism/carve.js.

highlight.js

import hljs from 'highlight.js'
import carve from '@markup-carve/carve-grammars/highlightjs/carve.js'

hljs.registerLanguage('carve', carve)
const { value } = hljs.highlight(source, { language: 'carve' })

Loaded as a classic <script> after highlight.js, it self-registers against the global hljs:

<script src="highlight.min.js"></script>
<script src="node_modules/@markup-carve/carve-grammars/highlightjs/carve.js"></script>
<script>hljs.highlightAll();</script>

Shiki / VitePress

@markup-carve/carve-grammars/shiki is the shared kit every Carve docs site uses, so highlighting stays identical across them: the TextMate grammar, GitHub light/dark themes extended with Carve scope colors, and a transformer + CSS pair that bridges what Shiki's HTML emitter cannot express (strikethrough, sub/superscript positioning, highlight background).

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { carveMarkdown } from '@markup-carve/carve-grammars/shiki'

export default defineConfig({
  markdown: {
    ...carveMarkdown(),
    // carveMarkdown({ light, dark, languages }) to override base themes
    // or register extra grammars
  },
})

// .vitepress/theme/index.ts
import '@markup-carve/carve-grammars/shiki/carve.css'

Named exports for other setups: carveGrammar, carveLightExtras / carveDarkExtras, carveLightTheme / carveDarkTheme, extendTheme, carveStylingTransformer.

Diagram rendering

Carve's FencedRenderExtension presets emit a <pre class="LANG">source</pre> hydration element; something on the client turns it into a diagram. Mermaid, WaveDrom, Vega-Lite and Chart each render once you load their browser library. For the rest, @markup-carve/carve-grammars/diagrams ships renderers:

Type	Renderer	Engine	Network
`graphviz` (`dot`)	`renderGraphvizDiagrams`	`@viz-js/viz` (WASM)	offline
`d2`	`renderD2Diagrams`	`@terrastruct/d2` (WASM)	offline
`plantuml` (`puml`)	`renderKrokiDiagrams`	a Kroki server	network

Graphviz and D2 render entirely in the browser - no server, no external call, works offline (in an IDE, behind a firewall, ...). The rendered SVG is placed in an inert <img> data URI (like the Kroki path), so even untrusted diagram source cannot run script or expose a javascript: link. The WASM libraries are optional peer dependencies, imported lazily only when a matching block is on the page:

import { renderGraphvizDiagrams } from '@markup-carve/carve-grammars/diagrams/graphviz'
import { renderD2Diagrams } from '@markup-carve/carve-grammars/diagrams/d2'

await renderGraphvizDiagrams(container)
await renderD2Diagrams(container)

renderDiagrams runs both (and PlantUML, when you opt in) in one call; each no-ops when its blocks are absent, so you pay nothing for the types not present:

import { renderDiagrams } from '@markup-carve/carve-grammars/diagrams'

await renderDiagrams(container)                       // graphviz + d2, offline
await renderDiagrams(container, { kroki: {} })        // + PlantUML via kroki.io
await renderDiagrams(container, { kroki: { server: 'https://kroki.internal' } })

PlantUML (Kroki)

PlantUML is the one preset with no practical in-browser renderer - its only pure-JS build is a multi-megabyte JVM-in-WASM. renderKrokiDiagrams renders it by POSTing the source to a Kroki server; the returned SVG rides in an <img> data URI (which cannot execute script). Idempotent, and dependency-free (plain-text POST, no deflate/base64).

⚠️ Privacy / GDPR. The default server is the public https://kroki.io, so the diagram source is sent to a third party outside your domain. For anything sensitive, or to stay offline, point server at a self-hosted or localhost Kroki so no data leaves your control - and disclose the external call to end users where required. Because of this, renderDiagrams leaves the Kroki step off unless you pass kroki.

import { renderKrokiDiagrams } from '@markup-carve/carve-grammars/diagrams/kroki'

await renderKrokiDiagrams(container, { server: 'https://kroki.internal' })

Options: server (default https://kroki.io), types (class → Kroki-type map, default KROKI_DIAGRAM_TYPES = plantuml/puml only; extend it to Kroki-render graphviz/d2 against a self-hosted server), onError, fetch.

When the diagram is rendered at build time (SSG) rather than in the browser, prefer the engine's static-render hook (carve-js renderers.plantuml, carve-php's own render pipeline) so the page ships finished SVG and needs no client JS at all.

API

renderDiagrams(container, options?) - render Graphviz + D2 (offline), and PlantUML via Kroki when options.kroki is set. See Diagram rendering.
renderGraphvizDiagrams(container, options?) / renderD2Diagrams(container, options?) - render graphviz/d2 blocks with the offline WASM engines.
renderKrokiDiagrams(container, options?) - render PlantUML (and any opted-in type) via a Kroki server; KROKI_DIAGRAM_TYPES is the default class→type map.
carveToProseMirror(source, options?) - parse Carve source and convert it to ProseMirror JSON. options.unsupported is 'throw' by default or 'preserve' for opaque source-preserving blocks.
astToProseMirror(ast, options?) - convert an existing @markup-carve/carve AST to ProseMirror JSON.
serializeToCarve(doc) - serialize an editor.getJSON() document to Carve markup.
escapeCarve(text) - contextually escape literal Carve syntax in a plain-text run so it round-trips as text (used internally by serializeToCarve).
CarveKit - the bundled Tiptap extension set.
Individual extensions: CarveInsert, CarveDelete, CarveCriticComment, CarveDiv, CarveSpan, CarveFootnote, CarveFootnoteDefinition, CarveMath, CarveEmbed, CarveAbbreviation, CarveDefinitionList, CarveUnsupported.

Schema map (for other engines)

tiptap/schema-map.json publishes the Carve-to-ProseMirror vocabulary as data, so an engine building a bridge in another language reads it instead of restating it:

import map from '@markup-carve/carve-grammars/tiptap/schema-map.json'

map.types.strong        // { kind: 'mark', pm: 'bold' }
map.types.list          // { kind: 'node', pm: ['bulletList', 'orderedList', 'taskList'], ... }
map.unmapped.figure     // 'figure / caption blocks are not modeled'

Every Carve node type appears exactly once, either in types with its ProseMirror name(s) or in unmapped with the reason it has none - the negative space is part of the contract, because a bridge that silently drops table alignment or figure captions is worse than one that says it cannot carry them.

tests/schema-map-test.js keeps it honest: every ProseMirror name must exist in the CarveKit schema with the declared node/mark kind, and every type in the pinned spec vocabulary must have a decision. Types the map covers ahead of the spec/ pin are declared explicitly and must be removed once the pin catches up.

Restating this mapping per engine is what the spec's own node-vocabulary test was written to prevent: carve-php once emitted citation-group while every other implementation spelled it with underscores.

Attributes, math and footnotes

Attributes - spans, headings and images serialize an id and class (and any extra non-structural attrs) as a {#id .class key="val"} block, e.g. [text]{#me .note}, ![alt](src){.wide}. Inline attrs trail their target; block attrs (headings) sit on the preceding line (strict djot), e.g. {#slug} then # Title.
Math - CarveMath (inline atom) serializes to $`x` and, with display: true, $$`x`. Math has no closing $ sentinel (grammar.ebnf PART 9 §18): the $ / $$ prefix opens a verbatim span and the backtick run ends it, which is what keeps currency like $5 literal.
Footnotes - CarveFootnote is the inline [^label] reference; CarveFootnoteDefinition is the matching body block, serialized as [^label]: body.

Tests

npm test

The suite holds all three grammars to one source of truth: the shared corpus from the markup-carve/carve spec, vendored as the spec/ git submodule (git submodule update --init).

npm run test:coverage - the coverage matrix. Each grammar (prism, highlightjs, tiptap) declares a covered-category set and a skip set (with a reason per skip); the test fails if the two do not partition every corpus category, so a new spec category forces a deliberate decision.
npm run test:snapshot - golden token snapshots. Each covered .crv is tokenized with Prism's and highlight.js's own tokenizers and the token stream (type + text) is compared against a committed golden in tests/snapshots/. Refresh intended changes with npm run snapshots:update.
npm run test:roundtrip - the Tiptap serializer round-trip. Each covered .crv runs parse -> ProseMirror JSON -> serializeToCarve -> parse and the two parsed ASTs must be identical, catching serializer drift. Categories the serializer cannot represent are skipped with a reason.

npm test runs all of the above plus the structural grammar and serializer unit tests. CI runs the same on Node 18, 20 and 22.

markup-carve / carve-grammars

Maintainers

Package info

Statistics

Security