panflute

Every element in panflute has attributes that allow you to navigate the document structure relative to the current element:

• .parent: The parent element.
• .next: The next sibling.
• .prev: The previous sibling.
• .ancestor(n): The n-th ancestor.
• .index: The index of the element among its siblings.
• .offset(n): The offset relative to the current element.

Panflute provides a Pythonic interface for interacting with Pandoc elements, making them significantly easier to manipulate than the raw JSON structures used by pandocfilters.

Key Advantages:

• Easy Modification: Access attributes directly. For example, use header.level += 1 to change a header level or header.identifier = 'spam' to change an identifier.
• Simple Creation: Construct elements using standard Python constructors. Example: Header(Str(The), Space, Str(Title), level=1, identifier=foo).
• Navigation: Traverse the document tree using attributes like elem.parent, elem.next, or by checking types with isinstance(elem.parent, Inline).

Action functions are the core of panflute filters. They are called with the signature action(element, doc). When writing these functions, follow these rules:

• Arguments: They must accept at least two arguments: element and doc. Additional arguments can be passed via **kwargs when using toJSONFilter or toJSONFilters.
• Return Values:
  • None: The element remains in the document as is (though it may have been modified in place).
  • Element: The returned element replaces the original element in the document.
  • [] (empty list): The element is deleted from the document. (Note: You can delete table rows or list items, but you cannot delete a table's caption; you can only make it empty).
  • List[Element]: If the input is a block or inline element, you can return a list of elements of the same base class to replace it.

To modify existing elements in a document (e.g., changing header levels), write a Python script that defines a function to handle specific element types and then calls panflute.run_filter().

import panflute as pf

def action(elem, doc):
    if isinstance(elem, pf.Header):
        elem.level = 1
    return elem

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

Using Conda is recommended if you want panflute and a matching version of Pandoc to be managed and installed together automatically. You can use conda or mamba (a faster drop-in replacement).

# Install both pandoc and panflute (version >= 2.0.5)
conda install -c conda-forge pandoc 'panflute>=2.0.5'

# Install pandoc, panflute, and extra dependencies (yamlloader)
conda install -c conda-forge pandoc 'panflute>=2.0.5' yamlloader

# Upgrade both
conda update pandoc panflute

# Remove both
conda remove pandoc panflute

To build the PDF version of the documentation, you must have miktex or a similar LaTeX distribution installed. The process is slower than building HTML.

On Windows, you can run the latex target via make.bat or manually run pdflatex on the generated .tex file.

cd docs && make.bat latex && cd build && cd latex && Makefile && cd

If you need the most recent development version directly from the GitHub repository instead of the PyPI release, use the following command:

pip install git+https://github.com/sergiocorreia/panflute.git

To rebuild the HTML documentation and update the hosted website, execute the following sequence of commands. This involves generating HTML via make.bat, building the Jekyll site, and pushing to S3.

Note: This assumes make.bat, jekyll, and s3_website are available in your environment.

cd docs && make.bat html && cd .. && cd ../website && jekyll build && s3_website push && cd ../panflute

To create a panflute filter, write a function that operates on Pandoc elements and call it using run_filter. The function should accept an element (elem) and the document (doc). If you want to modify an element, return the modified element (or a list of elements); to delete an element, return an empty list [].

from panflute import *

def increase_header_level(elem, doc):
    if type(elem) == Header:
        if elem.level < 6:
            elem.level += 1
        else:
            return [] # Delete headers already in level 6

def main(doc=None):
    return run_filter(increase_header_level, doc=doc)

if __name__ == "__main__":
    main()