Skip to main content

pandocfilters

A python module for writing pandoc filters

What are pandoc filters?

Pandoc filters are pipes that read a JSON serialization of the Pandoc AST from stdin, transform it in some way, and write it to stdout. They can be used with pandoc (>= 1.12) either using pipes

pandoc -t json -s | ./caps.py | pandoc -f json

or using the --filter (or -F) command-line option.

pandoc --filter ./caps.py -s

For more on pandoc filters, see the pandoc documentation under --filter and the tutorial on writing filters.

Compatibility

Pandoc 1.16 introduced link and image attributes to the existing caption and target arguments, requiring a change in pandocfilters that breaks backwards compatibility. Consequently, you should use:

  • pandocfilters version <= 1.2.4 for pandoc versions 1.12–1.15, and

  • pandocfilters version >= 1.3.0 for pandoc versions >= 1.16.

Installing

Run this inside the present directory:

python setup.py install

Or install from PyPI:

pip install pandocfilters

Available functions

The pandocfilters module exports the following functions:

walk(x, action, format, meta)

Walk a tree, applying an action to every object. Returns a modified tree.

toJSONFilter(action)

Converts an action into a filter that reads a JSON-formatted pandoc document from stdin, transforms it by walking the tree with the action, and returns a new JSON-formatted pandoc document to stdout. The argument is a function action(key, value, format, meta), where key is the type of the pandoc object (e.g. 'Str', 'Para'), value is the contents of the object (e.g. a string for 'Str', a list of inline elements for 'Para'), format is the target output format (which will be taken for the first command line argument if present), and meta is the document’s metadata. If the function returns None, the object to which it applies will remain unchanged. If it returns an object, the object will be replaced. If it returns a list, the list will be spliced in to the list to which the target object belongs. (So, returning an empty list deletes the object.)

stringify(x)

Walks the tree x and returns concatenated string content, leaving out all formatting.

attributes(attrs)

Returns an attribute list, constructed from the dictionary attrs.

How to use

Most users will only need toJSONFilter. Here is a simple example of its use:

#!/usr/bin/env python

"""
Pandoc filter to convert all regular text to uppercase.
Code, link URLs, etc. are not affected.
"""

from pandocfilters import toJSONFilter, Str

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

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

Examples

The examples subdirectory in the source repository contains the following filters. These filters should provide a useful starting point for developing your own pandocfilters.

abc.py

Pandoc filter to process code blocks with class abc containing ABC notation into images. Assumes that abcm2ps and ImageMagick’s convert are in the path. Images are put in the abc-images directory.

caps.py

Pandoc filter to convert all regular text to uppercase. Code, link URLs, etc. are not affected.

comments.py

Pandoc filter that causes everything between <!-- BEGIN COMMENT --> and <!-- END COMMENT --> to be ignored. The comment lines must appear on lines by themselves, with blank lines surrounding

deemph.py

Pandoc filter that causes emphasized text to be displayed in ALL CAPS.

deflists.py

Pandoc filter to convert definition lists to bullet lists with the defined terms in strong emphasis (for compatibility with standard markdown).

gabc.py

Pandoc filter to convert code blocks with class “gabc” to LaTeX \gabcsnippet commands in LaTeX output, and to images in HTML output.

graphviz.py

Pandoc filter to process code blocks with class graphviz into graphviz-generated images.

lilypond.py

Pandoc filter to process code blocks with class “ly” containing Lilypond notation.

metavars.py

Pandoc filter to allow interpolation of metadata fields into a document. %{fields} will be replaced by the field’s value, assuming it is of the type MetaInlines or MetaString.

myemph.py

Pandoc filter that causes emphasis to be rendered using the custom macro \myemph{...} rather than \emph{...} in latex. Other output formats are unaffected.

theorem.py

Pandoc filter to convert divs with class="theorem" to LaTeX theorem environments in LaTeX output, and to numbered theorems in HTML output.

tikz.py

Pandoc filter to process raw latex tikz environments into images. Assumes that pdflatex is in the path, and that the standalone package is available. Also assumes that ImageMagick’s convert is in the path. Images are put in the tikz-images directory.

Metadata

Release files for pandocfilters 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pandocfilters 1.3.0
File Size Uploaded Provenance Actions
pandocfilters-1.3.0.tar.gz 10.1 kB Without provenance Details for pandocfilters-1.3.0.tar.gz

Release files / pandocfilters-1.3.0.tar.gz

Download URL pandocfilters-1.3.0.tar.gz
Size 10.1 kB
Tags Source
SHA-256 checksum
How to use checksums
557d979cef8d282f5e9cda237f773b642ff2925824288e91c3339457165dda3f
BLAKE2b-256 checksum
How to use checksums
88eead5ac7a557fd4888865d71e46958902e50f9916e28e6278f35237b7550f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for pandocfilters 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page