Getting Started

Installation

Pre-built Binaries

Download platform-specific binaries from the releases page:

  • 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

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

Fedora/RHEL/openSUSE

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:

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

Verify Installation

Check that panache is installed correctly:

panache --version

Basic Usage

Formatting

Format files in place

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

panache format document.qmd

Format multiple files:

panache format file1.md file2.qmd file3.Rmd

Format entire directories recursively:

panache format .
panache format docs/

Format from stdin to stdout

When reading from stdin, panache always writes to stdout:

cat document.qmd | panache format

Using input redirection:

panache format <document.qmd

Inline formatting with echo:

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:

panache format --check document.qmd

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

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:

panache lint document.qmd

Lint multiple files or directories:

panache lint file1.md file2.qmd
panache lint .

Lint from stdin:

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

Apply automatic fixes

Fix issues automatically where possible:

panache lint --fix document.qmd

CI mode

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

panache lint --check .

Parsing

Inspect the Concrete Syntax Tree (CST) for debugging:

panache parse document.qmd

Export CST to JSON:

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:

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:

panache format --config custom.toml document.qmd

See the Configuration 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:

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:

<!-- 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:

<!-- 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 and Linting guides for more details.

Getting Help