# Getting started

> Install carta and run your first conversion.

carta reads a document in one markup format and writes it back out in another. It ships as a single binary.

Pre-1.0

carta is in active development. Some formats have known gaps and the library API is still unstable. The [compatibility page](/formats/) tracks what works today and what is missing per format.

## Install

* [Prebuilt](#tab-panel-8)
* [binstall](#tab-panel-9)
* [cargo](#tab-panel-10)
* [Source](#tab-panel-11)

Download the archive for your platform from the [latest release](https://github.com/mfkrause/carta/releases/latest). Builds are provided for Linux (x86-64 gnu, static musl, and arm64), macOS (Intel and Apple Silicon), and Windows (x86-64).

With [cargo-binstall](https://github.com/cargo-bins/cargo-binstall), the matching prebuilt binary is fetched directly:

```
cargo binstall carta
```

```
cargo install carta
```

This builds every format carta supports. To build a smaller binary, see [choosing formats at compile time](#choosing-formats-at-compile-time).

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

## Your first conversion

1. Convert a Markdown file to HTML:

   ```
   carta -f commonmark -t html input.md -o output.html
   ```

2. Or pipe through stdin and stdout, which is what carta does when no path is given:

   ```
   echo '# Hello' | carta -f commonmark -t html
   ```

3. Ask the build what it can do:

   ```
   carta --list-input-formats
   carta --list-output-formats
   carta --list-extensions=gfm
   ```

`-f`/`--from` and `-t`/`--to` name the source and target formats. Both accept extension toggles, so `-f markdown+hard_line_breaks-raw_html` reads Pandoc Markdown with hard line breaks on and raw HTML off.

## Standalone documents

By default carta emits a document fragment. `-s`/`--standalone` wraps it in the target format's scaffold, and the usual document switches work alongside it:

```
carta -f commonmark -t html -s --toc --number-sections input.md -o output.html
```

## Choosing formats at compile time

Each reader and writer sits behind its own Cargo feature (`read-*` and `write-*`). A build that names only the ones you need carries neither the code nor the dependencies of the rest:

```
cargo install carta --no-default-features --features cli,read-commonmark,write-html
```

The `full` feature, on by default, turns on every format.

## Where to go next

* [Formats](/formats/): what carta reads and writes, and the gaps that remain.
* [CLI](/cli/): every flag, grouped by task.
* [Library](/library/): using carta as a Rust dependency.