Skip to main content

Configuration Reference

Configuration options, defaults, discovery rules, and external-tool settings for Panache.

For a walkthrough of creating and sharing a project config, see the configuration guide.

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. Custom user config: the file named by PANACHE_CONFIG, when set and non-empty (errors if missing or invalid)
  4. User config: panache/config.toml in the platform’s user configuration directory—$XDG_CONFIG_HOME or ~/.config on Linux, ~/Library/Application Support on macOS, and %APPDATA% on Windows

For the project-config step, discovery walks up from the file being processed and uses the nearest panache.toml, .panache.toml, or .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 or .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.

Set PANACHE_CONFIG to keep your user config at a custom location, such as a synced drive. It replaces the platform user config fallback. Project configs still take precedence, and files from different discovery steps are not merged. Use extend when you want a project to inherit your user config. Relative PANACHE_CONFIG paths resolve from the process’s working directory; an absolute path is recommended for editor settings. An unset or empty value uses the normal user config location. --isolated ignores all config files, including PANACHE_CONFIG.

In VS Code, add this to your user settings.json, then run Panache: Restart Server:

{
  "panache.serverEnv": {
    "PANACHE_CONFIG": "P:/Softwares/panache.toml"
  }
}

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 the patterns under [flavors]—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).

Extending Another Config

A config file can inherit from another with the extend key, then override just the parts it needs—the same mechanism as Ruff’s extend:

# Inherit everything from the shared config in the parent directory...
extend = "../panache.toml"

# ...but use a wider line for this subproject.
[format]
line-width = 100

extend takes a single path to another config file. It is resolved relative to the file that declares it (not the current working directory); a leading ~ expands to your home directory, and absolute paths are used as-is.

Merge semantics:

  • The extending file wins. Any scalar it sets (like line-width above) overrides the base. Keys it leaves out are inherited.
  • Sections merge key by key. Setting one [format] key does not discard the base’s other [format] keys.
  • extend-exclude, extend-include, and extend-select accumulate across the whole chain (parent patterns then child patterns), whereas select, ignore, exclude, or include replaces the inherited list. This mirrors the additive naming used elsewhere (see File Selection).
  • [flavors] entries merge by path pattern. A child inherits patterns it does not mention; assigning an inherited pattern to another flavor moves it to that flavor.

Chaining is transitive—a may extend b which extends c—and the values flow down the whole chain. A cycle (a extends b extends a) or a missing base file is a hard error that names the offending file.

Unlike discovery, extend is explicit and is not capped by the .git project boundary: a shared base config may live above the project root or in a sibling tree. The LSP watches every file in the chain, so editing a base config reloads the open documents that inherit from it.

Validation

Panache validates every config it loads. Unknown keys are a hard error rather than a silent drop, so a typo like lin-width = 100 or [forrmat] fails the run with a message that names the offending key and lists the accepted ones:

Error: invalid config /path/panache.toml: TOML parse error at line 1, column 1
  |
1 | lin-width = 100
  | ^^^^^^^^^
unknown field `lin-width`, expected one of `flavor`, `extensions`,
`line-ending`, `line-width`, `pandoc-compat`, `compat`, `format`, ...

Extension names are validated against the canonical set, including inside per-flavor subtables, and the error suggests the closest valid name:

Error: invalid config /path/panache.toml: unknown extension
`quato-crossrefs` in [extensions]; did you mean `quarto-crossrefs`?

This is true regardless of how the config was found: a typo in a discovered panache.toml fails the run just like a broken --config path, rather than being silently ignored in favor of the user config or built-in defaults.

The same validation applies to panache format -o extensions.<name>=<bool>. Unknown names fail the run with exit code 2 and suggest a close match when one exists.

In the language server the same parse failure is surfaced rather than swallowed:

  • a diagnostic is published on the offending panache.toml, anchored at the bad key (so it shows even when the config file isn’t open), and
  • a one-time notification pops up, and
  • formatting is refused until the config parses again—Panache will not silently format with default settings while your config is broken.

All three clear automatically once the config parses, and formatting resumes.

Some keys that were valid in older releases are still accepted as deprecated aliases and print a warning. The current crop is:

  • top-level line-width and line-ending (use [format] line-width and [format] line-ending)
  • top-level pandoc-compat (use [compat] pandoc)
  • the top-level or [format] blank-lines key (now a no-op)
  • [flavor-overrides] (use [flavors]). It may be removed only in a major release on or after March 8, 2027.

