jolars/panache

Language server, formatter, and linter for Markdown, Quarto, and R Markdown - jolars/panache

212 stars · 13 forks

README

Panache

Panache is 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 --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 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 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 -sSf https://panache.bz/install | sh For Windows 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 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 arity on R code blocks and ruff on Python code blocks: [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: [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: 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:

Enable R linting

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

Configuration Panache looks for a configuration in:

An explicit --config <path> .panache.toml, panache.toml, or .config/panache.toml in the current directory or a parent directory 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

Markdown flavor and line width

Formatting style

External code formatters (opt-in)

Customize formatters

External code linters

• uses: jolars/panache-action@v1

or

Note: The hooks live in jolars/panache-pre-commit, a thin shim repo.

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 Panache is heavily inspired.

source