Formatting

Panache follows these principles:

  1. Preserve semantic meaning: Never change what your document means
  2. Consistent style: Apply uniform formatting rules throughout
  3. Readability first: Optimize for human readers, not machines
  4. Pandoc compatibility: Respect Pandoc’s parsing rules and extensions

Text Wrapping

Paragraphs

Panache wraps paragraphs to fit within the configured line width (default 80 characters):

Input:

This is a very long paragraph that exceeds the line width and needs to be wrapped across multiple lines for better readability.

Output:

This is a very long paragraph that exceeds the line width and needs to be
wrapped across multiple lines for better readability.

Preserving Hard Breaks

Hard line breaks are preserved:

First line\
Second line (forced break)

Wrapping Mode

Configure wrapping behavior:

[style]
wrap = "reflow"
reflow
Reformat paragraphs to fit within configured line width (default)
preserve
Keep existing line breaks

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

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:

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

External Formatters

When configured, code blocks are formatted by external tools:

[formatters]
python = "black"

Python code in code blocks is automatically formatted by Black.

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.

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 formatted with proper spacing:

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

Display Math

Display math is formatted on its own lines:

Input:

$$E = mc^2$$

Output:

$$
E = mc^2
$$

Complex Math

panache preserves math formatting:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{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:

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

Frontmatter

YAML

YAML frontmatter is preserved:

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

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.

Formatting Preservation

panache preserves:

  • Semantic meaning of all elements

  • Math expressions exactly as written

  • Code block content (unless external formatter configured)

  • Link URLs and reference definitions

  • Attribute syntax and values

  • Raw HTML/LaTeX blocks

  • Content within ignore directive regions

See Also