pandocfilters

pandocfilters is a small Python module for writing Pandoc filters — programs that read a JSON serialization of the Pandoc abstract syntax tree (AST) from stdin, transform it, and write it back to stdout. Filters let you customize how Pandoc converts documents between formats such as Markdown, LaTeX, HTML, and DOCX.

The module provides helper functions to walk and rewrite the AST, construct new document elements, and wire everything into Pandoc’s —filter pipeline, so you can implement custom behavior without patching Pandoc itself.

What You Get

• Helper functions to walk and transform the Pandoc document AST from Python
• Constructors for building AST elements such as headers, links, and code blocks
• A collection of example filters demonstrating common transformations

Common Use Cases

• Rewriting or annotating elements during a Markdown-to-HTML or LaTeX conversion
• Extracting or transforming code blocks, images, or links across a document
• Implementing custom directives and shortcodes for a documentation toolchain

Under The Hood

Architecture

pandocfilters is a single module, pandocfilters.py, exposing a functional API: walk(x, action, format, meta) recursively traverses the parsed JSON tree, toJSONFilter reads stdin, applies your action, and writes stdout per Pandoc’s filter contract, and element constructors emit the tagged {t, c} node dictionaries Pandoc expects.

Tech Stack

Pure Python with no third-party runtime dependencies, relying only on the standard library’s json module. It is packaged with a classic setup.py/setup.cfg and ships an examples directory rather than a compiled component.

Code Quality

The implementation is deliberately tiny and dependency-free, prioritizing portability and stability over feature breadth. It ships example filters instead of a formal unit-test suite, and its long track record across the Pandoc ecosystem is its main correctness signal.

API Design

The API is a small, functional surface — a few functions and element constructors — that mirrors Pandoc’s own AST shape, so anyone familiar with Pandoc can write a filter in a dozen lines. The README and examples get newcomers productive quickly, though writing filters still requires understanding the AST schema.