Getting Started

To get started with Panache, follow the installation instructions below, then explore the basic usage examples for formatting, linting, and parsing your Markdown documents. You can also customize Panache’s behavior with configuration files and use ignore directives to preserve specific formatting or suppress lint warnings in certain sections of your documents.

Installation

From crates.io

Install panache with Cargo:

cargo install panache

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

For macOS and Linux:

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

For Windows PowerShell:

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

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

Arch Linux

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

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:

{ pkgs, ... }:

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

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

You can also format multiple files or use glob patterns:

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

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

panache format .
panache format docs/

Format from stdin to stdout

When reading from stdin, Panache always writes to stdout:

cat document.qmd | panache format

You can also use input redirection:

panache format <document.qmd

Or pipe input directly:

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:

panache format --check document.qmd

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

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:

panache lint document.qmd

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

panache lint file1.md file2.qmd
panache lint .

Lint from stdin:

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

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

panache lint --fix document.qmd

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

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:

panache parse document.qmd

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

panache parse --json cst.json document.qmd

Configuration

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

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.

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:

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:

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