Formatting
Format documents with Panache and see how it lays out Markdown, tables, math, and code.
Panache makes your Markdown source easier to read and keeps formatting consistent across your project. It preserves your document’s meaning. Once you’ve formatted a document, running Panache again produces the same output.
Using the Formatter
Format and Check Files
Format a document in place, or give Panache a directory to format the supported files inside it:
panache format document.qmd
panache format docs/To check formatting without writing changes:
panache format --check .When files need formatting, --check exits with a nonzero status. Whether you format or check, Panache follows your project’s configuration and respects its file exclusions. See Configuration.
To pipe a document through Panache, use --stdin-filename to give it a filename. Panache uses that name to choose the Markdown flavor, reads from standard input, and writes the formatted result to standard output:
panache --stdin-filename=document.qmd format <document.qmdSee Editor Setup to format documents as you edit and Integrations to use Panache with CI, pre-commit, and dprint.
Choose a Wrapping Mode
By default, Panache wraps paragraphs to a line width of 80 columns. Put your project’s preferences in panache.toml:
[format]
line-width = 80
wrap = "reflow"Choose a wrapping mode to suit how you write:
| Mode | Behavior |
|---|---|
reflow |
Rewrap paragraphs to fit line-width. |
preserve |
Keep existing line breaks. |
sentence |
Put each sentence on its own line. |
semantic |
Keep line breaks and add a break after each sentence. |
The sentence and semantic modes don’t limit line length. When finding sentence boundaries, Panache takes common abbreviations and your document’s language into account. See Sentence-Wrapping Abbreviations to customize which abbreviations it recognizes.
For a single run, you can override a setting on the command line:
panache format -o wrap=sentence document.qmdThe configuration reference lists all formatting options and their defaults.
Format Embedded Code
Panache formats code fences and their attributes. It adds a blank line between a code block and a following paragraph. To format the code inside them as well, configure an external formatter and make sure its command is available on your PATH. See Configure Linting and Embedded Code for setup and the formatter presets for supported tools.
In CommonMark and GFM, Panache preserves indentation inside HTML blocks, including a multiline tag’s closing > on its own line.
Ignore Directives
Use HTML comments to leave the formatting in part of your document untouched. This is useful for ASCII diagrams or other content whose spacing matters:
<!-- panache-ignore-format-start -->
This paragraph has custom spacing
that will be preserved exactly.
<!-- panache-ignore-format-end -->To turn off both formatting and linting for part of a document, use <!-- panache-ignore-start --> and <!-- panache-ignore-end --> instead.
Formatting Examples
These examples use Panache’s default settings for Quarto documents unless they specify another setting or Markdown flavor. Panache uses consistent markers, clear indentation, and spacing to make your document’s structure easy to see in the source. Some features, such as definition lists and fenced divs, require a flavor that supports them.
Text Wrapping
Panache wraps paragraphs to line-width. Here’s how a paragraph looks with line-width = 60:
- Input
-
Panache wraps paragraphs to make the source easier to read and keeps related words together. You can choose a different wrapping mode for your project. - Output
-
Panache wraps paragraphs to make the source easier to read and keeps related words together. You can choose a different wrapping mode for your project.
Panache preserves hard line breaks in every wrapping mode. It writes them as a backslash at the end of the line, which is easier to see than two trailing spaces.
Headings
Panache writes headings with #, ##, and so on (ATX headings). It removes decorative hashes at the end and adds blank lines around each heading. It also separates attributes with a single space. In Pandoc, Quarto, and R Markdown, it expands the {-} shorthand to the heading attribute {.unnumbered}.
- Input
-
Introduction ============ Text ## Results ## ### Details{.important .highlight } - Output
-
# Introduction Text ## Results ### Details {.important .highlight}
Emphasis and Strong
Panache uses asterisks for emphasis and strong emphasis:
- Input
-
An _important_ point and a __strong__ claim. - Output
-
An *important* point and a **strong** claim.
Panache may escape literal emphasis markers so they stay as text when the document is read as Markdown again.
Code
Panache uses enough backticks to enclose inline code, even when the code itself contains backticks. For code blocks, it uses backtick fences, puts the language first, and encloses any other attributes in braces. Indented code blocks become fenced blocks.
- Input
-
``` {.haskell .numberLines} qsort [] = [] ``` - Output
-
```haskell {.numberLines} qsort [] = [] ```
Tabs become spaces by default. To keep tabs in code, set tab-stops = "preserve".
Lists
Bullet lists use -, with two spaces of indentation for each nesting level. Panache removes blank lines between items when each item contains just one paragraph.
In CommonMark, you can put a list marker on a line of its own. Once that item contains a block of content, later blocks stay in the item if they have the indentation that item requires, even after a blank line.
In CommonMark and GitHub-Flavored Markdown (GFM), a nested ordered list can start at any number if it immediately follows a heading or horizontal rule. If it follows paragraph text, it must start at 1 or have a blank line before it. A nested list marker with no content stays part of the current paragraph.
CommonMark and GFM also allow an HTML block immediately after a list marker. When Panache adjusts the list’s indentation, it keeps the raw HTML and its relative indentation.
- Input
-
* Item 1 + Nested item * Deeply nested + Item 2 - Output
-
- Item 1 - Nested item - Deeply nested - Item 2
Panache keeps your numbering style in ordered and fancy lists and aligns continuation lines with the text after the list marker. Task lists use - [ ] and - [x] for both top-level and nested tasks. If your Markdown parser requires four spaces of indentation for each nesting level, enable the four-space-rule extension.
Definition Lists
Each definition starts with : followed by three spaces. When a definition contains several blocks, Panache separates them with blank lines and indents continuation blocks by four spaces.
Tables and HTML comments stay inside the definition they belong to, including in Hugo documents. Panache adjusts the indentation of HTML that continues a definition so that later blocks remain in the same definition.
- Input
-
Term : Definition - Output
-
Term : Definition
Block Quotes
Each line in a block quote starts with >, followed by a space. Paragraphs inside the quote follow the chosen wrapping mode.
Panache keeps the blank line between a list and a block quote that follows it. To put a quote inside a list item, indent its > markers to line up with the item’s text.
In CommonMark and GFM, a quote ends the list item if it’s indented less than the item’s text, even without a blank line. Inside a list item, Panache also keeps the blank line between a quote and a following paragraph so the paragraph stays outside the quote.
- Input
-
>This is a block quote. This >paragraph has two lines. - Output
-
> This is a block quote. This paragraph has two lines.
Tables
Panache formats pipe, grid, simple, and multiline tables. By default, it indents pipe, simple, and multiline tables by two spaces. Set table-indent = 0 to keep them at the left margin. Grid tables stay at the left margin so Pandoc recognizes them as tables.
For multiline tables, Panache finds cell boundaries using the column positions after tabs have been expanded. When inline code is joined onto a single line, Panache removes any continuation lines in the row that this leaves empty, even with wrap = "preserve".
Pipe Tables
Panache adds padding to show each column’s alignment in the source and removes excess padding. In Pandoc-based flavors, the number of dashes in the separator row can control the relative widths of the rendered columns. Panache keeps those dash counts when they affect the layout.
When Pandoc reads a table, it uses these proportions only if a source row is longer than its configured width (72 columns by default). Panache keeps enough padding to stay above that threshold.
- Input
-
| Right | Left | Default | Center| |------:|:-----|---------|:------:| | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 | - Output
-
| Right | Left | Default | Center | | ----: | :--- | ------- | :----: | | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 |
Grid Tables
Panache wraps prose within the existing columns. It keeps column widths because Pandoc uses them to determine the rendered layout. Lists, code, and other block content inside cells keep their structure.
- Input
-
+--------------------+--------+ | Description | Value | +====================+========+ | First | 12 | | sample. | | | | | +--------------------+--------+ - Output
-
+--------------------+--------+ | Description | Value | +====================+========+ | First sample. | 12 | +--------------------+--------+
Simple Tables
Panache sizes columns to fit their contents and aligns cell text according to the header. It moves captions below the table and prefixes them with :.
- Input
-
Right Left Center Default ------- ------ ---------- --------------- 12 12 12 12 123 123 123 123 1 1 1 1 : A caption - Output
-
Right Left Center Default ------- ------ -------- --------- 12 12 12 12 123 123 123 123 1 1 1 1 : A caption
Multiline Tables
Panache wraps prose within the existing column widths and removes extra blank lines between rows. It keeps the widths because they affect the rendered layout. Code spans, links, and math stay intact when cells wrap. Panache uses the original column positions to read the text in each cell before it adjusts punctuation or whitespace.
- Input
-
------------------------------------------------------------- Centered Default Right Left Header Aligned Aligned Aligned ----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. ------------------------------------------------------------- - Output
-
------------------------------------------------------------- Centered Default Right Left Header Aligned Aligned Aligned ----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. -------------------------------------------------------------
Math
Panache adds spaces around operators and keeps subscripts and superscripts next to the terms they apply to. In display math, it indents the contents of environments, aligns columns at & markers, and lines up row endings so the source is easier to follow.
- Input
-
$$ \begin{aligned} x _1&=a+b\\ x _{12}&=2a+b\\ y&=a-b \end{aligned} $$ - Output
-
$$ \begin{aligned} x_1 & = a + b \\ x_{12} & = 2a + b \\ y & = a - b \end{aligned} $$
By default, Panache wraps long display equations at relation signs and operators to fit line-width. Content after a multiline environment starts on a new line at the display’s indentation level. Subscripts, superscripts, and punctuation stay attached to the environment’s closing marker.
Use math = "preserve" to keep your line breaks, or math = "verbatim" to leave the math content untouched. Panache also leaves malformed math untouched, along with any command arguments it can’t interpret. See Math Formatting for modes, delimiter styles, and indentation settings.
Links
Panache keeps link text and destinations as they are. It normalizes spacing and quotation marks around titles and attributes.
- Input
-
[Panache](https://panache.bz/ 'Project website') - Output
-
[Panache](https://panache.bz/ "Project website")
Fenced Divs
Fenced divs group content between lines of colons. Panache normalizes their attributes and removes blank lines at the start and end of their content. A nested div uses two more colons than its parent, so you can tell their boundaries apart.
- Input
-
::: Warning :::::: This is a warning. ::: Danger This is a warning within a warning. ::: :::::::::::::::::: - Output
-
::: Warning This is a warning. ::::: Danger This is a warning within a warning. ::::: :::
MyST Directives
In the MyST flavor, Panache formats directive options and separates them from the body with a blank line. It formats Markdown content in directives it recognizes, such as admonitions and figures.
Panache leaves the bodies of unknown directives as you’ve written them. It also preserves literal content, such as code, math, and eval-rst blocks, and keeps each toctree entry on its own line. Literal content keeps its internal indentation, as well as any indentation from the directive’s opening fence, even inside lists and block quotes.
For fenced code within Markdown bodies, Panache preserves lines that contain only whitespace. If a code block has no closing fence, Panache keeps its content and indentation. It lengthens directive fences when needed to enclose formatted code blocks or nested directives, keeping the opening and closing fences the same length.
- Input
-
```{code-block} python :caption: Fibonacci def fib(n): if n < 2: return n return fib(n - 1) + fib(n - 2) ``` - Output
-
```{code-block} python :caption: Fibonacci def fib(n): if n < 2: return n return fib(n - 1) + fib(n - 2) ```
Admonitions
To format !!! admonitions, enable python-markdown-admonitions. For collapsible ??? and ???+ blocks, enable pymdownx-details. Panache indents the body by four spaces and formats it like ordinary content.
- Input
-
!!! note "Heads up" Read the introduction before running the examples. - Output
-
!!! note "Heads up" Read the introduction before running the examples.
Footnotes
Footnote text follows your chosen wrapping mode. Panache indents continuation blocks by four spaces, as in list items.
- Input
-
A claim.[^note] [^note]: Supporting evidence appears in the appendix. - Output
-
A claim.[^note] [^note]: Supporting evidence appears in the appendix.
Horizontal Rules
Horizontal rules use hyphens and extend to line-width, making section breaks visible in the source. With line-width = 40:
- Input
-
First section. *** Second section. - Output
-
First section. ---------------------------------------- Second section.
Set horizontal-rule-style = "compact" to use --- instead. Panache adds blank lines around rules to keep them distinct from heading underlines and metadata delimiters.
Blank Lines
Panache reduces multiple blank lines between blocks to one:
- Input
-
Paragraph 1 Paragraph 2 - Output
-
Paragraph 1 Paragraph 2
Frontmatter
Panache normalizes YAML spacing and indentation. It wraps prose in plain YAML values and folded text blocks (>) using your document’s wrapping mode. Literal text blocks (|) keep their line breaks.
- Input
-
--- echo: false list: - a - b --- Text - Output
-
--- echo: false list: - a - b --- Text
Chunk Options
In Quarto and R Markdown code chunks, Panache moves simple options from the header into #| comments and formats them as YAML. Options that contain R expressions stay in the header, even when the expressions contain spaces, as in eval = n > 1.
- Input
-
```{r foobar, echo=FALSE, dependson = c("foo", "bar"), fig.cap = "A caption"} a <- 1 b <- 2 ``` - Output
-
```{r, dependson=c("foo", "bar")} #| label: foobar #| echo: false #| fig-cap: "A caption" a <- 1 b <- 2 ```
Captions follow your document’s wrapping mode. Use a folded YAML text block (>-) for a long caption that should wrap across lines.
Jupyter Notebooks
Run panache format notebook.ipynb to format each Markdown cell independently. When you pass a directory, Panache finds notebooks automatically and skips .ipynb_checkpoints directories. Use --check to check formatting in CI, or --stdin-filename notebook.ipynb to pipe notebook JSON through standard input.
Panache supports notebook format version 4. It changes only the Markdown source values that need formatting and preserves the rest of the notebook JSON, including executable code cells, outputs, metadata, IDs, and attachments. Nonempty Markdown cells end with a newline. You can’t lint notebooks or select line ranges for notebook formatting from the command line.
The jupyter flavor uses GFM with JupyterLab math conventions. It recognizes $...$, $$...$$, bracket delimiters with doubled backslashes in the Markdown source, and TeX environments without surrounding math delimiters. Math can span several nonblank lines, even when those lines look like Markdown blocks. It can also continue onto later lines within a heading. A blank line ends the math region. Pipes inside math don’t split table cells.
Panache doesn’t treat a leading --- as YAML metadata in this flavor. It also keeps heading whitespace as you’ve written it so GFM-style anchor links stay valid. Use --flavor jupyter to apply these rules to standalone Markdown files.