Formatting

Panache’s formatting rules are designed to produce clean, consistent Markdown output that adheres to common style guidelines while preserving the semantic meaning of the original document.

Text Wrapping

Paragraphs

Panache supports three modes of text wrapping for paragraphs, which are controlled via the configuration file:

[format]
wrap = "reflow" # or "preserve" or "sentence"

If wrap is set to reflow, panache will reformat paragraphs to fit within the number of columns specified by the line-width configuration option (default 80). If wrap is set to preserve, panache will keep existing line breaks and not reflow paragraphs. If wrap is set to sentence, panache will break lines at sentence boundaries, ensuring that each sentence starts on a new line.

Input
First sentence with a [link text](https://example.com) and inline math $a + b = c$. Second sentence; third sentence!
Output ("reflow")
First sentence with a [link text](https://example.com) and inline math
$a + b = c$. Second sentence; third sentence!
Output ("sentence")
First sentence with a [link text](https://example.com) and inline math $a + b = c$.
Second sentence; third sentence!

Preserving Hard Breaks

Hard line breaks, which are created either by ending a line with two or more spaces (`) or by using a backslash (\n`), are preserved regardless of the wrapping mode:

First line\
Second line (forced break)

Headings

ATX Headings

Headings are normalized with consistent spacing:

Input
#Heading 1
##  Heading 2
###   Heading 3

Output:

# Heading 1

## Heading 2

### Heading 3

Heading Attributes

Attributes are preserved and formatted:

## Heading {#custom-id .my-class key="value"}

Setext Headings

Setext-style headings are converted to ATX style for consistency:

Input
Heading 1
=========

Heading 2
---------
Output
# Heading 1

## Heading 2

Emphasis and Strong

Basic Formatting

Emphasis markers are normalized:

Input:

*italic* _also italic_
**bold** __also bold__
***bold italic***

Output:

*italic* *also italic*
**bold** **also bold**
***bold italic***

Nested Emphasis

Nested emphasis is handled correctly:

**bold with *nested italic* inside**
*italic with **nested bold** inside*

Code

Inline Code

Inline code is preserved with minimal backticks needed:

Use `code` for inline code.
Use ``code with ` backtick`` for code containing backticks.

Tab Stops in Code

Tabs in regular text are always normalized to spaces. To preserve tabs in literal code spans and code blocks, set:

[format]
tab-stops = "preserve"
tab-width = 4

Code Blocks

Fenced code blocks are formatted consistently:

Input:

```python
def hello():
    print("Hello")
```

Output:

```python
def hello():
    print("Hello")
```

Lists

Unordered Lists

Bullet list markers are standardized to - for consistency. All bullet markers (*, +, -) are converted to - at all nesting levels:

Input:

* Item 1
  + Nested item
    * Deeply nested
+ Item 2

Output:

- Item 1
  - Nested item
    - Deeply nested
- Item 2
Note

panache standardizes all bullet list markers to - (hyphen) for consistency, regardless of the original marker used. This applies to all nesting levels and task lists as well.

Ordered Lists

Ordered lists maintain proper numbering:

1. First item
2. Second item
   1. Nested item
   2. Another nested
3. Third item

Task Lists

GitHub-style task lists use the standardized - marker:

Input:

* [ ] Unchecked task
+ [x] Checked task
- [ ] Another task

Output:

- [ ] Unchecked task
- [x] Checked task
- [ ] Another task

Definition Lists

Definition lists preserve loose vs compact spacing:

Term 1

: Definition 1

Term 2
: Definition 2a
: Definition 2b

Term 3
: Definition 3

Blockquotes

Blockquotes are formatted with consistent > markers:

Input:

This is a blockquote
that spans multiple lines

Output:

This is a blockquote that spans multiple lines

Nested Blockquotes

Outer quote

Nested quote

Tables

Panache supports all Pandoc table types and normalizes alignment and spacing while preserving content and attributes.

Pipe Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Grid Tables

+----------+----------+----------+
| Header 1 | Header 2 | Header 3 |
+==========+==========+==========+
| Cell 1   | Cell 2   | Cell 3   |
+----------+----------+----------+
| Cell 4   | Cell 5   | Cell 6   |
+----------+----------+----------+

Simple Tables

  Header 1   Header 2   Header 3
  ---------- ---------- ----------
  Cell 1     Cell 2     Cell 3
  Cell 4     Cell 5     Cell 6

Math

Inline Math

Inline math is untouched:

The equation $E = mc^2$ is famous.

Display Math

Display math is formatted on its own lines with leading indentation depending on the math-indent configuration option (default 0):

Input
$$E = mc^2$$
Output
$$
E = mc^2
$$

Images

Inline Images

![Alt text](image.png)
![Alt with title](image.png "Title")

Images with Attributes

![Caption](image.png){#fig-id width=50%}

Fenced Divs

Quarto/Pandoc fenced divs are formatted correctly:

::: {.callout-note}
This is a note callout.
:::

::: {#custom-id .my-class}
Content with custom attributes.
:::

Nested Divs

::: {.outer}
Outer content

::: {.inner}
Inner content
:::

More outer content
:::

Footnotes

Inline Footnotes

Text with footnote^[This is the footnote content].

Reference Footnotes

Text with reference footnote[^1].

[^1]: This is the footnote content.

Citations

Pandoc citation syntax is preserved:

See @smith2020 for more details.
Multiple citations [@smith2020; @jones2021].
Citation with prefix [see @smith2020, pp. 10-15].

Raw Blocks

HTML

```{=html}
<div class="custom">
  <p>Raw HTML content</p>
</div>
```

LaTeX

```{=latex}
\begin{equation}
E = mc^2
\end{equation}
```

Horizontal Rules

Horizontal rules are normalized:

Input:

---
***
___

Output:

---

---

---

Blank Lines

Collapsing

By default, multiple blank lines are collapsed to one:

Input:

Paragraph 1


Paragraph 2

Output:

Paragraph 1

Paragraph 2

Preserving Blank Lines

Configure to preserve blank lines:

[format]
blank-lines = "preserve"
collapse
Collapse multiple blank lines into one (default)
preserve
Keep all existing blank lines

Frontmatter

YAML

YAML frontmatter is parsed and normalized by Panache’s built-in YAML formatter:

---
title: "My Document"
author: "Author Name"
date: "2026-02-11"
---

By default this means spacing and list indentation are normalized in the frontmatter block. This frontmatter formatting is always handled internally by Panache. The YAML parser/formatter implementation is shipped in Panache-owned workspace crates.

Pandoc Title Block

Pandoc-style title blocks are also supported:

% My Document Title
% Author Name
% 2026-02-11

Document content starts here.

Best Practices

Use consistent line width
Set line-width based on your editor width
Enable external formatters
Let language-specific tools format code blocks
Choose appropriate flavor
Match your document type (quarto, rmarkdown, etc.)
Test incrementally
Format small sections first to understand behavior
Use version control
Always commit before formatting large documents

Ignore Directives

You can selectively disable formatting for specific regions using HTML comment directives:

Ignore Formatting Only

Use panache-ignore-format-start and panache-ignore-format-end to preserve specific formatting:

Normal paragraph will be wrapped and formatted.

<!-- panache-ignore-format-start -->
This    paragraph   has    custom     spacing
that  will   be   preserved   exactly.
<!-- panache-ignore-format-end -->

Back to normal formatting.

This is useful for:

  • ASCII art or diagrams
  • Tables with specific spacing
  • Pre-formatted text blocks
  • Code examples that aren’t in code blocks

Ignore Both Formatting and Linting

Use panache-ignore-start and panache-ignore-end to disable both formatting and linting:

<!-- panache-ignore-start -->
#### Heading with unusual spacing
Custom    formatting   and   linting   rules   ignored
<!-- panache-ignore-end -->

Nested Structures

Ignore directives work inside lists, blockquotes, and other nested structures:

- List item 1
- List item 2
  <!-- panache-ignore-format-start -->
  Nested    content   with    custom   spacing
  <!-- panache-ignore-format-end -->
- List item 3

See Linting for information about linting-specific ignore directives.

See Also