markup-carve / carve-php

0.1.13 2026-10-18 01:19 UTC

Requires

• php: ^8.2

Requires (Dev)

• brianium/paratest: ^7.8
• nikic/php-fuzzer: ^0.0.11
• php-collective/code-sniffer: ^0.6.8
• phpstan/phpstan: ^2.1.32
• phpunit/phpunit: ^11.0 || ^12.0 || ^13.0

Suggests

• ext-dom: Required for HTML import and HTML heading-ID conversion.
• ext-intl: Recommended for heading-ID transliteration: enables ICU romanization of non-Latin scripts (e.g. CJK, Arabic). Without it, a baked map covers Latin/Cyrillic/punctuation identically and other scripts fall back to the generated `section` id.

MIT

• Mark Scherer
• PHP Collective (djot-php, upstream)

• parser
• markup
• djot
• carve

Published on Packagist.org on 2026-10-18 01:33 UTC

README

PHP parser and renderer for Carve, a lightweight markup language for readable source and structured documents.

Implements Carve spec 0.1 (see Versioning & Changelog).

Installation

composer require markup-carve/carve-php

HTML import and HTML heading-ID conversion require the PHP DOM extension (ext-dom). Core Carve parsing and rendering do not require it.

Usage

use MarkupCarve\Carve\CarveConverter;

$converter = new CarveConverter();
$html = $converter->convert('# Hello /Carve/');

The converter also renders Markdown, plain text and ANSI. PHP integration options are in the PHP guides.

Straight quotes with smart typography

Set SmartTypographyMode::QuotesSource with setSmartTypography() on an HTML, Markdown, plain-text, or ANSI renderer. It emits source runs for quotes and apostrophes while keeping other smart substitutions enabled. The CarveConverter constructor also accepts this mode as smartTypography. Glyph remains the default and Source still emits every source run. Parsing and heading IDs are unchanged; typed curly quotes and escapes keep their existing behavior. The CLI accepts --smart-typography quotes-source.

CLI

vendor/bin/carve README.crv > README.html   # render (HTML by default)
vendor/bin/carve --markdown README.crv      # or --plain, --ansi, --json
vendor/bin/carve lint README.crv            # report problems, change nothing
vendor/bin/carve migrate --from html p.html # convert into Carve
vendor/bin/carve migrate --from markdown --directory docs --output docs-carve --check-loss

The folder command copies assets and writes docs-carve/migration-report.json with files that need review. Copied assets keep their source permissions, and a converted file is never more readable than its Markdown source.

See the CLI guide for all subcommands and flags.

Sandbox

Try this implementation live in the Carve sandbox - explore syntax and extensions, inspect output, and share snippets via pastebin-style links. It also powers the wp-carve WordPress plugin.

Roundtrip HTML export writes structural carriers that the default HTML importer reads. Legacy stored-source attributes are consumed and never used as source.

Untrusted input

Use the safe rendering options for untrusted documents. They disable raw HTML passthrough and bound nesting depth.

Documentation

• Carve documentation: syntax, examples, optional features and format conversion.
• PHP guides: configuration, importers, output formats and editor integration.
• Djot image alternative text: multiline values and export diagnostics.
• Developer documentation: contributing, custom renderers, parser internals and benchmarks.
• Table source metadata: table body partitions and source attributes.