The following were removed in 3.0 and are now rejected (the parse error includes a hint pointing at the replacement key where one exists):

  • snake_case names under [extensions] (use kebab-case, e.g. quarto-crossrefs instead of quarto_crossrefs)
  • snake_case fields under [formatters.*] (use prepend-args / append-args)
  • the code-blocks table in any position (long a no-op)
  • the top-level [style] section (use [format])
  • the flat [lint] rule = true shape (use [lint] extend-select or ignore)
  • the per-language [formatters.<lang>] config format with preset/enabled (use the [formatters] <lang> = "<name>" mapping)

Lint Rule Selection

Key Type Default Behavior
select Array of rule names Unset Replaces the default rule set when supplied.
extend-select Array of rule names [] Adds rules to the defaults or explicit selection.
ignore Array of rule names [] Disables rules after selection and additions.
rules Table of booleans {} Deprecated overrides for the default rule set.

Selectors use exact names from the rule reference. select = [] disables the defaults. Rules added by extend-select still run unless listed in ignore, and flavor and extension requirements still apply. These settings control built-in lint rules; they do not suppress parser errors or select rules in external linters.

When extending another config, select and ignore replace inherited lists, while extend-select accumulates. Deprecated [lint.rules] entries merge by key and preserve their behavior when no new selection settings are supplied. If both forms are present, the booleans modify the defaults, select replaces that base set, extend-select adds rules, and ignore removes rules last.

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
jupyter
JupyterLab Markdown (GFM with Jupyter math), auto-detected for .ipynb files.
hugo
Hugo-flavored Markdown, using the CommonMark dialect with Goldmark’s default tables, strikethrough, task lists, bare autolinks, definition lists, reference footnotes, heading attributes, and heading identifiers. Enables YAML front matter, toml-metadata-block, and hugo-shortcodes.
commonmark
CommonMark
multimarkdown
MultiMarkdown flavor defaults (Pandoc-compatible MultiMarkdown extension set)
mdsvex
mdsvex (Svelte-flavored Markdown). Svelte template constructs are treated as opaque, lossless spans preserved verbatim: block logic ({#if}/{:else}/{/each}), tags ({@html ...}), and expressions ({expr}). A span that occupies a whole line on its own becomes a block-level construct, so an immediately following list or paragraph stays a separate block instead of being folded onto one line.
myst
MyST (CommonMark superset used by Sphinx myst-parser/myst-nb). Enables MyST directives, roles, targets, comments, and +++ block breaks by default, plus the GFM-superset rules myst-parser turns on (pipe tables, reference footnotes, leading --- YAML front matter); MyST markup extensions (colon_fence, attrs, dollarmath, etc.) are opt-in via [extensions], using myst-colon-fence and so on. MyST files use the plain .md extension, so this flavor is opt-in only (set flavor = "myst", use --flavor myst, or a [flavors] pattern); it is never auto-detected from the file extension.

The --flavor CLI flag (see the CLI reference) overrides this setting for a single invocation. It also overrides [flavors] 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 under [format]:

[format]
line-width = 80

The default is 80, and the width is measured in Unicode display columns, not characters or bytes: East Asian wide characters count as two columns, so x宮 is 3 columns (rather than 2 characters or 4 UTF-8 bytes), matching how wide the text renders in a terminal.

You do not need to set wrap for line-width to apply: the default wrap = "reflow" already refills paragraphs to this width. The other wrap modes leave paragraphs alone, but line-width still governs table captions, horizontal-rule length, YAML scalar folding, and display-math breaking.

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.

Note

A top-level line-width (outside [format]) is still accepted as a deprecated alias and prints a warning. The [format] value wins when both are set.

Line Endings

Control the line ending written to formatted output under [format]:

[format]
line-ending = "auto"

auto (the default) preserves the document’s existing convention, lf forces Unix line endings, and crlf forces Windows line endings. As with line-width, a top-level line-ending is still accepted as a deprecated alias and [format] wins when both are set.

Horizontal Rules

Control how horizontal rules are rendered under [format]:

[format]
horizontal-rule-style = "line-width"

line-width (the default) expands every rule to a full line of hyphens, matching Pandoc’s Markdown writer and keeping rules visually distinct from YAML metadata delimiters. compact emits a three-dash --- instead, which keeps long-form source lightweight and avoids soft-wrapping in narrow editor viewports. Panache always surrounds rules with blank lines, so a compact --- is never reparsed as a YAML delimiter or setext heading underline.

Per-file Flavors

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

flavor = "quarto"

[flavors]
gfm = ["README.md", "AGENTS.md", "CONTRIBUTING.md"]
quarto = ["docs/**/*.md"]

Each key is a built-in flavor, and each value is an array of glob patterns. A pattern may appear under only one flavor. When several different patterns match the same file, the most specific pattern wins.

The former pattern-to-flavor form remains available as a deprecated alias:

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

When both forms assign the same pattern, [flavors] wins. The deprecated form may be removed only in a major release on or after March 8, 2027.

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. .svx and .svelte.md files always use mdsvex
  5. Markdown-family files use the flavor associated with the most specific matching [flavors] pattern
  6. 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 and 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 and exclude globs (and patterns under [flavors]) 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 PANACHE_CONFIG and global user configs have no project location, so their globs resolve against the directory being traversed (typically the current working directory), or the document’s directory in the LSP.
  • 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.

Compatibility Targets

The [compat] section declares which upstream toolchain versions you author for.

[compat]
pandoc = "3.9"
quarto = "1.9"
pandoc

Compatibility target for ambiguous Pandoc behavior, used where Pandoc behavior changed across releases.

  • 3.12 (default): match Pandoc 3.12 behavior.
  • 3.11: match Pandoc 3.11 behavior.
  • 3.10: match Pandoc 3.10 behavior.
  • 3.9: match Pandoc 3.9 behavior.
  • 3.7: match Pandoc 3.7 behavior.
  • latest: alias for Panache’s pinned newest verified target (currently 3.12).

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.

The difference between 3.9 and 3.10 is that Pandoc 3.10.1 requires an ordered sublist to start at 1 — or its equivalent in the marker’s own numbering (i., a., A., (1)) — bringing the Markdown reader in line with CommonMark and avoiding unintended list starts. Under 3.10,

-   Item
    2.  Not a sublist

reads 2. Not a sublist as a paragraph rather than opening a list. Lists at the top level (including inside blockquotes and fenced divs) still accept any start number, as do sibling items continuing a list that is already open. Set pandoc = "3.9" if you author for an older Pandoc.

Pandoc 3.11 adds (1@label) to reset the example-list counter. With the example-lists extension enabled, targets 3.11, 3.12, and latest recognize the reset, preserve its marker during formatting, and resolve references such as (@label) to the assigned number. For example,

(@first) First example.

A new chapter begins.

(1@chapter) Restart at one.
(@next) Continue at two.

See (@chapter) and (@next).

A reset may specify another number, such as (10@label), or omit the label, as in (1@). Earlier targets keep reset-shaped text in paragraphs. The ordered-sublist rule still applies: a new nested example list must start at one, though a reset may change the counter within an open list.

Pandoc 3.12 compacts table paragraphs only when every cell is empty or contains a single paragraph. A cell containing a heading, code block, or multiple paragraphs keeps the other cells’ paragraphs as Para in the Pandoc AST. Earlier targets compact each single-paragraph cell to Plain independently. This affects AST export without changing table formatting.

quarto

Quarto release whose vendored schema the quarto-schema lint rule validates against (e.g. "1.9"). One version is currently bundled, so this is an advisory pin that reserves the key for selecting among bundled versions later.

Note

The top-level pandoc-compat key is deprecated in favor of [compat] pandoc and still works as an alias. The former [lint] quarto-version key moved to [compat] quarto.

Cross-Reference Prefixes

Quarto recognizes a fixed set of cross-reference prefixes (@fig-, @tbl-, @eq-, @sec-, @thm-, and so on), and Panache treats keys with those prefixes as cross-references rather than citations. Custom float types and some Quarto extensions introduce additional prefixes that Panache cannot discover on its own—for example the pseudocode extension makes @algo- a cross-reference. Without help, Panache parses @algo-cd as a citation and the linter reports it as a missing bibliography key.

List those extra prefixes under the top-level crossref-prefixes key:

crossref-prefixes = ["algo"]
crossref-prefixes

Extra cross-reference key prefixes (the segment before the first -). Matching is case-insensitive. Keys with these prefixes parse as cross-references, so the linter no longer flags them as citations. The undefined-references rule validates their targets just as it does for built-in prefixes, using IDs and executable chunk labels in the document or project. Panache does not execute extensions to discover generated targets, so references to those targets may be reported as undefined.

CLI Cache

Panache can persist CLI lint and format cache entries between runs to speed up workspace re-runs when files and config are unchanged.

cache = true
cache-dir = "/absolute/path/to/cache-dir"
cache
Enable the on-disk lint and format cache (default: true). Set to false to disable cache reads and writes for the project. --no-cache and PANACHE_NO_CACHE force the cache off for a single invocation regardless of this setting.
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 and 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 = "reflow"
math-indent = 2
table-indent = 2
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, reflowing away existing breaks.
semantic
Keep existing line breaks and add a break after each sentence (semantic line breaks). Ignores line width.
preserve
Keep existing line breaks and literal indentation, including in list continuation paragraphs.

In reflow, sentence, and semantic modes, multiline link titles are joined with spaces. Newlines inside shortcode URLs remain intact.

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

Sentence-Wrapping Abbreviations

In sentence and semantic modes, Panache must decide whether a trailing period ends a sentence or merely an abbreviation (etc., e.g., et al.). It picks a built-in abbreviation list from the document’s language, read from the YAML lang: metadata (the same field Quarto and Pandoc use). Built-in profiles ship for English (en), Czech (cs), German (de), Spanish (es), and French (fr); unknown languages fall back to English. Region subtags fold to their primary subtag, so de-AT uses the German profile.

When the document has no lang:, set a fallback for the project:

[format]
wrap = "sentence"
lang = "de"

To extend the built-in list with your own tokens, add no-break-abbreviations. A flat list applies to every document and is merged with the built-in profile:

[format]
wrap = "sentence"
no-break-abbreviations = ["př.", "čís."]

For multilingual projects, use a table keyed by language code (the primary subtag). The default bucket applies to every document, and the bucket matching the document’s language is added on top:

[format.no-break-abbreviations]
default = ["etc."]
cs = ["např.", "tzv."]
de = ["bzw.", "usw."]

A citation or cross-reference attached directly to a sentence-ending period stays with the sentence. For example, sentence wrapping changes Text.[@citation] Next sentence. to:

Text.[@citation]
Next sentence.

Smart Punctuation

Choose how Panache writes punctuation in prose:

[format]
smart-punctuation = "unicode"

For a single invocation, use panache format -o smart-punctuation=unicode.

preserve
Leave ASCII and Unicode punctuation as written.
ascii
Convert English curly quotes and apostrophes to straight quotes, en and em dashes to -- and ---, and ellipses to .... Quote conversion requires smart or smart-quotes; dash and ellipsis conversion requires smart. With both extensions disabled, punctuation stays as written.
unicode
Convert paired straight quotes to English curly quotes, apostrophes to ’, -- to –, --- to —, and ... to …. Existing Unicode quotation marks and unpaired straight double quotes keep their spelling.

The default is preserve for every flavor. To retain the ASCII normalization used by earlier releases for Pandoc, Quarto, and R Markdown, set smart-punctuation = "ascii" in [format].

The preserve and unicode modes work independently of the smart and smart-quotes extensions, including with CommonMark and GFM. An explicit ascii selection still requires the corresponding extension. Code, math, URLs, email addresses, attributes, link titles, escaped punctuation, and raw markup stay unchanged. Bare URL and email protection extends across inline markup in both conversion modes, even when autolink-bare-uris is disabled. Escaped punctuation still determines the direction of adjacent quotes. Panache resolves inline constructs across line-block continuations before normalizing prose. Multiline table cells normalize punctuation across continuation lines before reflow while preserving hard breaks and reference link labels. Unicode conversion preserves heading text when auto-identifiers or implicit-header-references is enabled so generated identifiers and implicit heading links keep working, including headings with explicit IDs when automatic identifiers are disabled. If Unicode conversion would turn literal bracketed text into a reference link, Panache escapes the literal opening brackets with character entities.

Math Formatting

Configure math content formatting, delimiters, and display indentation:

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

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 2; set it to 0 to keep content flush against the left margin.

math

The math mode controls how Panache formats the content of math spans ($...$, $$...$$, \(...\), and \[...\]) and recognized raw math environments:

reflow
Apply the canonical math style and wrap over-width free display equations at top-level punctuation, \qquad separators, relations, and binary operators. This is the default.
preserve
Apply the canonical math style, but retain authored top-level soft line breaks in free display equations. Panache does not add width-based breaks.
single-line
Apply the canonical math style, flatten authored top-level soft line breaks in free display equations, and never add width-based breaks. Structural rows marked with \\ and environment rows remain multiline.
verbatim
Do not structurally format math content. The Markdown host—including delimiter style and display indentation—may still be normalized.

Every non-verbatim mode collapses inline whitespace, tightens scripts, trims math-mode group interiors, normalizes \\ row breaks, indents environment bodies, aligns & columns, and spaces operators according to their role. Math alignment is therefore on by default and remains on in preserve and single-line; it is not a separate option.

Macros are never rewritten: Panache does not canonicalize \frac/\dfrac, insert alignment markers, or expand user definitions. Alignment measures source characters rather than rendered glyphs, so \alpha counts as six columns. Malformed math, a lone unescaped $, and structures whose semantics Panache cannot establish safely are preserved. See Math for an example of the formatting style.

The option is stable and independent of Markdown flavor and parser extensions. The parser always builds the lossless math CST; this option controls only the formatter’s content and soft-line policy.

Math Command Signatures

Panache formats a command argument recursively only when the command’s signature proves that the argument contains math. Add signatures for project or package commands under [format.math-signatures]; command names omit the leading backslash, contain only ASCII letters or @, and arguments appear in source order:

[format.math-signatures]
custom = [
  { kind = "bracket", domain = "unknown" },
  { kind = "brace", domain = "math" },
]
textual = [{ kind = "brace", domain = "text" }]

kind is bracket for an optional […] argument or brace for a required {…} argument. domain is math, text, or unknown; text and unknown arguments are preserved byte-for-byte. A configured signature replaces the complete built-in signature for that command. A \newcommand, \def, or other recognized raw-TeX definition in the document shadows both configured and built-in signatures because Panache does not expand replacement bodies.

Signatures change output in every math mode except verbatim.

Table Indentation

The table-indent field sets how many columns top-level pipe, simple, and multiline tables are indented:

[format]
table-indent = 2

It accepts an integer from 0 to 3 and defaults to 2. Set it to 0 to keep tables flush at column 0 (matching Pandoc’s pipe-table writers).

Grid tables are the exception: they always stay flush at column 0 regardless of this setting, because Pandoc only recognizes a grid table whose +---+ border starts at column 0.

This setting affects only top-level tables. A table nested inside a list item or other container still honors the container’s content indentation.

The -o table-indent=<N> flag on panache format can override this setting for a single invocation, e.g. panache format -o table-indent=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). Code spans use each tab’s column in the source line, including container prefixes and table columns, to preserve their literal content.
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).

