Getting Started

This guide gets you from zero to a productive Panache setup. You will install the CLI, verify it works, connect your editor, run the core commands (format and lint), and learn how to configure Panache.

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

Linux and macOS

curl --proto '=https' --tlsv1.2 -LsSf \
    https://raw.githubusercontent.com/jolars/panache/refs/heads/main/scripts/panache-installer.sh | sh

Windows (PowerShell)

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

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
  ];
}

Verify Installation

Check that panache is installed correctly:

panache --version

Editor Setup

You will get the most out of Panache by integrating its language server into your editor. This gets you access to

• formatting on save,
• real-time linting feedback,
• information on hovering over syntax,
• document symbols (outline views),
• clickable links for references and citations,
• renaming support,
• and much more.

VS Code

Install the VS Code Marketplace extension. The extension starts the language server automatically for supported files.

Open VSX (Positron, Cursor, VSCodium, etc.)

Install the Open VSX extension. The extension starts the language server automatically for supported files.

Neovim and other editors

In Neovim (version 0.11 or later), add the following to your LSP configuration:

-- .config/nvim/lsp/panache.lua

return {
  cmd = { "panache", "lsp" },
  filetypes = { "quarto", "markdown", "rmarkdown" },
    root_markers = { ".panache.toml", "panache.toml", ".git" },
  settings = {},
}

-- Enable it
vim.lsp.enable({"panache"})

See the Language Server guide for more detailed instructions on configuring the Panache language server in Neovim, Emacs, Helix, Emacs, Helix, and other LSP-capable editors.

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"

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)

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

• GitHub Issues: github.com/jolars/panache/issues
• Discussions: github.com/jolars/panache/discussions

Footnotes

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