pandocfilters

1.5.1 · active · verified Sat Mar 28

pandocfilters is a Python library that provides utilities for writing Pandoc filters. These filters manipulate Pandoc's Abstract Syntax Tree (AST) in its JSON representation between the reader (parser) and writer (output format). It is currently at version 1.5.1 and sees an active, though irregular, release cadence focused on maintenance and compatibility with Pandoc versions.

Warnings

breaking Python 2 support was officially dropped after `pandocfilters` version 1.5.0. If you are on Python 2, you must use `pandocfilters` <= 1.5.0.
Fix: Upgrade to Python 3 or pin `pandocfilters` to version 1.5.0 or earlier.
breaking Compatibility with the underlying `pandoc` executable is critical and can break filters due to AST changes. Specific `pandocfilters` versions are tied to `pandoc` versions.
Fix: Use `pandocfilters` <= 1.2.4 for `pandoc` versions 1.12-1.15. Use `pandocfilters` >= 1.3.0 for `pandoc` versions >= 1.16. `pandocfilters` 1.4.0 introduced compatibility with `pandoc` 1.17.3's new JSON format. Always check the `pandocfilters` README for the latest compatibility matrix.
gotcha The `get_filename4code` utility (used for generating filenames for code blocks, e.g., for images) by default creates temporary directories that are NOT automatically cleaned up. This can lead to an accumulation of files if not managed.
Fix: Set the environment variable `PANDOCFILTER_CLEANUP` to any non-empty value (e.g., '1') before running your filter. This will cause temporary directories to be created in a temporary location and automatically removed upon filter exit.
gotcha Starting from version 1.5.0, the `examples/` directory is no longer included in the PyPI distribution (source or binary wheels). It is only available in the source repository on GitHub.
Fix: If you rely on the examples, clone the GitHub repository (`http://github.com/jgm/pandocfilters`) directly instead of installing from PyPI, or browse the examples on GitHub.
gotcha Pandoc itself offers built-in Lua filters (since Pandoc 2.0) which do not require external language interpreters (like Python) and may offer better performance for some use cases. An alternative Python library, `panflute`, also exists, offering a more 'Pythonic' API.
Fix: Consider if a Lua filter (using Pandoc's `--lua-filter` option) or `panflute` might be a better fit for your specific filtering needs, especially for new projects.

Install

pip install pandocfilters Install with pip

Imports

toJSONFilter
```
from pandocfilters import toJSONFilter
```
This is the primary function for creating a standalone filter script that reads from stdin and writes to stdout.
walk
```
from pandocfilters import walk
```
Used for applying an action function to every object in a parsed Pandoc AST.
Str, Para, Header, Emph
```
from pandocfilters import Str, Para, Header, Emph
```
Common AST element constructors for manipulating the document structure.

Quickstart

This quickstart demonstrates a simple Pandoc filter that converts all regular string elements ('Str') in the document's Abstract Syntax Tree (AST) to uppercase. Save this code as a Python file (e.g., `caps_filter.py`), make it executable, and then run Pandoc with the `--filter` option pointing to your script.

#!/usr/bin/env python
"""
Pandoc filter to convert all regular text ('Str' elements) to uppercase.
Run with: pandoc input.md --filter ./caps_filter.py -o output.html
"""

from pandocfilters import toJSONFilter, Str

def caps(key, value, format, meta):
    if key == 'Str':
        return Str(value.upper())

if __name__ == "__main__":
    toJSONFilter(caps)

view raw JSON →