Configuration

Panache is designed to be opinionated with sensible defaults, but also configurable enough to accommodate most formatting preferences.

The configuration system is built around a TOML configuration file, which allows you to customize a wide range of options, including formatting preferences, linting rules, external linter and formatter integrations, and more.

Panache searches for a configuration file in the following order:

Explicit path: --config <path> (errors if invalid)
Project config: .panache.toml or panache.toml in current or parent directories
User config: ~/$XDG_CONFIG_HOME/panache/config.toml (typically ~/.config/panache/config.toml)

Basic Options

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

Flavor

Choose the Markdown flavor, which determines default extension 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 Markdownb Flavored Markdown
commonmark: CommonMark (Note that we are currently not fully CommonMark-compliant, and use this option only as a means to setup the correct set of extensions): CommonMark (minimal extensions)

Line Width

Set the maximum line width for text wrapping:

line-width = 80

The default is 80 characters.

Formatting Style

Formatting style preferences are organized under the [style] section:

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

Wrapping Mode

Control how text is wrapped:

[style]
wrap = "reflow"

reflow: Reformat paragraphs to fit within line width (default)
preserve: Keep existing line breaks

Blank Lines

Control blank line handling:

[style]
blank-lines = "collapse"

collapse: Collapse multiple blank lines into one (default)
preserve: Keep all existing blank lines

Math Formatting

Configure how math delimiters are formatted:

[style]
math-delimiter-style = "preserve"
math-indent = 0

Math delimiter styles:

preserve: Keep original delimiter style (default)
dollars: Normalize to $...$ and $$...$$
backslash: Normalize to $...$ and \[...\]

The math-indent field specifies indentation (in spaces) for display math blocks. Default is 0.

Tab Stops

Control how tabs are handled during formatting:

[style]
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).

Code Block Style

Configure code block formatting preferences:

[style.code-blocks]
fence-style = "backtick"
attribute-style = "shortcut"

Fence style options:

backtick: Use ``` fences (default for Quarto/RMarkdown)
tilde: Use ~~~ fences
preserve: Keep original fence style (default for Pandoc)

Attribute style options:

shortcut: Use shortcut form like ```python (default for Quarto/RMarkdown)
explicit: Use explicit form like ```{.python}
preserve: Keep original style (default for Pandoc)

Note

These defaults vary by flavor. Quarto uses backtick and shortcut, while Pandoc preserves original formatting.

Backwards Compatibility

For backwards compatibility, style options can still be specified at the top-level, but this is deprecated:

[style]
wrap = "reflow"
blank-lines = "collapse"

The [style] section format shown above is preferred. If both formats are present, the [style] section takes precedence and a warning will be logged.

Extensions

panache supports 66 Pandoc extensions. Each flavor has sensible defaults, but you can override any extension:

flavor = "quarto"

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

Block-Level Extensions

Headings

[extensions]
blank-before-header = true
header-attributes = true
implicit-header-references = true

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)

Block Quotes

[extensions]
blank-before-blockquote = true

blank-before-blockquote: Require blank line before blockquotes (default: enabled)

Lists

[extensions]
fancy-lists = true
startnum = true
example-lists = true
task-lists = true
definition-lists = true

fancy-lists: Roman numerals, letters, and fancy list markers (default: enabled)
startnum: Start ordered lists at arbitrary numbers (default: enabled)
example-lists: Example lists with (@) markers (default: enabled)
task-lists: GitHub-style task lists - [ ] and - [x] (default: enabled)
definition-lists: Term/definition syntax (default: enabled)

Code Blocks

[extensions]
backtick-code-blocks = true
fenced-code-blocks = true
fenced-code-attributes = true
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)
inline-code-attributes: Attributes on inline code `code`{.class} (default: enabled)

Tables

[extensions]
simple-tables = true
multiline-tables = true
grid-tables = true
pipe-tables = true
table-captions = true

simple-tables: Simple table syntax (default: enabled)
multiline-tables: Multiline cells (default: enabled)
grid-tables: Grid-style tables (default: enabled)
pipe-tables: GitHub-style | tables (default: enabled)
table-captions: Table captions (default: enabled)

Divs

[extensions]
fenced-divs = true
native-divs = true

fenced-divs: Fenced divs ::: {.class} (default: enabled)
native-divs: HTML <div> elements (default: enabled)

Other Blocks

[extensions]
line-blocks = true

line-blocks: Line blocks for poetry with | prefix (default: enabled)

Inline Extensions

Emphasis

[extensions]
intraword-underscores = true
strikeout = true
superscript = true
subscript = true

intraword-underscores: Don’t trigger emphasis in snake_case (default: enabled)
strikeout: Strikethrough ~~text~~ (default: enabled)
superscript: Superscript ^super^ (default: enabled)
subscript: Subscript ~sub~ (default: enabled)

Links

[extensions]
inline-links = true
reference-links = true
shortcut-reference-links = true
link-attributes = true
autolinks = true
autolink-bare-uris = false

inline-links: Inline links [text](url) (default: enabled)
reference-links: Reference links [text][ref] (default: enabled)
shortcut-reference-links: Shortcut reference links [ref] (default: enabled)
link-attributes: Attributes on links [text](url){.class} (default: enabled)
autolinks: Automatic links <http://example.com> (default: enabled)
autolink-bare-uris: Bare URLs become links (default: disabled, non-default extension)

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-single-backslash = false
tex-math-double-backslash = false

tex-math-dollars: Dollar-delimited math $x$ and $$equation$$ (default: enabled)
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)

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
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)
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-references: Bookdown references \@ref(label) and (\#label) (default: disabled, enabled for RMarkdown flavor)

External Code Formatters

panache can invoke external formatters for code blocks. Formatters are opt-in—you choose which languages to format.

Basic Usage

Map languages to formatters using built-in presets:

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

Available presets:

Language	Preset	Command	Type
R	`air`	`air format {}`	File-based
R	`styler`	`Rscript -e "styler::style_file('{}')"`	File-based
Python	`ruff`	`ruff format`	Stdin
Python	`black`	`black -`	Stdin
YAML	`yamlfmt`	`yamlfmt -`	Stdin
YAML	`prettier`	`prettier --parser=yaml`	Stdin
TOML	`taplo`	`taplo format -`	Stdin
Shell	`shfmt`	`shfmt -`	Stdin
C/C++	`clang-format`	`clang-format -`	Stdin

Sequential Formatting

Run multiple formatters in order by using an array:

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

Output from the first formatter is piped to the second.

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 definition 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 add arguments incrementally 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"].

Available modifiers:

prepend-args: Arguments added before base args
append-args: Arguments added after base args

Multiple modifiers example:

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

This produces final args: ["--verbose", "format", "{}", "-i", "2", "--check"].

With explicit args (no preset):

[formatters.shfmt]
cmd = "shfmt"
args = ["-filename", "$FILENAME"]
append-args = ["-i", "2", "-bn"]

Final args: ["-filename", "$FILENAME", "-i", "2", "-bn"].

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.

Behavior

Language matching: Code block language (e.g., ```python) is matched to formatter key (case-insensitive)
Parallel execution: All formatters run concurrently for speed
Sequential chains: Multiple formatters per language run in order
Error handling: Failed formatters preserve original code with a warning
Timeout: 30 seconds per formatter (not per chain)
Config files: Formatters respect their own config files (.prettierrc, pyproject.toml, etc.)

External Code Linters

panache can invoke external linters for code blocks. Linters are opt-in—you choose which languages to lint.

Quick Start

Enable linters for specific languages:

[linters]
r = "jarl"

Available linters:

Language	Linter	Command	Notes
R	`jarl`	`jarl`	R 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
Timeout: 30 seconds per linter invocation
Line-accurate: Diagnostics report exact line/column locations
Auto-fixes: Currently disabled due to byte offset mapping complexity (diagnostics work perfectly)

Example

Enable R linting with jarl while also formatting with air:

[linters]
r = "jarl"

[formatters]
r = "air"

Example Configuration

Complete example with all common options:

# Markdown flavor and basic settings
flavor = "quarto"
line-width = 80

# Formatting style (NEW: organized under [style] section)
[style]
wrap = "reflow"
blank-lines = "collapse"
math-delimiter-style = "preserve"
math-indent = 0

[style.code-blocks]
fence-style = "backtick"
attribute-style = "shortcut"

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

emoji = false

External formatters (opt-in)

[formatters]
python = ["isort", "black"] # Sequential: isort then black
r = "air"                   # Built-in preset
javascript = "prettier"     # Reusable definition
typescript = "prettier"
rust = "rustfmt"

Customize formatters (optional)

[formatters.prettier]
args = ["--print-width=100"]


[formatters.isort]
cmd = "isort"
args = ["-"]

# External linters (opt-in)
[linters]
r = "jarl" # Enable R linting