Deprecated Experimental Setting

The former experimental spelling remains a compatibility alias:

[experimental]
format-math = false

Panache warns when it reads this spelling. Replace true with [format] math = "reflow" and false with [format] math = "verbatim". If a configuration contains both spellings, [format] math wins. The alias will be removed in a future major release.

Extensions

Run panache inspect document.qmd to list every extension’s effective state alongside its default for the resolved flavor. Use panache inspect --isolated --flavor pandoc to list only built-in defaults, or pass -o extensions.<name>=<bool> to inspect a one-off override. See inspecting settings for details. Add --json for machine-readable output.

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). Disabled for mdsvex, which renders headings through rehype with no plugins of its own, so a heading gets an id only if you add rehype-slug — if you do, turn this back on.
gfm-auto-identifiers
Use GitHub’s heading identifier algorithm (default: disabled, enabled for gfm and mdsvex). This only selects the slug algorithm; with auto-identifiers disabled no identifier is generated at all, which is why mdsvex selects the algorithm without enabling identifiers: rehype-slug slugs with github-slugger, so this is the right choice for the sites that do install it.
blank-before-header
Require blank line before headers (default: enabled)
header-attributes
Full attribute syntax on headers {#id .class key=value} (default: enabled for pandoc, quarto, and rmarkdown). When disabled, a trailing {...} is ordinary heading text, matching pandoc -f commonmark.
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
four-space-rule = false
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)
four-space-rule
Pandoc <= 2.0 list semantics: list continuation paragraphs and nested lists require four-space (one tab-width) indentation rather than lining up with the first character after the marker (default: disabled, non-default extension). Enable this to produce output that strict Markdown parsers such as Python-Markdown accept—they treat two-space-indented continuations as escaping the list. When enabled, the formatter indents nested and continuation content a flat four columns per level (- a with nested - a1); markers keep their normal trailing space.

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 classic R inline expressions such as `r x` and R Markdown nested-backtick tails (default: disabled, enabled for Quarto and RMarkdown flavors). Executable expressions participate in external linting.
quarto-inline-code
Parse braced inline expressions such as `{r} x`, `{python} x`, and `{julia} x`, as well as braced R nested-backtick tails (default: disabled, enabled for Quarto flavor). Executable expressions participate in external linting. Formatting preserves ordinary expressions and extra backticks used to escape them.
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)

