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:

Explicit path: --config <path> (errors if invalid)
Project config: .panache.toml, panache.toml, or .config/panache.toml in current or parent directories
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, 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.

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

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 and extend-include accumulate across the whole chain (parent patterns then child patterns), whereas a plain exclude or include replaces the inherited list. This mirrors the additive naming used elsewhere (see File Selection).

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.

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.

Keys that were valid in older releases and have since been deprecated still parse, but Panache prints a warning. The current crop is:

snake_case names under [extensions] (e.g. quarto_crossrefs → use quarto-crossrefs)
snake_case fields under [formatters.*] (e.g. prepend_args → prepend-args)
the top-level, [format], or [style] code-blocks table (now a no-op)
the top-level, [format], or [style] blank-lines key (now a no-op)
the top-level [style] section itself (use [format])
top-level line-width and line-ending (use [format] line-width and [format] line-ending)

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)
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]. MyST files use the plain .md extension, so this flavor is opt-in only (set flavor = "myst", use --flavor myst, or a [flavor-overrides] glob); 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 [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 under [format]:

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

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.

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:

The --flavor CLI flag, if supplied, overrides everything below
.qmd files always use quarto
.Rmd files always use rmarkdown
.svx and .svelte.md files always use mdsvex
Markdown-family files use the most specific matching flavor-overrides pattern
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 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.

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

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. Some Quarto extensions inject 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. Because their targets are defined by an extension mechanism Panache does not model, such cross-references are also exempt from the undefined-references check.

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

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

Math Formatting

Configure how math delimiters are formatted:

[format]
math-delimiter-style = "preserve"
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.

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

Experimental Features

The [experimental] table gates features that are opt-in and unstable. Their behavior—and the option surface itself—may change, or be removed, without a major release. Do not depend on them for stable output.

[experimental]
format-math = false

`format-math`

When enabled, Panache reformats the content of math spans ( $...$ , $$...$$, and $...$ or \[...\]) structurally:

inline whitespace runs collapse to a single space;
environment bodies (\begin{aligned}…\end{aligned} and friends) are indented two spaces and laid out one row per line;
\\ line breaks are normalized to a trailing \\;
& columns in alignment environments are aligned;
operators are spaced precedence-aware—a binary or relational operator gets one space on each side (a+b → a + b, a<=b → a <= b), while a unary minus or plus stays tight (x = -y, f(-x)).

Macros are not rewritten—no \frac/\dfrac canonicalization and no inserting alignment &. Column alignment uses source character widths, so it tidies the source rather than aligning rendered glyphs (\alpha counts as six columns). Malformed math (unbalanced braces or environments) and content with a lone unescaped $ is left verbatim.

Standalone TeX blocks (a bare \begin{env}…\end{env} that is not wrapped in math delimiters) are not affected—they are kept opaque by the parser.

Default is false (math content is emitted verbatim).

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:

flavor defaults
global [extensions]
[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
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 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)

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)

Links

[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)
spaced-reference-links: Allow whitespace—spaces, tabs, or a single newline—between the two bracket pairs of a reference link or image: [foo] [bar], ![alt] [bar], [foo] []. Without the extension, [foo] [bar] parses as a shortcut [foo] followed by literal text. Also applies to reference images (default: disabled, non-default extension).
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 with a recognized URI scheme (e.g. https:, mailto:) become links (default: disabled, non-default extension)

Wikilinks

[extensions]
wikilinks-title-after-pipe = true
wikilinks-title-before-pipe = false

wikilinks-title-after-pipe: Wikilink syntax [[url]] and [[url|title]]—URL first, optional title after the pipe. Image variant ![[url]] or ![[url|title]] is also recognized. Single-line shape, non-greedy on the first ]], empty bodies ([[]]) are treated as literal text. Title content is not recursively parsed for inline markup, mirroring pandoc behavior (default: disabled, no flavor default).
wikilinks-title-before-pipe: Same as above but with title before the pipe: [[title|url]]. The two extensions are mutually exclusive in intent; if both are enabled, wikilinks-title-after-pipe takes precedence (matches pandoc).

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
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: 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. A dash that would land alone on a line (e.g. a paragraph that is just ---) is left as the Unicode character instead, since ---/-- there would re-parse as a thematic break or setext underline.
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.

YAML

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

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

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

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

Collection - Gathers all code blocks of the configured language
Concatenation - Combines blocks with blank-line preservation to maintain original line numbers
Analysis - Runs the external linter on the concatenated code
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"

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

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

emoji = false

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

Footnotes

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

Extending Another Config

Validation

Editor Support

VS Code (Even Better TOML)

Inline #:schema directive

Other editors

Basic Options

Flavor

Line Width

Line Endings

Flavor Overrides

File Selection (Directory Traversal)

Compatibility Targets

Cross-Reference Prefixes

CLI Cache

Formatting Style

Wrapping Mode

Sentence-Wrapping Abbreviations

Math Formatting

Table Indentation

Tab Stops

Experimental Features

format-math

Extensions

Block-Level Extensions

Headings

Block Quotes

Lists

Code Blocks

Tables

Divs

Other Blocks

Admonitions

Inline Extensions

Emphasis

Links

Wikilinks

Images

Math

Footnotes

Citations

Spans

Metadata Extensions

Raw Content Extensions

Special Character Extensions

Quarto-Specific Extensions

Bookdown Extensions

External Formatters

Basic Usage

Custom Formatters

Formatter Fields

Preset Inheritance

Examples

Incremental Argument Modification

File-Based Formatters

Placeholders

Untagged Code Blocks

Behavior

Presets

External Code Linters

Quick Start

How It Works

Where Linters Run

Behavior

Example

Example Configuration

Footnotes

Inline `#:schema` directive

`format-math`