---
title: Getting Started
---

## Installation

### From crates.io (Recommended)

Install panache with Cargo:

```bash
cargo install panache
```

### Pre-built Binaries

Download platform-specific binaries from the [releases
page](https://github.com/jolars/panache/releases):

- **Linux**: x86_64 and ARM64 (available as `.deb`, `.rpm`, or `.tar.gz`)
- **macOS**: Intel and Apple Silicon (`.tar.gz`)
- **Windows**: x86_64 (`.zip`)

#### Debian/Ubuntu

```bash
wget https://github.com/jolars/panache/releases/latest/download/panache_ <VERSION >_amd64.deb
sudo dpkg -i panache_*.deb
```

#### Fedora/RHEL/openSUSE

```bash
wget https://github.com/jolars/panache/releases/latest/download/panache- <VERSION >.x86_64.rpm
sudo rpm -i panache-*.rpm
```

### From Source

Clone the repository and build:

```bash
git clone https://github.com/jolars/panache.git
cd panache
cargo install --path .
```

### Verify Installation

Check that panache is installed correctly:

```bash
panache --version
```

## Basic Usage

### Formatting

#### Format files in place

By default, panache formats files in place when given file paths:

```bash
panache format document.qmd
```

Format multiple files:

```bash
panache format file1.md file2.qmd file3.Rmd
```

Format entire directories recursively:

```bash
panache format .
panache format docs/
```

#### Format from stdin to stdout

When reading from stdin, panache always writes to stdout:

```bash
cat document.qmd | panache format
```

Using input redirection:

```bash
panache format <document.qmd
```

Inline formatting with echo:

```bash
echo '# Heading' | panache format
```

#### Check formatting without changes

Check if files are already formatted. Exits with code 1 if formatting is needed,
0 if already formatted:

```bash
panache format --check document.qmd
```

This is useful in CI/CD pipelines to enforce formatting:

```bash
panache format --check .
```

### Linting

#### Check for correctness issues

Lint a file to check for semantic problems like heading hierarchy issues, broken
references, and syntax errors:

```bash
panache lint document.qmd
```

Lint multiple files or directories:

```bash
panache lint file1.md file2.qmd
panache lint .
```

Lint from stdin:

```bash
echo '# H1\n### H3' | panache lint
```

#### Apply automatic fixes

Fix issues automatically where possible:

```bash
panache lint --fix document.qmd
```

#### CI mode

Exit with code 1 if violations are found (useful for continuous integration):

```bash
panache lint --check .
```

### Parsing

Inspect the Concrete Syntax Tree (CST) for debugging:

```bash
panache parse document.qmd
```

Export CST to JSON:

```bash
panache parse --json cst.json document.qmd
```

## Configuration

panache looks for configuration files in this order:

1. Explicit `--config` path
2. `.panache.toml` or `panache.toml` in current/parent directories
3. `~/.config/panache/config.toml` (XDG config directory)
4. Built-in defaults

### Create a Config File

Create `.panache.toml` in your project root with your preferred settings:

```toml
flavor = "quarto"
line-width = 80

[style]
wrap = "reflow"
blank-lines = "collapse"

[extensions]
hard-line-breaks = false
citations = true
```

Available flavor options:

`pandoc`
:   Standard Pandoc Markdown (default)

`quarto`
:   Quarto-flavored Markdown

`rmarkdown`
:   R Markdown

`gfm`
:   GitHub Flavored Markdown

`commonmark`
:   CommonMark (minimal extensions)

### Use a Custom Config

Specify a config file explicitly:

```bash
panache format --config custom.toml document.qmd
```

See the [Configuration](configuration.qmd) guide for all options.

## Ignore Directives

Sometimes you need to preserve specific formatting or suppress lint warnings for
certain regions. Panache supports ignore directives using HTML comments:

### Preserve Formatting

Use `panache-ignore-format-start` and `panache-ignore-format-end`:

```markdown
Normal text will be formatted.

<!-- panache-ignore-format-start -->
This    text   has    custom     spacing
that  will   be   preserved   exactly.
<!-- panache-ignore-format-end -->

Back to normal formatting.
```

### Suppress Linting

Use `panache-ignore-lint-start` and `panache-ignore-lint-end`:

```markdown
<!-- panache-ignore-lint-start -->
#### Unusual heading structure won't trigger warnings
<!-- panache-ignore-lint-end -->
```

### Ignore Both

Use `panache-ignore-start` and `panache-ignore-end`:

```markdown
<!-- panache-ignore-start -->
Custom    formatting   and   no    lint    warnings
<!-- panache-ignore-end -->
```

These directives work anywhere in your document, including inside lists,
blockquotes, and other nested structures.

See the [Formatting](formatting.qmd) and [Linting](linting.qmd) guides for more
details.

## Getting Help

- **GitHub Issues**:
  [github.com/jolars/panache/issues](https://github.com/jolars/panache/issues)
- **Discussions**:
  [github.com/jolars/panache/discussions](https://github.com/jolars/panache/discussions)
