Package: pandocfilters
A python module for writingpandocfiltersWhat 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 pipespandoc -t json -s | ./caps.py | pandoc -f jsonor using the--filter(or-F) command-line option.pandoc --filter ./caps.py -sFor more on pandoc filters, see the pandoc documentation under--filterandthe tutorial on writing filters.For an alternative library for writing pandoc filters, with
a more “Pythonic” design, seepanflute.CompatibilityPandoc 1.16 introduced link and imageattributesto the existingcaptionandtargetarguments, 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, andpandocfilters version >= 1.3.0 for pandoc versions >= 1.16.Pandoc 1.17.3 (pandoc-types 1.17.*) introduced a new JSON format.
pandocfilters 1.4.0 should work with both the old and the new
format.InstallingRun this inside the present directory:python setup.py installOr install from PyPI:pip install pandocfiltersAvailable functionsThe main functionspandocfiltersexports arewalk(x, action, format, meta)Walk a tree, applying an action to every object. Returns a modified
tree. An action is a function of the formaction(key, value, format, meta), where:keyis the type of the pandoc object (e.g. ‘Str’, ‘Para’)valueis the contents of the object (e.g. a string for ‘Str’, a list of
inline elements for ‘Para’)formatis the target output format (as supplied by theformatargument ofwalk)metais the document’s metadataThe return of an action is either:None: this means that the object should remain unchangeda pandoc object: this will replace the original objecta list of pandoc objects: these will replace the original object;
the list is merged with the neighbors of the original objects
(spliced into the list the original object belongs to); returning
an empty list deletes the objecttoJSONFilter(action)LiketoJSONFilters, but takes a single action as argument.toJSONFilters(actions)Generate a JSON-to-JSON filter from stdin to stdoutThe filter:reads a JSON-formatted pandoc document from stdintransforms it by walking the tree and performing the actionsreturns a new JSON-formatted pandoc document to stdoutThe argumentactionsis a list of functions of the formaction(key, value, format, meta), as described in more detail
underwalk.This function callsapplyJSONFilters, with theformatargument provided by the first command-line argument, if present.
(Pandoc sets this by default when calling filters.)applyJSONFilters(actions, source,format="")Walk through JSON structure and apply filtersThis:reads a JSON-formatted pandoc document from a source stringtransforms it by walking the tree and performing the actionsreturns a new JSON-formatted pandoc document as a stringTheactionsargument is a list of functions (seewalkfor a
full description).The argumentsourceis a string encoded JSON object.The argumentformatis a string describing the output format.Returns a new JSON-formatted pandoc document.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 useMost users will only needtoJSONFilter.  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)ExamplesThe examples subdirectory in the source repository contains the
following filters. These filters should provide a useful starting point
for developing your own pandocfilters.abc.pyPandoc filter to process code blocks with classabccontaining ABC
notation into images. Assumes that abcm2ps and ImageMagick’s convert
are in the path. Images are put in the abc-images directory.caps.pyPandoc filter to convert all regular text to uppercase. Code, link
URLs, etc. are not affected.blockdiag.pyPandoc filter to process code blocks with class “blockdiag” into
generated images. Needs utils fromhttp://blockdiag.com.comments.pyPandoc 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 surroundingdeemph.pyPandoc filter that causes emphasized text to be displayed in ALL
CAPS.deflists.pyPandoc filter to convert definition lists to bullet lists with the
defined terms in strong emphasis (for compatibility with standard
markdown).gabc.pyPandoc filter to convert code blocks with class “gabc” to LaTeX
\gabcsnippet commands in LaTeX output, and to images in HTML output.graphviz.pyPandoc filter to process code blocks with classgraphvizinto
graphviz-generated images.lilypond.pyPandoc filter to process code blocks with class “ly” containing
Lilypond notation.metavars.pyPandoc filter to allow interpolation of metadata fields into a
document.%{fields}will be replaced by the field’s value, assuming
it is of the typeMetaInlinesorMetaString.myemph.pyPandoc filter that causes emphasis to be rendered using the custom
macro\myemph{...}rather than\emph{...}in latex. Other output
formats are unaffected.plantuml.pyPandoc filter to process code blocks with classplantumlto images.
Needsplantuml.jarfromhttp://plantuml.com/.ditaa.pyPandoc filter to process code blocks with classditaato images.
Needsditaa.jarfromhttp://ditaa.sourceforge.net/.theorem.pyPandoc filter to convert divs withclass="theorem"to LaTeX theorem
environments in LaTeX output, and to numbered theorems in HTML
output.tikz.pyPandoc 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 thetikz-imagesdirectory.API documentationBy default most filters useget_filename4codeto
create a directory...-imagesto save temporary
files. This directory doesn’t get removed as it can be used as a cache so that
later pandoc runs don’t have to recreate files if they already exist. The
directory is generated in the current directory.If you prefer to have a clean directory after running pandoc filters, you
can set an environment variablePANDOCFILTER_CLEANUPto any non-empty value such as1which forces the code to create a temporary directory that will be removed
by the end of execution.