Configuration

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, panache.toml, or .config/panache.toml in current or parent directories
  3. User config: ~/$XDG_CONFIG_HOME/panache/config.toml (typically ~/.config/panache/config.toml)

For the project-config step, discovery walks up from the file being processed and uses the nearest panache.toml / .panache.toml / .config/panache.toml. In a monorepo, a config closer to the file wins over one at the project root. Within a single directory, a bare panache.toml / .panache.toml wins over .config/panache.toml. The walk stops at the nearest .git ancestor (project root) so unrelated configs above the project — e.g. a stray panache.toml in your home directory — are not inherited. The same rule applies to both the CLI and the LSP. If no .git ancestor exists (e.g. an untracked scratch file), the walk falls back to today’s filesystem-root behavior.

Putting the file in .config/ (the dot-config convention) keeps the project root tidy. A .config/panache.toml behaves exactly like a panache.toml in the directory that contains .config/: the .config/ wrapper is purely cosmetic. In particular, path-based settings — exclude / include and flavor-overrides glob keys — anchor at that parent directory (the project root), so a pattern like vendor/** matches vendor/ next to .config/, with no ../ prefix needed (see Path matching base).

Editor Support

Panache publishes a JSON Schema for panache.toml so editors with TOML support can offer key/value completion, inline documentation, and validation while you edit your config.

Schema URL
https://panache.bz/panache.schema.json

The schema is regenerated from the host configuration types on every release, so it always reflects the keys, enums, and defaults the current CLI accepts.

VS Code (Even Better TOML)

With the Even Better TOML extension installed, add the following to your user or workspace settings.json:

{
  "evenBetterToml.schema.associations": {
    "^(.*/)?\\.?panache\\.toml$":
      "https://panache.bz/panache.schema.json"
  }
}

Even Better TOML will then offer completion, hover documentation, and diagnostics whenever you open a panache.toml or .panache.toml file.

Inline #:schema directive

Some editors (including newer Even Better TOML builds) support an inline schema reference. Drop this at the top of any panache.toml:

#:schema https://panache.bz/panache.schema.json

Other editors

Any editor or LSP that consumes JSON Schemas (Helix, Neovim with taplo-lsp, Zed, IntelliJ, etc.) can be pointed at the same URL using its local TOML/JSON-schema mechanism.

Basic Options

Here, we list the top-level configuration options that control general behavior.

Flavor

Choose the Markdown flavor, which determines default extension settings:

flavor = "pandoc"

The available flavors are:

pandoc
Standard Pandoc Markdown (default)
quarto
Quarto-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
multimarkdown
MultiMarkdown flavor defaults (Pandoc-compatible MultiMarkdown extension set)

The --flavor CLI flag (see the CLI reference) overrides this setting for a single invocation. It also overrides [flavor-overrides] and the flavor inferred from the file extension. [extensions] overrides from panache.toml still merge on top of the selected flavor’s defaults.

Line Width

Set the maximum line width for text wrapping:

line-width = 80

The -o/--option flag on panache format can override this setting for a single invocation, e.g. panache format -o line-width=100. This is an escape hatch for ad-hoc runs; prefer panache.toml so that everyone formatting the repository gets the same result.

Flavor Overrides

Use flavor-overrides to pick flavor by path pattern for Markdown-family files (.md, .markdown, .mdown, .mkd):

flavor = "quarto"

[flavor-overrides]
"README.md" = "gfm"
"docs/**/*.md" = "quarto"

Panache applies flavor in this order:

  1. The --flavor CLI flag, if supplied, overrides everything below
  2. .qmd files always use quarto
  3. .Rmd files always use rmarkdown
  4. Markdown-family files use the most specific matching flavor-overrides pattern
  5. 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:

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:

  • Relative include / exclude globs (and flavor-overrides glob keys) resolve against the directory of the config file that declared them. A .config/panache.toml is unwrapped to the project root, so it behaves exactly like a panache.toml in the directory above .config/. The same rule applies to discovered configs and to an explicit --config path/to/panache.toml (anchored at path/to/, not the current working directory).
  • The global ~/.config/panache/config.toml has no project location, so its globs resolve against the directory being traversed (typically the current working directory).
  • CLI path arguments (for example panache format docs/) limit traversal scope but do not change how globs are anchored.

If a path matches both include and exclude, exclude wins.

Patterns are matched with globset. Gitignore-style shorthand works: a bare name like *.md matches at any depth, and a trailing slash (build/) matches a directory’s contents. Gitignore negation (!pattern) is not supported.

Pandoc Compatibility

Use pandoc-compat for ambiguous syntax cases where Pandoc behavior changed across releases.

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.

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:

[format]
wrap = "reflow"
math-delimiter-style = "preserve"
math-indent = 0
tab-stops = "normalize"
tab-width = 4

