Skip to main content

Panache

Build and Test Crates.io Open VSX VS Code PyPI version npm version codecov

A language server, formatter, and linter for Markdown, Quarto, and R Markdown, built in Rust with a lossless CST parser and support for external formatters and linters on code blocks.

Installation

Homebrew

Panache is available from Homebrew on macOS and Linux:

brew install panache

From crates.io

If you have Rust installed, the easiest way is likely to install from crates.io:

cargo install panache

Pre-built Binaries

Alternatively, you can install pre-built binary packages from the releases page for Linux, macOS, and Windows. For Linux, packages are available for generic distributions (tarballs) as well as Debian/Ubuntu (.deb) and Fedora/RHEL/openSUSE (.rpm).

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 are fetched directly from this repository and then download the latest matching Panache CLI release asset for your platform, installing 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://raw.githubusercontent.com/jolars/panache/refs/heads/main/scripts/panache-installer.sh | sh

For Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/jolars/panache/refs/heads/main/scripts/panache-installer.ps1 | iex"

Arch Linux

There are also two recipies available for Arch Linux in the AUR: panache and panache-bin. The first builds from source for your system, the second uses precompiled binaries attatched to GH releases. Install either using yay or your favorite AUR helper:

yay -S panache
yay -S panache-bin

NixOS

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 PyPI (via uv or pipx)

Install with uv or pipx:

# One-shot run, no install:
uvx --from panache-cli panache format path/to/file.qmd

# Persistent install:
uv tool install panache-cli
# or
pipx install panache-cli

From NPM (via npmx)

Install with npx or npmx:

# One-shot run, no install:
npx @panache-cli/panache format path/to/file.qmd

# Persistent install:
npm install -g @panache-cli/panache

VS Code Extension

If you are running VS Code or an editor that supports VS Code extensions (like Positron), you can install the Panache extension from the VS Code Marketplace or the Open VSX extension, which will automatically also install the panache CLI and start the language server when editing supported files.

Development Version

To install the latest development version, you can run

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

This presumes you have a working and up-to-date Rust toolchain (stable, 2024 edition) installed. You also need to have cargo in your PATH if you want to use the panache command directly after installation.

Usage

Panache provides a single CLI interface for formatting, linting, and running the LSP server.

Formatting

To format a file in place, simply run:

panache format document.qmd

You can also format from stdin by piping content into panache format:

cat <file> | panache format

panache format supports glob patterns and recursive directory formatting:

panache format **/*.{qmd,md}

You can use Panache as a linter via the --check flag to check if files are already formatted without making changes:

panache format --check document.qmd

External Code Formatters

Panache supports external formatters for code blocks. For example, you can configure it to run air on R code blocks and ruff on Python code blocks:

[formatters]
r = "air"
python = "ruff"
javascript = "prettier"
typescript = "prettier" # Reuse same formatter

You can setup custom formatters or modify built-in presets with additional arguments:

[formatters]
python = ["isort", "black"]
javascript = "foobar"

[formatters.isort]
args = ["--profile=black"]

[formatters.myformatters]
cmd = "foobar"
args = ["--print-width=100"]
stdin = true

Linting

Panache also features a linter that can report formatting issues and optionally auto-fix them. To run the linter, use:

panache lint document.qmd

As with panache format, you can use glob patterns and recursive formatting:

panache lint **/*.{qmd,md}

External Linters

As with formatting, Panache supports external linters for code blocks. These are configured in the [linters] section of the configuration, but due to the complexity of linting, including dealing with auto-fixing, external linters cannot be customized and only support presets and at the moment only support R via the jarl linter:

# Enable R linting
[linters]
r = "jarl" # R linter with JSON output

Language Server

Panache implements the language server protocol (LSP) to provide editor features like formatting, diagnostics, code actions, and more. See the language server documentation for guides on how to connect Panache to your editor and configure LSP features.

The list of LSP features supported by Panache includes, among others:

  • Document formatting (full document, incremental and range)
  • Diagnostics with quick fixes
  • Code actions for refactoring
    • Convert between loose/compact lists
    • Convert between inline/reference footnotes
  • Document symbols/outline
  • Folding ranges
  • Go to definition for references and footnotes
  • Quaro and Bookdown project awareness

Configuration

Panache looks for a configuration in:

  1. .panache.toml or panache.toml in current directory or parent directories
  2. $XDG_CONFIG_HOME/panache/config.toml (usually ~/.config/panache/config.toml)

Example

# Markdown flavor and line width
flavor = "quarto"
line-width = 80
line-ending = "auto"

# Formatting style
[format]
wrap = "reflow"

# External code formatters (opt-in)
[formatters]
python = ["isort", "black"] # Sequential formatting
r = "air"                   # Built-in preset
javascript = "prettier"     # Reusable definitions
typescript = "prettier"
yaml = "yamlfmt"            # Formats both code blocks AND frontmatter

# Customize formatters
[formatters.prettier]
prepend-args = ["--print-width=100"]

# External code linters
[linters]
r = "jarl"      # Enable R linting
python = "ruff"

See examples/panache.toml for a complete configuration reference.

Integrations

GitHub Actions

For CI, use the dedicated GitHub Action:

- uses: jolars/panache-action@v1

See the Integrations documentation for configuration options.

Pre-commit Hooks

Panache integrates with pre-commit to automatically format and lint your files before committing.

Installation:

First, install pre-commit if you haven't already:

pip install pre-commit
# or
brew install pre-commit

Then add Panache to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/jolars/panache-pre-commit
    rev: v2.43.1 # Use the latest version
    hooks:
      - id: panache-format # Format files
      - id: panache-lint # Lint and auto-fix issues