In Pandoc-based flavors, <div/> starts a div just like <div>. Following content belongs to it until </div> or the end of its container. Formatting preserves the opening tag’s spelling.

A matched <div>...</div> with an invalid attribute name, such as a&amp;b, stays raw HTML. Its body is preserved without parsing Markdown. Attribute names must start with a Unicode letter and continue with letters, numbers, :, -, or _. Entities in attribute values remain supported.

Without a matching </div> or a self-closing slash, a <div> with an invalid attribute name stays Markdown text. Its body parses as Markdown, and the rejected opener does not declare an anchor.

A self-closing <div .../> with an invalid attribute name stays one raw tag. The raw tag ends at the first >, even inside a quoted value. Following content is parsed as Markdown outside it.

Other Blocks

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

Admonitions

[extensions]
python-markdown-admonitions = true
pymdownx-details = true
python-markdown-admonitions
python-markdown admonitions — !!! type "title" with 4-space-indented content (default: disabled for all flavors). Required because the indented body would otherwise parse as an indented code block.
pymdownx-details
Collapsible admonitions from pymdownx.details—??? (collapsed) and ???+ (expanded) (default: disabled for all flavors). Independent of python-markdown-admonitions.

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
A block whose entire content is a single image becomes a figure (default: enabled). This covers a paragraph, a blockquote body, a list item, and a definition-list body alike. Any other content in the block—including a lazy continuation line—keeps it an ordinary paragraph.

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)

