pandoc-pyplot: A Pandoc filter to include figures generated from Python code blocks

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]


A Pandoc filter to include figures generated from Python code blocks. Keep the document and Python code in the same location. Output from Matplotlib is captured and included as a figure.

[Skip to Readme]


Change log
Dependencies base (>=4 && <5), containers, data-default-class (>=0.1.2), deepseq, directory, filepath (>=1.4 && <2), hashable (>=1 && <2), open-browser (>=, pandoc (>=2 && <3), pandoc-pyplot, pandoc-types (>1.12 && <2), template-haskell (>2.7 && <3), temporary, text (>=1 && <2), typed-process (>=0.2.1 && <1), yaml (>=0.8.16) [details]
License MIT
Author Laurent P. René de Cotret
Maintainer Laurent P. René de Cotret
Category Documentation
Home page
Bug tracker
Source repo head: git clone
Uploaded by LaurentRDC at 2019-05-29T19:37:57Z


[Index] [Quick Jump]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for pandoc-pyplot-

[back to package description]

pandoc-pyplot - A Pandoc filter to generate Matplotlib figures directly in documents

Hackage version Stackage version (LTS) Stackage version (nightly) Build status GitHub

pandoc-pyplot turns Python code present in your documents into embedded Matplotlib figures.


The filter recognizes code blocks with the .pyplot class present. It will run the script in the associated code block in a Python interpreter and capture the generated Matplotlib figure.

Here is a basic example using the scripting matplotlib.pyplot API:

    import matplotlib.pyplot as plt

    plt.plot([0,1,2,3,4], [1,2,3,4,5])
    plt.title('This is an example figure')

Putting the above in, we can then generate the plot and embed it:

pandoc --filter pandoc-pyplot --output output.html


pandoc --filter pandoc-pyplot --output output.pdf

or any other output format you want.

There are more examples in the source repository, in the \examples directory.


No wasted work

pandoc-pyplot minimizes work, only generating figures if it absolutely must. Therefore, you can confidently run the filter on very large documents containing dozens of figures --- like a book or a thesis --- and only the figures which have recently changed will be re-generated.

In case of an output format that supports links (e.g. HTML), the embedded image generated by pandoc-pyplot will be a link to the source code which was used to generate the file. Therefore, other people can see what Python code was used to create your figures. A high resolution image will be made available in a caption link.


You can also specify a caption for your image. This is done using the optional caption parameter:

    ```{.pyplot caption="This is a simple figure"}
    import matplotlib.pyplot as plt

    plt.plot([0,1,2,3,4], [1,2,3,4,5])
    plt.title('This is an example figure')

Caption formatting is either plain text or Markdown. LaTeX-style math is also support in captions (using dollar signs \(...\)).

Including scripts

If you find yourself always repeating some steps, inclusion of scripts is possible using the include parameter. For example, if you want all plots to have the ggplot style, you can write a very short preamble like so:

import matplotlib.pyplot as plt'ggplot')

and include it in your document as follows:

    plt.plot([0,1,2,3,4], [1,2,3,4,5])
    plt.title('This is an example figure')

Which is equivalent to writing the following markdown:

    import matplotlib.pyplot as plt'ggplot')

    plt.plot([0,1,2,3,4], [1,2,3,4,5])
    plt.title('This is an example figure')

This include parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script! You can also import packages this way, or define functions you often use.

Compatibility with pandoc-crossref

pandoc-crossref is a pandoc filter that makes it effortless to cross-reference objects on documents.

You can use pandoc-crossref in conjunction with pandoc-pyplot for the ultimate figure-making pipeline. You can combine both in a figure like so:

    ```{#fig:myexample .pyplot caption="This is a caption"}
    # Insert figure script here

    As you can see in @fig:myexample, ...

If the above source is located in file, you can render the figure and references by applying pandoc-pyplot first, and then pandoc-crossref. For example:

pandoc --filter pandoc-pyplot --filter pandoc-crossref -i -o myfile.html


New in version

To avoid repetition, pandoc-pyplot can be configured using simple YAML syntax. pandoc-pyplot will look for a .pandoc-pyplot.yml file in the current working directory:

# You can specify any or all of the following parameters
interpreter: python36
directory: mydirectory/
format: jpeg
dpi: 150
flags: [-O, -Wignore]

These values override the default values, which are equivalent to:

# Defaults if no configuration is provided.
# Note that the default interpreter name on MacOS and Unix is python3
interpreter: python
flags: []
directory: generated/
format: png
dpi: 80



Windows binaries are available on GitHub. Place the executable in a location that is in your PATH to be able to call it.


Windows installers are made available thanks to Inno Setup. You can download them from the release page.

From Hackage/Stackage

pandoc-pyplot is available on Hackage. Using the cabal-install tool:

cabal update
cabal install pandoc-pyplot

Similarly, pandoc-pyplot is available on Stackage:

stack update
stack install pandoc-pyplot

From source

Building from source can be done using stack or cabal:

git clone
cd pandoc-pylot
stack install # Alternatively, `cabal install`

Running the filter


This filter only works with the Matplotlib plotting library. Therefore, you a Python interpreter and at least Matplotlib installed. The name of the Python interpreter to use can be specified in a .pandoc-pyplot.yml file; by default, pandoc-pyplot will use the "python" name on Windows, and "python3" otherwise.

You can use the filter with Pandoc as follows:

pandoc --filter pandoc-pyplot --output output.html

In which case, the output is HTML. Another example with PDF output:

pandoc --filter pandoc-pyplot --output output.pdf

Python exceptions will be printed to screen in case of a problem.

pandoc-pyplot has a limited command-line interface. Take a look at the help available using the -h or --help argument:

pandoc-pyplot --help

Usage as a Haskell library

To include the functionality of pandoc-pyplot in a Haskell package, you can use the makePlot :: Block -> IO Block function (for single blocks) or plotTransform :: Pandoc -> IO Pandoc function (for entire documents).

Usage with Hakyll

This filter was originally designed to be used with Hakyll. In case you want to use the filter with your own Hakyll setup, you can use a transform function that works on entire documents:

import Text.Pandoc.Filter.Pyplot (plotTransform)

import Hakyll

-- Unsafe compiler is required because of the interaction
-- in IO (i.e. running an external Python script).
makePlotPandocCompiler :: Compiler (Item String)
makePlotPandocCompiler =
    (unsafeCompiler . plotTransform)

The plotTransformWithConfig is also available for a more configurable set-up.


Do not run this filter on unknown documents. There is nothing in pandoc-pyplot that can stop a Python script from performing evil actions.