Note: The hooks live in jolars/panache-pre-commit, a thin shim repo. This avoids pre-commit autoupdate resolving to unrelated sub-package tags from this monorepo (e.g. panache-code-*). If you currently point at https://github.com/jolars/panache, update the repo: URL and run pre-commit autoupdate.

Install the hooks:

pre-commit install

Panache will now automatically run on your staged .qmd, .md, and .Rmd files before each commit.

See examples/pre-commit-config.yaml for more configuration options.

Motivation

I wanted a formatter that understands Quarto and Pandoc syntax. I have tried to use Prettier as well as mdformat, but both fail to handle some of the particular syntax used in Quarto documents, such as fenced divs and some of the table syntax.

For a side-by-side overview of how Panache compares to Prettier, Pandoc, rumdl, mdformat, mado, markdownlint, markdownlint-cli2, and marksman, see the comparison page. For benchmarks against the same set of tools, see the performance page.

Design Goals and Scope

  • Full LSP implementation with formatting, diagnostics, code actions, and more
  • Standalone CLI for both formatting and linting
  • Support for Quarto, Pandoc, and R Markdown syntax
  • Lossless CST-based parsing
  • Idempotent formatting
  • Semi-opinionated defaults with configurable style options for common formatting decisions
  • Support for running external formatters and linters on code blocks, with built-in presets for popular languages and tools

Acknowledgements

The development of Panache has simplified considerably thanks to the extensive documentation, well-structured code, and testing infrastructure provided by Pandoc. We also owe significant debt to the rust-analyzer project, on which Panche is heavily inspired.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

panache_cli-3.1.0.tar.gz (1.4 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

panache_cli-3.1.0-py3-none-win_arm64.whl (7.1 MB view details)

Uploaded Python 3Windows ARM64

panache_cli-3.1.0-py3-none-win_amd64.whl (7.5 MB view details)

Uploaded Python 3Windows x86-64

panache_cli-3.1.0-py3-none-musllinux_1_2_x86_64.whl (7.9 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

panache_cli-3.1.0-py3-none-musllinux_1_2_aarch64.whl (7.1 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

panache_cli-3.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

panache_cli-3.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (7.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

panache_cli-3.1.0-py3-none-macosx_11_0_arm64.whl (7.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

panache_cli-3.1.0-py3-none-macosx_10_12_x86_64.whl (7.4 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file panache_cli-3.1.0.tar.gz.

File metadata

  • Download URL: panache_cli-3.1.0.tar.gz
  • Upload date:
  • Size: 1.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panache_cli-3.1.0.tar.gz
Algorithm Hash digest
SHA256 ee40881943337dda91f1c446ae020fc353905194ebb17182724b2538d07ffa6d
MD5 6c383fd19d3af316ab9603131f729eda
BLAKE2b-256 be1d6e0fa9ed6354617167cf1318644bd0be7d8e59d8c68571905e222f2774af

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0.tar.gz:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: panache_cli-3.1.0-py3-none-win_arm64.whl
  • Upload date:
  • Size: 7.1 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panache_cli-3.1.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 6f9f0852d0f1a77f80f2b93a4ec0c7562c8e8c6d1eaa1d8a83e22e46f5197cb4
MD5 b6781e1fb5bc94bf35b53c4736f41b3e
BLAKE2b-256 26745e820a0ba35067813ff3857a15bfb137b5917f882c9f9420eca9a5a4cbe5

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-win_arm64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: panache_cli-3.1.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 7.5 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panache_cli-3.1.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 09834ee139fb4dada93918cc7cdb2bf2f3d1ff83d844cfede10f98171762edf8
MD5 b343df44702b10e04f06effdb39e152b
BLAKE2b-256 8cd48c75b298c5e1d370d83105ff62d583d5cf0d2cfe64ce1f742d3923829924

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-win_amd64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 73bccaa251afaf3525b107096f78d86e8cda29222a79f081a7bef9650e859e49
MD5 452dc8c6a7e13edb99cca88b58a3c5a3
BLAKE2b-256 b96653db3cc8b9e8f7dbcc2b5935c30d6213e7d27e01102b997121ba4bae2a77

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-musllinux_1_2_x86_64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 f98dc0f80a198a591d82d719980c5d240bcc5bd38855f577a8be79997622b0af
MD5 de952545e4d162500365090b1a9ebf0f
BLAKE2b-256 625ca231be20a5579f6ece7463d950b5cd9ac47a59bd816c402090e06e3612ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-musllinux_1_2_aarch64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a6318d5008acc480c8cdf824c1e38bd82468577248f7e21066ade393c8123778
MD5 2272be1acc7d6f6645b3a59f79f77025
BLAKE2b-256 df4501d5cd9ea51a73566669be3952e98a5a90bd4da128e93dac0a4d7a2b743c

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e8319c57791a8cf9e9fbec7c2cbba4a8fc50cd5178fff751f836ddb0acfbc47a
MD5 ece2bf9bf8e04ddcf2fdf70989a4d86c
BLAKE2b-256 ab17aaf01025ba855556e9a726840a26e7e8d8b19bc667227535af597eff6385

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 40dcd6e9642ee67b54335fd702e400e594ed523b33c9eccce4e04520706407a0
MD5 7f863db00ab960953233c76dd7c4462d
BLAKE2b-256 bb8c6d3a53d44ba9020271c2dc0e50143bf94c5dd4f0951fb81e66ee361ea580

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-macosx_11_0_arm64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file panache_cli-3.1.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.1.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f5d4d632cb313483c73d1bb87ec7a91de464ad122d9b22ee35e6dc1cbe614b03
MD5 b34964753803e4c4d261139ec2c39c21
BLAKE2b-256 a6d48438bf17dd5b2832c203fde5a6ceb092fad79ff5b9d65a42f51d7998a372

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.1.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: publish-pypi.yml on jolars/panache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page