Pandoc-family flavors require attribute names to start with a Unicode letter and continue with letters, numbers, :, -, or _. An invalid name, such as _bad or a&b, leaves the opener as Markdown text instead of creating a native span. Markdown in the body still parses, and </span> stays raw inline HTML. The rejected opener does not declare an anchor.

When matching a native span’s closing tag, Panache skips code spans, escaped tags, and raw inline HTML, including comments and quoted attribute values. Rejected inner <span> openers do not add nesting depth, so their closing tag can close the surrounding native span.

Metadata Extensions

[extensions]
yaml-metadata-block = true
pandoc-title-block = true
toml-metadata-block
Recognize +++ TOML front matter at the beginning of a document, allowing initial blank lines and a byte order mark. Preserve contents verbatim, including invalid TOML and unterminated blocks. Unterminated blocks retain trailing spaces and blank lines, even at the end of the document. Does not recognize metadata inside lists or blockquotes, or later in the document. Enabled by default for hugo; disabled for other flavors.
yaml-metadata-block
YAML frontmatter with --- delimiters (default: enabled). Pandoc-family flavors also accept metadata blocks mid-document when preceded by a blank line; CommonMark-family flavors (gfm, commonmark, mdsvex, myst, hugo) only recognize document-start frontmatter, matching pandoc’s gfm reader.
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
east-asian-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)
east-asian-line-breaks
Suppress the soft-break-derived space when a newline sits between two East Asian wide characters. Useful for CJK documents where reflow would otherwise insert a stray ASCII space (e.g. 路\n名 becoming 路 名). Default: disabled, non-default extension. Under the default wrap = "reflow", Panache joins soft-wrapped lines regardless of this setting; the extension only controls whether a join between two wide characters keeps a stray space (off) or drops it (on). Enable it when you reflow CJK text and want the result to read correctly. To instead keep your manual line breaks, set wrap = "preserve"—turning this extension off will not preserve them, since reflow still collapses the lines. The behavior matches Pandoc’s east_asian_line_breaks extension.
smart
Describes smart interpretation of ASCII punctuation by the target reader, including quotes, dashes, and ellipses. Defaults: enabled for pandoc, quarto, and rmarkdown; disabled for other flavors. Enables quote, dash, and ellipsis normalization when smart-punctuation is ascii.
smart-quotes
Describes smart interpretation of quotes and apostrophes only. Default: disabled. Enables quote and apostrophe normalization when smart-punctuation is ascii, leaving dashes and ellipses unchanged unless smart is also enabled.
emoji
Emoji syntax :emoji: (default: disabled, non-default extension)
mark
Highlighted text ==highlighted== (default: disabled, non-default extension)

