---
title: Configuration
description: >
This guide describes how to configure Panache, both globally and on a
per-project basis, and how to use configuration files to customize the
formatting and linting rules.
---
Panache's configuration system is built around a TOML configuration file, which
allows you to customize a range of options, including formatting preferences,
linting rules, external linter and formatter integrations.
Panache searches for a configuration file in the following order:
1. **Explicit path**: `--config <path>` (errors if invalid)
2. **Project config**: `.panache.toml` or `panache.toml` in current or parent
directories
3. **User config**: `~/$XDG_CONFIG_HOME/panache/config.toml` (typically
`~/.config/panache/config.toml`)
## Basic Options
Here, we list the top-level configuration options that control general behavior.
### Flavor
Choose the Markdown flavor, which determines default [extension](#extensions)
settings:
```toml
flavor = "pandoc"
```
The available flavors are:
`pandoc`
: Standard [Pandoc Markdown](https://pandoc.org) (default)
`quarto`
: [Quarto](https://quarto.org)-flavored Markdown (Pandoc + Quarto extensions)
`rmarkdown`
: R Markdown (Pandoc + R-specific extensions, including Bookdown): R Markdown
(Pandoc + R-specific extensions)
`gfm`
: GitHub-Flavored Markdown
`commonmark`
: CommonMark (Note that we are currently **not** fully CommonMark-compliant,
and use this option only as a means to setup the correct set of extensions):
CommonMark (minimal extensions)
`multimarkdown`
: MultiMarkdown flavor defaults (Pandoc-compatible MultiMarkdown extension
set)
### Line Width
Set the maximum line width for text wrapping:
```toml
line-width = 80
```
### Flavor Overrides
Use `flavor-overrides` to pick flavor by path pattern for Markdown-family files
(`.md`, `.markdown`, `.mdown`, `.mkd`):
```toml
flavor = "quarto"
[flavor-overrides]
"README.md" = "gfm"
"docs/**/*.md" = "quarto"
```
Panache applies flavor in this order:
1. `.qmd` files always use `quarto`
2. `.Rmd` files always use `rmarkdown`
3. Markdown-family files use the most specific matching `flavor-overrides`
pattern
4. Otherwise, Panache falls back to top-level `flavor`
### File Selection (Directory Traversal)
When you run commands on directories (`panache format .`, `panache lint .`,
`panache debug format .`), Panache supports include/exclude selectors:
```toml
exclude = [".git/", "build/"]
extend-exclude = ["tests/testthat/_snaps/"]
include = ["*.qmd", "*.md"]
extend-include = ["*.Rmd"]
```
`exclude`
: Base exclude patterns. If set, replaces Panache's default exclude base. The
default exclude base includes common build/cache directories and
`**/LICENSE.md`.
`extend-exclude`
: Additional exclude patterns appended to the base set.
`include`
: Base include patterns. If set, replaces Panache's default include base.
`extend-include`
: Additional include patterns appended to the base set.
Path matching base:
- For discovered config files, include/exclude globs are resolved relative to
the directory containing the active config file.
- For explicit `--config path/to/panache.toml`, include/exclude globs are
resolved relative to the current working directory.
- CLI path arguments (for example `panache format docs/`) limit traversal scope
but do not change how include/exclude globs are resolved.
If a path matches both include and exclude, exclude wins.
### Pandoc Compatibility
Use `pandoc-compat` for ambiguous syntax cases where Pandoc behavior changed
across releases.
```toml
pandoc-compat = "3.7"
```
`pandoc-compat`
: Compatibility target for ambiguous Pandoc behavior.
- `3.9` (default): match Pandoc 3.9 behavior.
- `3.7`: match Pandoc 3.7 behavior.
- `latest`: alias for Panache's pinned newest verified target (currently
`3.9`).
This option is intentionally narrow in scope and only affects cases where Pandoc
changed behavior across versions. It is global, so parser, formatter, and LSP
all use the same target behavior.
### CLI Cache
Panache can persist CLI lint/format cache entries between runs to speed up
workspace re-runs when files and config are unchanged.
```toml
cache-dir = "/absolute/path/to/cache-dir"
```
`cache-dir`
: Optional cache directory override. Relative paths are resolved from the CLI
start directory. If unset, Panache uses an OS-specific global cache location
(for example `~/.cache/panache/` on Linux).
Cache validity currently includes file content, effective config, and Panache
version. When any of these change, Panache recomputes and refreshes entries. Use
`--cache-dir <CACHE_DIR>` (or `PANACHE_CACHE_DIR`) to override `cache-dir` for
one invocation. Use `--no-cache` (or `PANACHE_NO_CACHE`) to bypass cache
reads/writes for a single CLI invocation. Use `panache clean` to remove the
current workspace bucket, or `panache clean --all` to clear all global Panache
cache buckets.
## Formatting Style
Formatting style preferences are organized under the `[format]` section:
```toml
[format]
wrap = "reflow"
blank-lines = "collapse"
math-delimiter-style = "preserve"
math-indent = 0
tab-stops = "normalize"
tab-width = 4
```
### Wrapping Mode
Control how text is wrapped:
```toml
[format]
wrap = "reflow"
```
`reflow`
: Reformat paragraphs to fit within line width (default)
`sentence`
: Wrap after each sentence.
`preserve`
: Keep existing line breaks
### Blank Lines
Control blank line handling:
```toml
[format]
blank-lines = "collapse"
```
`collapse`
: Collapse multiple blank lines into one (default)
`preserve`
: Keep all existing blank lines
### Math Formatting
Configure how math delimiters are formatted:
```toml
[format]
math-delimiter-style = "preserve"
math-indent = 0
```
Math delimiter styles:
`preserve`
: Keep original delimiter style (default)
`dollars`
: Normalize to `$...$` and `$$...$$`
`backslash`
: Normalize to `\(...\)` and `\[...\]`
The `math-indent` field specifies indentation (in spaces) for display math
blocks. Default is 0.
### Tab Stops
Control how tabs are handled during formatting:
```toml
[format]
tab-stops = "normalize"
tab-width = 4
```
`normalize`
: Convert tabs to spaces using `tab-width` (default 4).
`preserve`
: Preserve tabs in literal code spans and fenced/indented code blocks. Tabs in
regular text are always normalized to spaces.
`tab-width`
: Number of spaces per tab when normalizing (default 4).
## Extensions
Panache supports most of the Pandoc extensions. Defaults vary by flavor, but you
can override any extension:
```toml
flavor = "quarto"
[extensions]
hard-line-breaks = false
citations = true
task-lists = true
```
You can also scope extension overrides to a specific flavor:
```toml
[extensions]
citations = true
task-lists = false
[extensions.gfm]
task-lists = true
```
Precedence for the active flavor is:
1. flavor defaults
2. global `[extensions]`
3. `[extensions.<flavor>]`
### Block-Level Extensions
#### Headings
```toml
[extensions]
auto-identifiers = true
gfm-auto-identifiers = false
blank-before-header = true
header-attributes = true
implicit-header-references = true
```
`auto-identifiers`
: Auto-generate heading identifiers (default: enabled for `pandoc`, `quarto`,
`rmarkdown`, `gfm`, and `multimarkdown`)
`gfm-auto-identifiers`
: Use GitHub's heading identifier algorithm (default: disabled, enabled for
`gfm` flavor)
`blank-before-header`
: Require blank line before headers (default: enabled)
`header-attributes`
: Full attribute syntax on headers `{#id .class key=value}` (default: enabled)
`implicit-header-references`
: Allow `[Heading]` links to reference headers (default: enabled)
`mmd-header-identifiers`
: MultiMarkdown heading identifiers in square brackets, e.g.
`# Heading [myid]` and setext `Heading [myid]` (default: disabled, enabled
for `multimarkdown` flavor)
#### Block Quotes
```toml
[extensions]
blank-before-blockquote = true
```
`blank-before-blockquote`
: Require blank line before blockquotes (default: enabled)
#### Lists
```toml
[extensions]
fancy-lists = true
startnum = true
example-lists = true
task-lists = true
definition-lists = true
```
`fancy-lists`
: Roman numerals, letters, and fancy list markers (default: enabled)
`startnum`
: Start ordered lists at arbitrary numbers (default: enabled)
`example-lists`
: Example lists with `(@)` markers (default: enabled)
`task-lists`
: GitHub-style task lists `- [ ]` and `- [x]` (default: enabled)
`definition-lists`
: Term/definition syntax (default: enabled)
#### Code Blocks
```toml
[extensions]
backtick-code-blocks = true
fenced-code-blocks = true
fenced-code-attributes = true
executable-code = true
inline-code-attributes = true
```
`backtick-code-blocks`
: Fenced code blocks with \`\`\` fences (default: enabled)
`fenced-code-blocks`
: Fenced code blocks with `~~~` fences (default: enabled)
`fenced-code-attributes`
: Attributes on fenced code blocks `{.language #id}` (default: enabled)
`executable-code`
: Executable code chunks with brace info strings like ```` ```{r} ```` and
```` ```{python} ```` (default: disabled, enabled for Quarto and RMarkdown
flavors).
`rmarkdown-inline-code`
: Parse inline executable code that uses R Markdown style tails like
`` `3 == `r 2 + 1 `` \`\` (default: disabled, enabled for Quarto and
RMarkdown flavors).
`quarto-inline-code`
: Parse inline executable code that uses braced tails like
`` `3 == `{r} 2 + 1 ``
\``(default: disabled, enabled for Quarto flavor). Formatted output is normalized to the braced`{r}\`
marker for renderer parity in this syntax family.
`inline-code-attributes`
: Attributes on inline code `` `code`{.class} `` (default: enabled)
#### Tables
```toml
[extensions]
simple-tables = true
multiline-tables = true
grid-tables = true
pipe-tables = true
table-captions = true
```
`simple-tables`
: Simple table syntax (default: enabled)
`multiline-tables`
: Multiline cells (default: enabled)
`grid-tables`
: Grid-style tables (default: enabled)
`pipe-tables`
: GitHub-style `|` tables (default: enabled)
`table-captions`
: Table captions (default: enabled)
#### Divs
```toml
[extensions]
fenced-divs = true
native-divs = true
```
`fenced-divs`
: Fenced divs `::: {.class}` (default: enabled)
`native-divs`
: HTML `<div>` elements (default: enabled)
#### Other Blocks
```toml
[extensions]
line-blocks = true
```
`line-blocks`
: Line blocks for poetry with `|` prefix (default: enabled)
### Inline Extensions
#### Emphasis
```toml
[extensions]
intraword-underscores = true
strikeout = true
superscript = true
subscript = true
```
`intraword-underscores`
: Don't trigger emphasis in `snake_case` (default: enabled)
`strikeout`
: Strikethrough `~~text~~` (default: enabled)
`superscript`
: Superscript `^super^` (default: enabled)
`subscript`
: Subscript `~sub~` (default: enabled)
#### Links
```toml
[extensions]
inline-links = true
reference-links = true
shortcut-reference-links = true
link-attributes = true
autolinks = true
```
`inline-links`
: Inline links `[text](url)` (default: enabled)
`reference-links`
: Reference links `[text][ref]` (default: enabled)
`shortcut-reference-links`
: Shortcut reference links `[ref]` (default: enabled)
`link-attributes`
: Attributes on links `[text](url){.class}` (default: enabled)
`mmd-link-attributes`
: MultiMarkdown key-value attributes on reference link/image definitions,
including indented continuation lines (default: disabled, enabled for
`multimarkdown` flavor)
`autolinks`
: Automatic links `<http://example.com>` (default: enabled)
`autolink-bare-uris`
: Bare URLs become links (default: disabled, non-default extension)
#### Images
```toml
[extensions]
inline-images = true
implicit-figures = true
```
`inline-images`
: Inline images `` (default: enabled)
`implicit-figures`
: Single image becomes figure (default: enabled)
#### Math
```toml
[extensions]
tex-math-dollars = true
tex-math-gfm = false
tex-math-single-backslash = false
tex-math-double-backslash = false
```
`tex-math-dollars`
: Dollar-delimited math `$x$` and `$$equation$$` (default: enabled)
`tex-math-gfm`
: GFM math: inline `$`...`$` and fenced ```` ``` math ```` blocks (default:
disabled, enabled for GFM flavor)
`tex-math-single-backslash`
: Single backslash math `\(...\)` and `\[...\]` (default: disabled, enabled
for RMarkdown)
`tex-math-double-backslash`
: Double backslash math `\\(...\\)` and `\\[...\\]` (default: disabled)
#### Footnotes
```toml
[extensions]
inline-footnotes = true
footnotes = true
```
`inline-footnotes`
: Inline footnotes `^[text]` (default: enabled)
`footnotes`
: Reference footnotes `[^1]` and `[^1]: content` (default: enabled)
#### Citations
```toml
[extensions]
citations = true
```
`citations`
: Citation syntax `[@cite]` (default: enabled)
#### Spans
```toml
[extensions]
bracketed-spans = true
native-spans = true
```
`bracketed-spans`
: Bracketed spans `[text]{.class}` (default: enabled)
`native-spans`
: HTML `<span>` elements (default: enabled)
### Metadata Extensions
```toml
[extensions]
yaml-metadata-block = true
pandoc-title-block = true
```
`yaml-metadata-block`
: YAML frontmatter with `---` delimiters (default: enabled)
`pandoc-title-block`
: Pandoc title block `% Title`, `% Author`, `% Date` (default: enabled)
`mmd-title-block`
: MultiMarkdown metadata/title block at document start using `Key: Value`
pairs with optional indented continuation lines (default: disabled, enabled
for `multimarkdown` flavor)
### Raw Content Extensions
```toml
[extensions]
raw-html = true
markdown-in-html-blocks = false
raw-tex = true
raw-attribute = true
```
`raw-html`
: HTML blocks and inline HTML (default: enabled)
`markdown-in-html-blocks`
: Markdown inside HTML blocks (default: disabled)
`raw-tex`
: LaTeX commands and environments (default: enabled)
`raw-attribute`
: Generic raw blocks with `{=format}` syntax (default: enabled)
### Special Character Extensions
```toml
[extensions]
all-symbols-escapable = true
escaped-line-breaks = true
hard-line-breaks = false
smart = true
smart-quotes = false
emoji = false
mark = false
```
`all-symbols-escapable`
: Backslash escapes any symbol (default: enabled)
`escaped-line-breaks`
: Backslash at line end creates hard line break (default: enabled)
`hard-line-breaks`
: Newline creates hard line break (default: disabled, non-default extension)
`smart`
: Normalize smart/curly punctuation in formatter output (quotes/apostrophes
and en/em dashes, plus ellipsis) to Markdown forms (`'`, `"`, `--`, `---`,
`...`). Defaults: enabled for `pandoc`, `quarto`, `rmarkdown`; disabled for
`gfm`, `commonmark`, `multimarkdown`.
`smart-quotes`
: Normalize smart/curly quotes and apostrophes only (`'`, `"`). Unlike
`smart`, this does not normalize dashes or ellipsis. Default: disabled.
`emoji`
: Emoji syntax `:emoji:` (default: disabled, non-default extension)
`mark`
: Highlighted text `==highlighted==` (default: disabled, non-default
extension)
### Quarto-Specific Extensions
```toml
[extensions]
quarto-callouts = true
quarto-crossrefs = true
quarto-shortcodes = true
```
`quarto-callouts`
: Quarto callout blocks `.callout-note`, `.callout-warning`, etc. (default:
disabled, enabled for Quarto flavor)
`quarto-crossrefs`
: Quarto cross-references `@fig-id`, `@tbl-id` (default: disabled, enabled for
Quarto flavor)
`quarto-shortcodes`
: Quarto shortcodes `{{< name args >}}` (default: disabled, enabled for Quarto
flavor)
### Bookdown Extensions
```toml
[extensions]
bookdown-references = true
bookdown-equation-references = true
```
`bookdown-references`
: Bookdown references `\@ref(label)` and `(\#label)` (default: disabled,
enabled for RMarkdown flavor)
`bookdown-equation-references`
: Bookdown equation references for labels like `(\#eq:label)` inside LaTeX
math environments (default: disabled, enabled for RMarkdown flavor)
## External Formatters
Panache can invoke external formatters for code blocks. No external formatters
are enabled by default, so you have to opt-in for each language you want to
format.
::: {.callout-note}
### YAML
YAML is special: Panache has built-in YAML formatting for frontmatter and
hashpipe chunk options based on [Pretty
YAML](https://github.com/g-plane/pretty_yaml). External YAML formatters apply
*only* to fenced code blocks (with YAML language).
:::
### Basic Usage
To enable formatting for a language, map the language key to a formatter preset
or custom formatter name:
```toml
[formatters]
r = "air"
python = "ruff"
javascript = "prettier"
typescript = "prettier"
```
You can also specify multiple formatters for a language, which will run
sequentially:
```toml
[formatters]
python = ["isort", "black"]
```
Go to [Formatter Presets](#formatter-presets) for a list of built-in presets.
### Custom Formatters
Define custom formatter configurations with the `[formatters.NAME]` syntax:
```toml
[formatters]
python = ["isort", "black"]
javascript = "prettier"
[formatters.prettier]
cmd = "prettier"
args = ["--parser=babel", "--print-width=100"]
stdin = true
[formatters.isort]
cmd = "isort"
args = ["-"]
stdin = true
```
### Formatter Fields
The formatter definition supports the following fields:
`cmd`
: Command to execute (required for custom formatters)
`args`
: Command-line arguments (optional, defaults to empty list)
`stdin`
: Use stdin/stdout mode (default: `true`) or file-based mode (`false`)
### Preset Inheritance
When a `[formatters.NAME]` section matches a built-in preset name, unspecified
fields are automatically inherited from the preset. This allows partial
overrides:
```toml
[formatters]
r = "air"
[formatters.air]
args = ["format", "--preset=tidyverse"]
```
In this example, `cmd` and `stdin` are inherited from the built-in `air` preset,
while `args` is customized.
How it works:
- If the formatter name matches a built-in preset (`air`, `black`, `ruff`,
etc.), that preset's defaults are used as a base
- Any fields you specify (`cmd`, `args`, `stdin`) override the preset defaults
- Unspecified fields keep the preset values
#### Examples
- Override only `args` (inherits `cmd = "air"`, `stdin = false`):
```toml
[formatters.air]
args = ["format", "--custom-flag", "{}"]
```
- Override only `cmd` (inherits default `args` and `stdin`):
```toml
[formatters.ruff]
cmd = "ruff-custom"
```
- Override everything (complete replacement):
```toml
[formatters.black]
cmd = "my-black"
args = ["--fast"]
stdin = false
```
### Incremental Argument Modification
Instead of completely overriding `args`, you can append and prepend arguments to
the preset's base `args` using `append-args` and `prepend-args`[^1].
```toml
[formatters]
r = "air"
[formatters.air]
append-args = ["-i", "2"]
```
This adds `["-i", "2"]` after the preset's base args `["format", "{}"]`,
resulting in final args `["format", "{}", "-i", "2"]`.
Consider the following example:
```toml
[formatters.air]
prepend-args = ["--verbose"]
append-args = ["-i", "2", "--check"]
```
This will produce the following final args:
`["--verbose", "format", "{}", "-i", "2", "--check"]`.
[^1]: The idea of `append-args` and `prepend-args` is taken from the
[conform.nvim](https://github.com/stevearc/conform.nvim) Neovim plugin.
### File-Based Formatters
For formatters that modify files in place:
```toml
[formatters]
r = "air-file"
[formatters.air-file]
cmd = "air"
args = ["format", "{}"]
stdin = false
```
The `{}` placeholder controls where the file path is inserted. If omitted, it's
appended at the end.
### Behavior
Language matching
: Code block language (e.g., ```` ```python ````) is matched to formatter key
(case-insensitive)
Parallel execution
: A thread pool is used to run formatters in parallel across files and
languages. For a single code block, formatters run sequentially in the order
specified.
Sequential chains
: Multiple formatters per language run in order
Error handling
: Failed formatters preserve original code with a warning
Language compatibility
: Built-in presets are checked against the configured language key (for
example, `python = "ruff"` is valid but `python = "gofmt"` is rejected with
a config warning). Custom formatter definitions remain unrestricted.
Preset metadata
: Built-in presets include metadata (name, source URL, description, and
supported languages) in Panache internals, which is used for validation now
and can power future formatter lookup/help commands.
Timeout
: 30 seconds per formatter (not per chain)
Config files
: Formatters respect their own config files (`.prettierrc`, `pyproject.toml`,
etc.)
### Presets {#formatter-presets}
Here is a list of the current built-in formatter presets in Panache. **Command**
and **Arguments** are the defaults for `cmd` and `args` when you specify the
preset name in `[formatters]`.
See [Formatter Presets](../reference/formatter-presets) for a list of all the
presets available in Panache.
## External Code Linters
Panache can invoke external linters for code blocks. Linters are opt-in---you
choose which languages to lint.
### Quick Start
Enable linters for specific languages:
```toml
[linters]
r = "jarl"
python = "ruff"
sh = "shellcheck"
js = "eslint"
go = "staticcheck"
rust = "clippy"
```
Available linters:
| Language | Linter | Command | Notes |
| --------------------- | ------------- | --------------- | ----------------------------------- |
| R | `jarl` | `jarl` | R linter with JSON diagnostics |
| Python | `ruff` | `ruff` | Python linter with JSON diagnostics |
| Shell | `shellcheck` | `shellcheck` | Shell linter with JSON diagnostics |
| JavaScript/TypeScript | `eslint` | `eslint` | JS/TS linter with JSON diagnostics |
| Go | `staticcheck` | `staticcheck` | Go linter with JSON diagnostics |
| Rust | `clippy` | `clippy-driver` | Rust linter with JSON diagnostics |
### How It Works
External linters analyze code blocks within your document:
1. **Collection** - Gathers all code blocks of the configured language
2. **Concatenation** - Combines blocks with blank-line preservation to maintain
original line numbers
3. **Analysis** - Runs the external linter on the concatenated code
4. **Mapping** - Maps diagnostics back to exact line/column positions in your
document
::: {.callout-note}
This approach handles **stateful code** correctly. For example, if an R variable
is defined in one code block and used in another, the linter sees both blocks
together and won't report false "undefined variable" errors.
:::
### Where Linters Run
CLI
: `panache lint` shows external linter diagnostics
LSP
: Diagnostics appear inline in your editor as you type
### Behavior
Language matching
: Code block language (e.g., ```` ```{r} ````) is matched to linter key
(case-insensitive)
Error handling
: Missing linters are gracefully ignored with a warning
Compatibility checks
: External linters declare supported languages. If `[linters]` maps a linter
to an unsupported language (for example, `bash = "jarl"`), Panache skips
that mapping and logs a warning.
Timeout
: 30 seconds per linter invocation
Line-accurate
: Diagnostics report exact line/column locations
Auto-fixes
: Supported for external linters that provide fix edits with mappable ranges
(currently `jarl`, `ruff`, and `eslint`)
### Example
Enable R and Python linting while also formatting:
```toml
[linters]
r = "jarl"
python = "ruff"
[formatters]
r = "air"
python = "ruff"
```
## Example Configuration
Complete example with some common options:
```toml
flavor = "quarto"
line-width = 80
[format]
wrap = "reflow"
blank-lines = "collapse"
math-delimiter-style = "preserve"
math-indent = 0
[extensions]
hard-line-breaks = false
citations = true
task-lists = true
emoji = false
[formatters]
r = "air"
python = "ruff"
```