Skip to content

pandoc.md

Latest commit

 

History

History
333 lines (230 loc) · 7.79 KB

pandoc.md

File metadata and controls

333 lines (230 loc) · 7.79 KB

Pandoc Flavor

For projects using Pandoc Markdown — academic papers, books, and reports converted via Pandoc.

The Pandoc flavor is the foundation that the Quarto 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:

::: {.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:

# My Heading {#myid .my-class}

![Image](path.png){.my-image width="50%"}

`code`{.python}

Bracketed Spans

Spans of inline content with attributes:

This is [some text]{.smallcaps} and [more]{.highlight}.

Affected rules: MD037 (no space in emphasis)

Citations

Pandoc citation syntax:

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

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:

# 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:

# A.

first

# A.

second

See [first](#a.) and [second](#a.-1).

Example Lists

(@) 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

Term
:   Definition.

Another term
:   Another definition.

Raw Format Blocks

```{=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.

```{.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

Inline math $\alpha + \beta$ and display math:

$$
E = mc^2
$$

Affected rules: MD037, MD049, MD050

Subscripts and Superscripts

H~2~O and 2^10^.

Affected rules: MD037

Inline Code Attributes

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

| col1 | col2 |
|------|------|
| a    | b    |

: Caption for the table.

Grid Tables

+---------+---------+
| Header  | Header  |
+=========+=========+
| Cell    | Cell    |
+---------+---------+

Affected rules: MD055, MD056, MD058, MD060, MD075

Multi-Line Tables

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

| 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:

---
title: My Document
---

# Heading

---
author: Jane Doe
---

Rule Behavior Changes

Rule Standard Behavior Pandoc Behavior
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

[global]
flavor = "pandoc"

Or per-file:

[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 instead — it includes everything Pandoc does plus Quarto-specific syntax (executable code blocks, shortcodes, #| cell options).

See Also
⚡