Hugo-Specific Extensions

[extensions]
hugo-shortcodes = true
hugo-shortcodes
Preserve Hugo shortcode calls and paired bodies verbatim. Supports both {{< ... >}} and {% ... %}, multiline arguments, quoted and raw strings, closing and self-closing tags, nesting, inline shortcode templates, and escaped calls such as {{< foo >}}.

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). Shortcodes in link and image destinations retain their closing delimiters, including when arguments are quoted.

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

NoteMyST directive bodies

Verbatim MyST directive bodies ({code}, {code-block}, {code-cell}) are routed to external formatters too, keyed by the directive argument as the language. For example, the body of ```{code-block} python is formatted with the python formatter, just like a fenced ```python block.

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"]

The language key matches a code block by its language alias group, so common aliases are interchangeable: a jl key formats {julia} blocks, py matches python, rs matches rust, and sh matches bash or zsh. An exact key match always wins, so you can still register different chains for spellings that resolve to distinct languages.

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)
code-style-args
Map each supported code style option to arguments appended when a code block supplies that option. Use {value} in an argument to insert the block’s scalar value.

Code Style Metadata

code-style is a tool-independent metadata mapping for formatting source code in fenced blocks. A formatter may translate supported keys into its own settings. The metadata does not control code execution or the appearance of rendered code. This is a Panache convention proposed for use by other source formatters. Recognition in Quarto’s cell-option schema is still under discussion.

