# Panache [![CI](https://img.shields.io/github/actions/workflow/status/jolars/panache/build-and-test.yml?branch=main&label=CI)](https://github.com/jolars/panache/actions/workflows/build-and-test.yml) [![Crates.io](https://img.shields.io/crates/v/panache.svg?logo=rust)](https://crates.io/crates/panache) [![Open VSX](https://img.shields.io/open-vsx/v/jolars/panache?logo=vsix)](https://open-vsx.org/extension/jolars/panache) [![VS Code](https://vsmarketplacebadges.dev/version-short/jolars.panache.svg?logo=vsix)](https://marketplace.visualstudio.com/items?itemName=jolars.panache) [![PyPi](https://img.shields.io/pypi/v/panache-cli?logo=python&label=PyPi)](https://badge.fury.io/py/panache-cli) [![npm](https://img.shields.io/npm/v/@panache-cli/panache?logo=npm&label=npm)](https://badge.fury.io/js/@panache-cli%2Fpanache) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18608442-blue)](https://doi.org/10.5281/zenodo.18608442) Panache is a language server, formatter, and linter for Quarto and other Markdown flavors, 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 --locked 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` - **mise/Aqua**: see the [installation guide](https://panache.bz/getting-started.html#mise-and-aqua) - **NixOS**: the `panache` package on [Nixpkgs](https://search.nixos.org/packages?channel=unstable&show=panache&from=0&size=50&sort=relevance&type=packages) - **Arch Linux**: from the AUR: [`panache-bin`](https://aur.archlinux.org/packages/panache-bin/) (prebuilt), [`panache`](https://aur.archlinux.org/packages/panache/) (built from source) - **Prebuilt binaries**: tarballs, `.deb`, and `.rpm` from the [releases page](https://github.com/jolars/panache/releases) - **VS Code/Open VSX**: the Panache extension, from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=jolars.panache) or [Open VSX](https://open-vsx.org/extension/jolars/panache) (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 download the matching Panache CLI release asset. If you prefer, download and inspect the script before running it. For macOS and Linux: ```sh curl --proto '=https' --tlsv1.2 -sSf https://panache.bz/install | sh ``` For Windows PowerShell: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://panache.bz/install.ps1 | iex" ``` Set `PANACHE_INSTALL_DIR` to change the destination and `PANACHE_TAG` to pin a version. See [getting started](https://panache.bz/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: ```bash panache format document.qmd ``` You can also format from stdin by piping content into `panache format`: ```bash cat | panache format ``` `panache format` supports glob patterns and recursive directory formatting: ```bash 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: ```bash panache format --check document.qmd ``` #### External Code Formatters Panache supports external formatters for code blocks. For example, you can configure it to run `arity` on R code blocks and `ruff` on Python code blocks: ```toml [formatters] r = "arity" python = "ruff" javascript = "prettier" typescript = "prettier" # Reuse same formatter ``` You can setup custom formatters or modify built-in presets with additional arguments: ```toml [formatters] python = ["isort", "black"] javascript = "myformatter" [formatters.isort] args = ["--profile=black"] [formatters.myformatter] 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: ```bash panache lint document.qmd ``` As with `panache format`, you can use glob patterns and recursive formatting: ```bash 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: ```toml # 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 [Language Server](https://panache.bz/guide/language-server.html) for feature details and [Editor Setup](https://panache.bz/guide/lsp.html) to connect Panache to your editor. 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 - Quarto and Bookdown project awareness The development R package also provides [RStudio addins](https://panache.bz/guide/lsp.html#rstudio) for formatting documents and selected blocks. ## Configuration Panache looks for a configuration in: 1. An explicit `--config ` 2. `.panache.toml`, `panache.toml`, or `.config/panache.toml` in the current directory or a parent directory 3. The user configuration directory: - Linux: `$XDG_CONFIG_HOME/panache/config.toml` or `~/.config/panache/config.toml` - macOS: `~/Library/Application Support/panache/config.toml` - Windows: `%APPDATA%\panache\config.toml` ### Example ```toml # Markdown flavor and line width flavor = "quarto" # Formatting style [format] wrap = "reflow" line-width = 80 line-ending = "auto" # External code formatters (opt-in) [formatters] python = ["isort", "black"] # Sequential formatting latex = "badness" # Built-in preset javascript = "prettier" # Reusable definitions typescript = "prettier" # Customize formatters [formatters.prettier] prepend-args = ["--print-width=100"] # External code linters [linters] julia = "fatou" # Enable Julia linting python = "ruff" ``` See [the configuration reference](https://panache.bz/reference/configuration.html) for a complete list of configuration options and their defaults. ## Integrations ### GitHub Actions For CI, use the dedicated GitHub Action: ```yaml - uses: jolars/panache-action@v1 ``` See the [Integrations documentation](https://panache.bz/guide/integrations) for configuration options. ### Pre-commit Hooks Panache integrates with [pre-commit](https://pre-commit.com/) to automatically format and lint your files before committing. **Installation:** First, install pre-commit if you haven't already: ```bash pip install pre-commit # or brew install pre-commit ``` Then add Panache to your `.pre-commit-config.yaml`: ```yaml repos: - repo: https://github.com/jolars/panache-pre-commit rev: v3.14.0 hooks: - id: panache-lint - id: panache-format ``` > **Note:** The hooks live in > [`jolars/panache-pre-commit`](https://github.com/jolars/panache-pre-commit), a > thin shim repo. Install the hooks: ```bash pre-commit install ``` The lint hook reports findings; add `args: [--fix]` to apply safe fixes before formatting. The format hook rewrites files in place. See the [integration guide](https://panache.bz/guide/integrations.html#pre-commit) for file patterns, check-only mode, and updates. See [examples/pre-commit-config.yaml](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](https://panache.bz/guide/comparison). For benchmarks against the same set of tools, see the [performance page](https://panache.bz/guide/performance). ## 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, R Markdown, MyST, and other Markdown flavors - 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 Panache is heavily inspired. ## Citation If you use Panache in your research, please cite the release you used. Select that release in the [Zenodo archive](https://doi.org/10.5281/zenodo.18608442) and export its citation. To cite Panache generally, use the concept DOI `10.5281/zenodo.18608442`. Machine-readable metadata is available in [CITATION.cff](CITATION.cff).