---
title: Getting Started
---

This guide gets you from zero to a productive Panache setup. You will install
the CLI, verify it works, run the core commands (`format`, `lint`, and `parse`),
and learn the minimum configuration and ignore directives you need for
day-to-day editing.

## Installation

### From crates.io

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 and ARM64 (`.zip`)

If you prefer a one-liner installer that picks the right release artifact for
your platform, you can use the installer scripts below. These scripts download
from this repository's latest GitHub release and install to a user-local
directory by default. If you prefer, download and inspect the script before
running it.

::: {.panel-tabset}
### Linux and macOS

```sh
curl --proto '=https' --tlsv1.2 -LsSf \
    https://github.com/jolars/panache/releases/latest/download/panache-installer.sh | sh
```

### Windows (PowerShell)

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/jolars/panache/releases/latest/download/panache-installer.ps1 | iex"
```

:::

### Arch Linux

Panache is available in the Arch User Repository (AUR):

```bash
yay -S panache-bin
```

### Nix OS

Panache is available in NixOS via the `panache` package in `nixpkgs`. To add it
to your system configuration, include it in the `environment.systemPackages`:

```nix
{ pkgs, ... }:

{
  environment.systemPackages = [
    pkgs.panache
  ];
}
```

### 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
```

You can also format multiple files or use glob patterns:

```bash
panache format file1.md file2.qmd file3.Rmd
panache format ./*.{qmd,md}
```

If you specify a directory, Panache will recursively format all supported files:

```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
```

You can also use input redirection:

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

Or pipe input directly:

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

#### Check formatting without changes

`panache` includes a `--check` option to verify if files are already formatted
correctly. It exits with code 1 if any formatting issues are found:

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

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

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

### Linting

Panache also includes a `lint` command to check for semantic issues in your
Markdown documents, such as heading hierarchy problems, broken references, and
syntax errors.

#### Check for correctness issues

To lint a single file, run:

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

As with `format`, you can lint multiple files or entire directories:

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

Lint from stdin:

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

`panache lint` also support an auto-fix mode that attempts to correct certain
issues:

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

To exit with an error code if any lint issues are found (without fixing), use
`--check`:

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

This is typically used in CI/CD pipelines to enforce linting rules.

### Parsing

You can also selectively invoke the Panache parser to analyze the structure of
your Markdown documents. This is typically mostly useful for debugging or
understanding why your document is formatted in a certain way.

To return a stdout representation of the parsed document tree, run:

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

If you want to see the raw JSON output of the parser, use the `--json` flag:

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

## Configuration

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

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

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

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

To see all the available configuration options, check the [Configuration
guide](user-guide/configuration.qmd).

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)

If you like, you can also specify a custom configuration file directly:

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

## 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](user-guide/formatting.qmd) and
[Linting](user-guide/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)
  :::