For an executable Quarto cell, write the mapping in the hashpipe preamble:


::: {.cell code-style='{"line-width":40,"indent-width":2}'}

```{.r .cell-code}
result <- some_function(first_argument, second_argument)
```
:::

For an ordinary fenced block, encode the same mapping as a YAML flow mapping in a Pandoc code-block attribute:

```{.r code-style="{line-width: 40, indent-width: 2}"}
result <- some_function(first_argument, second_argument)
```

Both forms have the same scope and meaning. The ordinary fence syntax uses an attribute because its body is displayed code, so a #| line there would become part of the example. Pandoc preserves the attribute on the code block.

To set defaults for every code block in a document, put code-style in its YAML front matter:

---
code-style:
  line-width: 88
  indent-width: 2
---

These defaults apply to executable cells and displayed code blocks. A block’s own code-style mapping overrides individual keys from the front matter. For example, a block with #| code-style: {line-width: 40} keeps the document’s indent-width: 2.

Pandoc permits multiple YAML metadata blocks. When more than one sets code-style, the last mapping replaces the earlier mapping for the entire document, including code blocks before it. The mappings do not merge, and the setting does not switch midway through the document. Repeating a YAML key in one metadata block makes Pandoc warn and use the last value; write each key once to avoid ambiguity.

Option names use lowercase kebab-case. The first defined keys are:

Key Value Meaning
line-width Positive integer Preferred maximum source line width, in display columns. A language formatter may exceed it when a line cannot be broken safely.
indent-width Positive integer Preferred indentation width in columns, where the formatter supports this choice.

The mapping is open to additional keys. Consumers should ignore keys they do not support. Without document or block metadata, a formatter uses its configured defaults. Block options apply only to their own block. Panache ignores non-scalar values and nonpositive values for the two width keys. Keys should be unique within a mapping. If an executable cell has both an inline and a hashpipe code-style mapping, the hashpipe mapping takes precedence.

Panache supplies built-in translations for Arity (line-width, indent-width), Black (line-width), Prettier (line-width, indent-width), and Ruff (line-width). Other presets keep their usual behavior until an adapter is configured. The width is passed to the external formatter, so that formatter’s own wrapping rules still decide the output.

Custom formatter definitions can translate any scalar key with code-style-args. Arguments are appended only when the block contains the corresponding key. {value} is replaced within each argument, and arguments are passed directly to the process without a shell:

[formatters]
r = "my-r-formatter"

[formatters.my-r-formatter]
cmd = "arity"
args = ["format"]
stdin = true

[formatters.my-r-formatter.code-style-args]
line-width = ["--line-width", "{value}"]
indent-width = ["--indent-width", "{value}"]

Named definitions inherit a preset’s translations when they share its name. Entries in code-style-args replace the inherited entry with the same key; an empty argument list disables that translation. Panache formats each block using its own metadata, even when another block has identical source text.

