---
title: Getting Started
description: >
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:
```bash
cargo install panache
```
### Pre-built Binaries
Download platform-specific binaries from the [releases
page](https://github.com/jolars/panache/releases):
- **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.^[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.]
::: {.panel-tabset}
### Linux and macOS
```sh
curl --proto '=https' --tlsv1.2 -LsSf \
https://raw.githubusercontent.com/jolars/panache/refs/heads/main/scripts/panache-installer.sh | sh
```
### Windows (PowerShell)
```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):
```bash
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`:
```nix
{ pkgs, ... }:
{
environment.systemPackages = [
pkgs.panache
];
}
```
### Verify Installation
Check that panache is installed correctly:
```bash
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](https://marketplace.visualstudio.com/items?itemName=jolars.panache).
The extension starts the language server automatically for supported files.
### Open VSX (Positron, Cursor, VSCodium, etc.)
Install the [Open VSX extension](https://open-vsx.org/extension/jolars/panache).
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:
```lua
-- .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](guide/lsp.qmd#editor-integration) 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:
```bash
panache format document.qmd
```
You can also format multiple files or use glob patterns:
```bash
panache format file1.md file2.qmd file3.Rmd
panache format ./*.{qmd,md}
```
If you specify a directory, Panache will recursively format all supported files:
```bash
panache format .
panache format docs/
```
#### Format from stdin to stdout
When reading from stdin, Panache always writes to stdout:
```bash
cat document.qmd | panache format
```
You can also use input redirection:
```bash
panache format <document.qmd
```
Or pipe input directly:
```bash
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:
```bash
panache format --check document.qmd
```
This is useful in CI/CD pipelines to enforce formatting:
```bash
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:
```bash
panache lint document.qmd
```
As with `format`, you can lint multiple files or entire directories:
```bash
panache lint file1.md file2.qmd
panache lint .
```
Lint from stdin:
```bash
echo '# H1\n### H3' | panache lint
```
`panache lint` also support an auto-fix mode that attempts to correct certain
issues:
```bash
panache lint --fix document.qmd
```
To exit with an error code if any lint issues are found (without fixing), use
`--check`:
```bash
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:
```bash
panache parse document.qmd
```
If you want to see the raw JSON output of the parser, use the `--json` flag:
```bash
panache parse --json cst.json document.qmd
```
## Configuration
Create `panache.toml` in your project root with your preferred settings:
```toml
flavor = "quarto"
line-width = 80
[format]
wrap = "reflow"
blank-lines = "collapse"
```
To see all the available configuration options, check the [Configuration
guide](guide/configuration.qmd).
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`:
```markdown
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`:
```markdown
<!-- 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`:
```markdown
<!-- 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](guide/formatting.qmd) and [Linting](guide/linting.qmd)
guides for more details.
## Getting Help
- **GitHub Issues**:
[github.com/jolars/panache/issues](https://github.com/jolars/panache/issues)
- **Discussions**:
[github.com/jolars/panache/discussions](https://github.com/jolars/panache/discussions)
