Get Started

Interactive online, readable offline

One of Carve's design principles: it targets the interactive web first. The Playground, live preview, and hydration extensions (Mermaid, D2, Graphviz, Vega-Lite, Chart.js, math, tabs, details) render rich, interactive output when JavaScript is present. But interactivity is an enhancement, never a requirement — Carve only ever emits the marker element, and the client library hydrates it.

With no JavaScript — RSS readers, email, curl, archived pages, PDF, Markdown or terminal exports — every construct degrades to self-describing semantic HTML: a mermaid fence renders as <pre class="mermaid"> showing its source, :::details is a native <details>, list-table is a real <table>, captions are <figure> / <figcaption>. The document is always whole; online just makes it richer.

1. Try it now — no install

The fastest path is the Playground: type Carve on the left, watch the HTML render live on the right. Nothing to set up.

Or skim the Cheat Sheet — the whole syntax fits on one page.

2. Render Carve in your project

There are three reference engines. All of them turn a Carve string into HTML and pass the shared Tier-1 corpus.

Published packages

The three reference engines are published: npm @markup-carve/carve, Packagist markup-carve/carve-php, and crates.io carve-lang. The install commands below use them.

JavaScript / TypeScript — carve-js

npm install @markup-carve/carve

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

const html = carveToHtml('/italic/, *bold*, and a heading')

carveToHtml is the one-call entry point; the package also exposes the AST (parse) and the Markdown / plain-text / ANSI renderers.

Rust — carve-rs

The Rust engine is a third reference-quality implementation — Tier-1 corpus passing — and ships a carve CLI tool.

cargo install carve-lang

# CLI: convert a .crv file to HTML
carve input.crv

Browser / Node via WebAssembly — carve-wasm

carve-wasm wraps carve-rs as a WebAssembly module, usable in the browser or any Node/Bun/Deno environment. It is early-stage; see the repository for the current API.

PHP — carve-php

composer require markup-carve/carve-php

use MarkupCarve\Carve\CarveConverter;

$html = (new CarveConverter())->convert('/italic/, *bold*, and a heading');

CarveConverter::convert() returns HTML; the package also ships parse() plus Markdown / plain-text / ANSI renderers and HTML/Markdown/Djot converters.

Language bindings

Higher-level wrappers built on carve-rs are available for other languages. Ruby is on RubyGems and Go is fetched by module path; Python is not on PyPI yet (install from Git).

Language	Project	Install
Python	carve-py	from Git (PyPI pending)
Ruby	carve-rb	gem install carve-lang
Go	carve-go	go get github.com/markup-carve/carve-go

The full ecosystem — editor integrations, framework plugins, and more — is listed on the Ecosystem page.

3. Learn the syntax

• Cheat Sheet — every construct, one scannable page.
• Examples — Carve source next to the exact HTML it produces.
• Formal Grammar — the normative block and inline grammar.
• Case Study — the design research the language grew out of (historical, not normative).

4. Core vs extensions

Almost everything you write is core (Tier-1): headings, lists, tables, links, code, math, footnotes, admonitions, attributes, and the rest of the cheat sheet. Core is on by default and renders identically across every implementation — no configuration, no plugins.

A few things are opt-in:

• Tier-2 — spec-defined but off by default, e.g. citations [@key], bare-URL autolinking, mention/tag → URL templates. Enable them in your processor.
• Tier-3 — per-implementation extensions, e.g. Mermaid diagrams, a collapsible details widget, list-table. Register the ones you want.

The :name[…] (inline) and ::: name (block) syntax is core, but whether a given name does something special depends on whether a handler is registered; an unknown one just renders as a plain span/div, so documents always stay readable. The full feature → tier table is the place to look up any feature.

Build your own parser

Carve's grammar is small and unambiguous. To implement it in another language, start from Build Your Own Implementation and the Formal Grammar.

File extension: .crv