This convention grew out of the Quarto discussion on per-cell source width.

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-to-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
Result caching
Identical code blocks (same language and content) are formatted once and the result is reused, so a document with repeated blocks spawns one process instead of one per block. In a long-lived process (the LSP) results are also reused across edits, so reformatting after changing one block does not re-spawn the formatter for the untouched blocks. The cache keys on the formatter command, arguments, language, and block content—but not on the formatter’s own config files (see Config files below).
Error handling
Failed formatters preserve original code with a warning (failures are never cached)
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 and help commands.
Timeout
30 seconds per formatter (not per chain)
Config files
Formatters respect their own config files (.prettierrc, pyproject.toml, etc.). Because result caching does not track these files, edits to them are picked up on the next cold run (or, in the LSP, after a restart).

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.

Verbatim MyST directive bodies ({code}, {code-block}, {code-cell}) are linted as well, keyed by the directive argument as the language—the body of ```{code-block} python is linted with the python linter, like a fenced ```python block.

Quick Start

Enable linters for specific languages:

[linters]
r = "arity"
julia = "fatou"
latex = "badness"
python = "ruff"
sh = "shellcheck"
js = "eslint"
go = "staticcheck"
rust = "clippy"

Preset Overrides

Override a built-in linter’s command or arguments with a named table:

[linters]
r = "arity"

[linters.arity]
append-args = ["--ignore", "undefined-symbol"]

cmd replaces the executable, and args replaces the complete preset argument list. prepend-args and append-args add arguments before and after that list. Keep the preset’s JSON output flags when replacing args, since Panache uses the preset’s diagnostic parser. Named tables must refer to built-in presets. Panache appends the temporary input file path after the configured arguments.

External linters run from the document’s directory, so tools such as Arity, Fatou, and Badness can discover project configuration. ESLint and Clippy retain their isolated temporary working directories. Input without a document path uses Panache’s working directory. Relative executable and configuration paths are resolved from the tool’s working directory.

Arity, Fatou, and Badness load their configuration by default. For example, [lint] ignore in arity.toml controls Arity’s rules; [lint] ignore in panache.toml controls Panache’s built-in rules. To use Arity’s built-in defaults:

[linters.arity]
args = ["lint", "--no-config", "--output", "json"]

Panache reruns these three linters instead of caching their results across lint runs, so changes to their configuration take effect without editing the document. Explicitly adding --no-config allows Panache to cache their results.

Available linters:

Language Linter Command Notes
R arity arity R linter with JSON diagnostics
R jarl jarl R linter with JSON diagnostics
Julia fatou fatou Julia linter with JSON diagnostics
LaTeX badness badness LaTeX linter with JSON diagnostics (0.14+)
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 arity, fatou, badness, jarl, ruff, and eslint). Fixes that the linter marks as unsafe (arity, fatou, badness) are only applied under --unsafe-fixes. Requires badness 0.14+ for LaTeX (earlier versions lack JSON output and are skipped).

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"

[format]
line-width = 80
wrap = "reflow"
math-delimiter-style = "preserve"
math = "reflow"
math-indent = 2

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

emoji = false

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

Jupyter Markdown

The jupyter flavor is selected automatically for .ipynb files. It uses the CommonMark dialect with GFM tables, task lists, strikethrough, HTML, and Jupyter math. YAML metadata, GitHub alerts, emoji aliases, footnotes, and GitHub-specific math delimiters are disabled by default.

tex-math-jupyter enables JupyterLab’s math boundaries: dollar-delimited math, escaped bracket delimiters, and bare TeX environments. Unlike Pandoc’s dollar rules, whitespace and adjacent digits do not prevent recognition. Inline math can span a single line break. Markdown source uses doubled backslashes for bracket delimiters, such as \\(x\\) and \\[x\\]. The formatter preserves these delimiters by default. Explicit backslash normalization also emits the doubled form. Override extensions under [extensions.jupyter].

Dollar normalization adds a space between adjacent inline math spans to keep their delimiters separate. Standalone Markdown linting with --flavor jupyter includes math syntax and inline math line-break diagnostics.

Math is resolved before table rows and heading underlines, so multiline math stays within its cell or heading. Unmatched delimiters leave ordinary Markdown active. Empty math remains valid when whitespace or delimiters are normalized.

Notebook formatting discovers .ipynb files by default; notebook linting is not supported. Existing include, exclude, and --force-exclude settings apply.

Footnotes

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