Wrapping Mode

Control how text is wrapped:

[format]
wrap = "reflow"
reflow
Reformat paragraphs to fit within line width (default)
sentence
Wrap after each sentence.
preserve
Keep existing line breaks

The -o wrap=<MODE> flag on panache format can override this setting for a single invocation, e.g. panache format -o wrap=sentence.

Math Formatting

Configure how math delimiters are formatted:

[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:

[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:

flavor = "quarto"

[extensions]
hard-line-breaks = false
citations = true
task-lists = true

You can also scope extension overrides to a specific flavor:

[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

[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

[extensions]
blank-before-blockquote = true
blank-before-blockquote
Require blank line before blockquotes (default: enabled)

Lists

[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

[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

[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

[extensions]
fenced-divs = true
native-divs = true
fenced-divs
Fenced divs ::: {.class} (default: enabled)
native-divs
HTML <div> elements (default: enabled)

Other Blocks

[extensions]
line-blocks = true
line-blocks
Line blocks for poetry with | prefix (default: enabled)

Inline Extensions

Emphasis

[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)

Images

[extensions]
inline-images = true
implicit-figures = true
inline-images
Inline images ![alt](url) (default: enabled)
implicit-figures
Single image becomes figure (default: enabled)

Math

[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

[extensions]
inline-footnotes = true
footnotes = true
inline-footnotes
Inline footnotes ^[text] (default: enabled)
footnotes
Reference footnotes [^1] and [^1]: content (default: enabled)

Citations

[extensions]
citations = true
citations
Citation syntax [@cite] (default: enabled)

Spans

[extensions]
bracketed-spans = true
native-spans = true
bracketed-spans
Bracketed spans [text]{.class} (default: enabled)
native-spans
HTML <span> elements (default: enabled)

Metadata Extensions

[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

[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

[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

[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

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

NoteYAML

YAML is special: Panache has built-in YAML formatting for frontmatter and hashpipe chunk options based on 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:

[formatters]
r = "air"
python = "ruff"
javascript = "prettier"
typescript = "prettier"

You can also specify multiple formatters for a language, which will run sequentially:

[formatters]
python = ["isort", "black"]

Go to Formatter Presets for a list of built-in presets.

Custom Formatters

Define custom formatter configurations with the [formatters.NAME] syntax:

[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:

[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):

    [formatters.air]
    args = ["format", "--custom-flag", "{}"]
  • Override only cmd (inherits default args and stdin):

    [formatters.ruff]
    cmd = "ruff-custom"
  • Override everything (complete replacement):

    [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-args1.

[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:

[formatters.air]
prepend-args = ["--verbose"]
append-args = ["-i", "2", "--check"]

This will produce the following final args: ["--verbose", "format", "{}", "-i", "2", "--check"].

File-Based Formatters

For formatters that modify files in place:

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

Placeholders

Formatter args support the following placeholders, substituted per code block before the formatter is invoked:

{}
The temp file path (in file mode) or a language-aware virtual stdin filename like stdin.py (in stdin mode). If omitted in file mode, the path is appended at the end of the args.
{lang}
The literal language string from the code fence, e.g. python, javascript, bash. Useful when the external tool takes a language name as a parameter (e.g. Prettier’s --parser).
{ext}
The conventional file extension for the language, e.g. py, js, sh. Panache maintains a built-in language — extension table covering the common languages; unknown languages fall back to txt.

This makes it practical to delegate every code block to a monolithic formatter that dispatches by extension internally, e.g. dprint:

[formatters.python]
cmd = "dprint"
args = ["fmt", "--stdin", "snippet.{ext}"]

[formatters.rust]
cmd = "dprint"
args = ["fmt", "--stdin", "snippet.{ext}"]

Untagged Code Blocks

To register a formatter that runs on fenced code blocks with no language tag (e.g. for aligning ASCII tables or box-drawing characters), use the empty-string key "":

[formatters.""]
cmd = "boxalign"

This matches only truly untagged blocks:

```
+---+---+
| a | b |
+---+---+
```

A block tagged with an explicit language — including ```plain — is not matched by [formatters.""]. If you also want to format ```plain blocks, register a separate [formatters.plain] entry.

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

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 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:

[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
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:

[linters]
r = "jarl"
python = "ruff"

[formatters]
r = "air"
python = "ruff"

Example Configuration

Complete example with some common options:

flavor = "quarto"
line-width = 80

[format]
wrap = "reflow"
math-delimiter-style = "preserve"
math-indent = 0

[extensions]
hard-line-breaks = false
citations = true
task-lists = true

emoji = false

[formatters]
r = "air"
python = "ruff"

Footnotes

  1. The idea of append-args and prepend-args is taken from the conform.nvim Neovim plugin.↩︎