Panflute

2.3.1 verified Mon Apr 27 auth: no python

Panflute is a Pythonic library for writing Pandoc filters. It provides an easy-to-use API to traverse and modify the Pandoc AST. Current version is 2.3.1, compatible with Python >=3.7 and Pandoc 3.1.x. Releases follow Pandoc API updates.

pip install panflute

Common errors

error ModuleNotFoundError: No module named 'panflute' ↓

cause Panflute not installed.

fix

Run pip install panflute

error pandoc: panflute: /usr/bin/env: 'python': No such file or directory ↓

cause Pandoc filter script shebang line missing or wrong Python path.

fix

Add shebang #!/usr/bin/env python3 and ensure the script is executable.

Warnings

breaking Null block element removed in version 2.3.0. Filters relying on Null must be updated. ↓

fix Replace references to pf.Null with appropriate handling (e.g., skip or convert to pf.Plain).

breaking Figure block element added in version 2.3.0. Pandoc 3.0+ required, older pandoc versions incompatible. ↓

fix Ensure pandoc version is 3.0+ when using panflute 2.3.0+.

deprecated The run_filter function is deprecated in favor of run_pandoc or direct usage of the returned document. ↓

fix Use pf.run_pandoc() with a filter function for better control.

gotcha Table caption handling: In Panflute 2.1.4+, Table() allows no caption. Older versions might crash with None caption. ↓

fix Update panflute or always provide a caption string.

Imports

run_filter
wrong
```
from panflute import run_filter
```
correct
```
import panflute as pf
```
run_filter is not a top-level function; use pf.run_filter or from panflute.tools import run_filter

Header

wrong

from panflute.elements import Header

correct

from panflute import Header

Header is available directly from panflute

Quickstart

Basic Pandoc filter to uppercase all headers. Run with pandoc: pandoc input.md --filter script.py -o output.md

import panflute as pf

def capitalize_headers(elem, doc):
    if isinstance(elem, pf.Header):
        return pf.Header(pf.stringify(elem).upper(), level=elem.level)

if __name__ == '__main__':
    pf.run_filter(capitalize_headers)