carta

A universal document converter written in Rust. Read a markup format, render it back out in another. A fast, lightweight reimplementation of pandoc.

[!WARNING] carta is still in active development. Not all of pandoc's formats and features are implemented yet and the API is still unstable.

Goals

Performance and a lightweight binary.
A developer-friendly library, with the CLI as a thin shell over it.
Feature parity with pandoc across all formats and extensions.

Status

carta already supports the most-used pandoc formats; the rest are in active development. STATUS.md has a per-format breakdown, extension coverage, and the full feature backlog.

Installation

Prebuilt binaries

Download the archive for your platform from the latest release. Builds are provided for Linux (x86-64 gnu and static musl, arm64), macOS (Intel and Apple Silicon), and Windows (x86-64).

With cargo-binstall installed, the matching prebuilt binary can be fetched directly:

cargo binstall carta

From crates.io

cargo install carta

This installs the carta binary. For a smaller build, pass --no-default-features with only the formats you need, e.g. --features cli,read-commonmark,write-html.

From source

git clone https://github.com/mfkrause/carta
cd carta
cargo build --release
# binary at target/release/carta

Usage

Command line

# CommonMark to HTML
carta -f commonmark -t html input.md -o output.html

# read from stdin, write to stdout
echo '# Hello' | carta -f commonmark -t html

# inspect the document model
carta -f commonmark -t json input.md

# standalone document with a table of contents and numbered sections
carta -f commonmark -t html -s --toc --number-sections input.md -o output.html

# discover what this build supports
carta --list-input-formats
carta --list-output-formats
carta --list-extensions=gfm

Library

use carta::{convert_text, ReaderOptions, WriterOptions};

let html = convert_text(
    "commonmark",
    "html",
    "# Hello, *world*",
    &ReaderOptions::default(),
    &WriterOptions::default(),
)?;

convert_text is the shortcut for text-to-text conversion. The general entry point is convert, which takes raw bytes and returns an Output that is text or bytes depending on the target format.

You can select formats at compile time via per-direction features to shrink the binary further.

cargo build -p carta --no-default-features --features read-commonmark,write-html

Development

cargo build                         # build the workspace
cargo nextest run --workspace       # run tests
cargo clippy --all-targets          # lint

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

The syntax-highlighting grammar files are third-party works that retain their own upstream licenses; see vendor/syntax-highlighting/ATTRIBUTION.md. Only permissively licensed grammars are compiled into carta. The remaining grammars (copyleft or unspecified licenses) ship through an optional feature.

carta-core 0.0.8