# Pandoc Flavor
For projects using [Pandoc](https://pandoc.org/) Markdown — academic
papers, books, and reports converted via Pandoc.
The Pandoc flavor is the foundation that the [Quarto](quarto.md) flavor
extends. Use Pandoc when you write Pandoc Markdown directly without using
the Quarto toolchain.
## Supported Patterns
### Fenced Divs
Pandoc fenced div syntax with attributes:
```markdown
::: {.note}
A note block.
:::
::: {#myid .class}
Generic div.
:::
```
**Affected rules**: MD031 (blanks around fences), MD022 (blanks around
headings), MD032 (blanks around lists)
### Pandoc Attribute Lists
Attribute syntax `{#id .class key="value"}` on headings, images, and code:
```markdown
# My Heading {#myid .my-class}
{.my-image width="50%"}
`code`{.python}
```
### Bracketed Spans
Spans of inline content with attributes:
```markdown
This is [some text]{.smallcaps} and [more]{.highlight}.
```
**Affected rules**: MD037 (no space in emphasis)
### Citations
Pandoc citation syntax:
```markdown
According to @smith2020, the results show...
Multiple citations [@smith2020; @jones2021] confirm this.
Suppress author: [-@smith2020] showed...
In-text: @smith2020 [p. 42] argues that...
```
**Affected rules**: MD042 (empty links), MD051 (link fragments),
MD052 (reference links)
### Inline Footnotes
```markdown
Here is a sentence^[with an inline footnote] and some more text.
```
**Affected rules**: MD042, MD052
### Implicit Header References
A bracketed phrase whose Pandoc slug matches an existing heading:
```markdown
# My Section
Refer to [My Section] for details.
```
**Affected rules**: MD042, MD051, MD052
#### Duplicate Heading Disambiguation
Pandoc's `auto_identifiers` extension assigns the second heading sharing the
same slug `<base>-1`, the third `<base>-2`, etc. MD051 resolves both forms:
```markdown
# A.
first
# A.
second
See [first](#a.) and [second](#a.-1).
```
### Example Lists
```markdown
(@) The first example.
(@good) The second example.
(@) The third example.
As shown in (@good), this approach works.
```
**Affected rules**: MD029 (ordered list prefix), MD042, MD052
### Definition Lists
```markdown
Term
: Definition.
Another term
: Another definition.
```
### Raw Format Blocks
````markdown
```{=html}
<div class="raw">Embedded HTML</div>
```
```{=latex}
\section{Raw LaTeX}
```
````
**Affected rules**: MD040 (fenced code language)
### Code Block Attributes
Pandoc fenced code blocks may declare their language via attribute syntax.
The first `.class` inside the attribute block is the language; additional
classes, ids, and key=value pairs are decoration.
````markdown
```{.python}
print("hi")
```
```{.haskell .numberLines}
main = putStrLn "hi"
```
```{#snippet .python startFrom="10"}
print(1)
```
````
A brace block with no `.class` (e.g. `{#myid}` or `{}`) declares no language
and is still flagged by MD040.
**Affected rules**: MD040 (fenced code language)
### Math
```markdown
Inline math $\alpha + \beta$ and display math:
$$
E = mc^2
$$
```
**Affected rules**: MD037, MD049, MD050
### Subscripts and Superscripts
```markdown
H~2~O and 2^10^.
```
**Affected rules**: MD037
### Inline Code Attributes
```markdown
Use `print()`{.python} to display.
```
The attribute block lives outside the code span, so MD038 still flags
genuine leading or trailing whitespace inside the backticks
(e.g. `` ` print()`{.python} ``).
### Pipe Tables with Captions
```markdown
| a | b |
: Caption for the table.
```
### Grid Tables
```markdown
+---------+---------+
| Cell | Cell |
+---------+---------+
```
**Affected rules**: MD055, MD056, MD058, MD060, MD075
### Multi-Line Tables
```markdown
-------------------------------------------------------------
Centered Default Right Left
Header Aligned Aligned Aligned
----------- ------- --------------- -------------------------
First row 12.0 Example of a row that
spans multiple lines.
Second row 5.0 Another row.
-------------------------------------------------------------
```
**Affected rules**: MD055, MD056, MD058, MD060, MD075
### Line Blocks
```markdown
| The Lord of the Rings
| by J.R.R. Tolkien
```
**Affected rules**: MD034 (no bare URLs), MD042, MD056
### Multi-Block YAML Metadata
Pandoc allows multiple YAML metadata blocks anywhere in a document:
```markdown
---
title: My Document
---
# Heading
---
author: Jane Doe
---
```
## Rule Behavior Changes
| MD022 | Blanks around headings | Treat `:::` div markers as transparent (don't require extra blanks) |
| MD029 | Validate ordered prefixes | Skip `(@)` / `(@label)` example markers |
| MD031 | Blanks around fences | Allow Pandoc fenced divs without extra blanks |
| MD032 | Blanks around lists | Treat `:::` div markers as transparent |
| MD034 | Flag all bare URLs | Skip URLs inside line blocks and metadata blocks |
| MD037 | Check emphasis spacing | Skip bracketed spans and sub/superscripts |
| MD040 | Standard language detection | Recognize `{=format}` raw-format and `{.class …}` code-attribute declarations |
| MD042 | Flag empty links | Skip citations, footnotes, example refs, implicit header refs |
| MD051 | Validate link fragments | Resolve fragments against Pandoc heading slugs |
| MD052 | Flag undefined references | Skip citations, footnotes, example refs, implicit header refs |
### Parser-Level Exclusions
Some Pandoc constructs are excluded by rumdl's parser for **all** flavors,
not by a Pandoc-specific guard. These rules therefore behave identically
under Pandoc and Standard:
- **Math blocks** (`$$...$$`, `$...$`): MD037, MD049, MD050 skip math
contexts universally.
- **Grid tables** (`+---+---+`), **multi-line tables**
(`---------- -------`), **line blocks** (`| line\n| line`), and
**pipe-table captions** (`: caption`): MD055, MD056, MD058, MD060,
MD075 iterate the table-block scanner, which only recognizes pipe
tables with `|`-bounded delimiter rows. The other table shapes never
enter the iteration source — under any flavor.
## Limitations
- Smart-typography linting (smart quotes, em-dashes, ellipses, emoji
shortcodes, `\` hard line breaks) is out of scope — these are rendering
features that do not trigger rumdl rules.
- `[TOC]` placeholder syntax is **not** Pandoc syntax (Pandoc generates
table-of-contents via the `--toc` flag) and is not recognized.
- Pandoc filter / Lua-filter / template execution is out of scope; rumdl
is a linter.
## Configuration
```toml
[global]
flavor = "pandoc"
```
Or per-file:
```toml
[per-file-flavor]
"papers/**/*.md" = "pandoc"
```
Pandoc files use `.md`, so there is no automatic file-extension
detection — opt in explicitly.
## When to Use
Use the Pandoc flavor when:
- You write Markdown that you process via the `pandoc` CLI.
- You use Pandoc citations, fenced divs, attribute lists, or other Pandoc
extensions.
- You write academic papers, books, or reports in Markdown.
If you use the Quarto toolchain, use the [Quarto flavor](quarto.md)
instead — it includes everything Pandoc does plus Quarto-specific syntax
(executable code blocks, shortcodes, `#|` cell options).
## See Also
- [Flavors Overview](../flavors.md) — compare all flavors
- [Quarto Flavor](quarto.md) — Pandoc + Quarto extensions
- [Pandoc Documentation](https://pandoc.org/MANUAL.html#pandocs-markdown)