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

Panache is available from several sources:

  • crates.io: cargo install panache
  • Homebrew: brew install panache
  • npm: npm install -g @panache-cli/panache (or npx @panache-cli/panache)
  • PyPI: uv tool install panache-cli/pipx install panache-cli
  • Aqua: aqua install jolars/panache
  • NixOS: the panache package on Nixpkgs
  • Arch Linux: from the AUR: panache-bin (prebuilt), panache (built from source)
  • Prebuilt binaries: tarballs, .deb, and .rpm from the releases page
  • VS Code/Open VSX: the Panache extension, from the VS Code Marketplace or Open VSX (also works in Positron), which installs the CLI and starts the language server automatically

Install Script

The installer scripts pick the right release artifact for your platform and install to a user-local directory by default. They are fetched from the latest release and then download the matching Panache CLI release asset. 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"

Set PANACHE_INSTALL_DIR to change the destination and PANACHE_TAG to pin a version.

See getting started for per-platform detail and the development version.

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.3.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.3.0-py3-none-win_arm64.whl (7.1 MB view details)

Uploaded Python 3Windows ARM64

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

Uploaded Python 3Windows x86-64

panache_cli-3.3.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.3.0-py3-none-musllinux_1_2_aarch64.whl (7.2 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

panache_cli-3.3.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.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (7.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

panache_cli-3.3.0-py3-none-macosx_10_12_x86_64.whl (7.5 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: panache_cli-3.3.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.3.0.tar.gz
Algorithm Hash digest
SHA256 5c5492de09b6ce02ca2e96f61fa175299647ebeb991215771caa80d8038a08a4
MD5 31988646f518b8091235b5829ae2a18e
BLAKE2b-256 822d659dacb162008413ec6622c8c598f000a82e5148840386a988e7d8c20b04

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: panache_cli-3.3.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.3.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 79bea4649f196b922695ac277d5ababd0e6b72ae07d7c905c805a0d064c0df92
MD5 6fec538c13e9174cf0e0342a7473d34a
BLAKE2b-256 8c00037fa74599faf4249824ef5c3eae68b664267b0d8696f12a3e3393c7e8cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: panache_cli-3.3.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.3.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 5b5abab3bb7fb5db856822d9bab1e2e9baee8a094df3099f196e5da8d014fe0d
MD5 1e904adb9af211ae6eadc9ab84ea270e
BLAKE2b-256 57195311881e32606c8b199493cbbb5d140d858e3d5c44b7132fefe9536c6893

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 946f41912109a37110dd27cd11bb02b8ea61d89c407335f713ee580d3c8f90cb
MD5 ab48d00b59fb9d493903c5eec4b3326f
BLAKE2b-256 8cdd93ea2c7f9adf785e5412944b63be6e1793d36e4ed174355790a06d347f75

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 c5031eb6d882101fadb6600805e4d0552378e9adfebe3f47a47c83c1f5995142
MD5 1b976d1a24f05c8069cf6e87a54b036c
BLAKE2b-256 7b6720b8f8d8c73ada84d9982cb3e8c61d7d4eacada8139850c42d091c7d2b88

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f558ea8f33f74ab2232b38589d3132e8c1c43e89301dcda9396122a2a7d0e6de
MD5 15a5c66905c5cb1176cae34a00a09cd1
BLAKE2b-256 33f2e0d819b20932b7d63111a64c60475f132f2accae528446293e79349ffd4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4a1f13537d60ddbdf7e78ede1e3d56e571f3da39dd4e2feae72491fe9706c9e1
MD5 0fc42f0636166294afc511395c31a2c1
BLAKE2b-256 9394ec3bb75268d2897833e492731e730e9e1be08bde57df586890dc8cb5e4d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 855caa0040d5d0ddc85b836d5cfbfc0f7c914ea6301bfc38342f1116eb0aa0ca
MD5 51ebd4040485f7819477f60732a36010
BLAKE2b-256 a2541e0aa06e00a51078b738ebc3399f53d791128ad38500a2e8416f4a51e4ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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.3.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for panache_cli-3.3.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3734ff2fe0e3e97ec241f65b97b7fae08ef45c29080edb802342f12200816ad2
MD5 13a475f117b9e75f5a2210240000685d
BLAKE2b-256 430a97469144d5bd2a83b0ff9855b78c0376e98724bf0b232bc7ade3c316712a

See more details on using hashes here.

Provenance

The following attestation bundles were made for panache_cli-3.3.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