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

Copyright(c) Laurent P René de Cotret 2019
Safe HaskellNone




This module defines a Pandoc filter makePlot that can be used to walk over a Pandoc document and generate figures from Python code blocks.

The syntax for code blocks is simple, Code blocks with the .pyplot attribute will trigger the filter. The code block will be reworked into a Python script and the output figure will be captured, along with a high-resolution version of the figure and the source code used to generate the figure.

To trigger pandoc-pyplot, the following is required:

  • .pyplot: Trigger pandoc-pyplot but let it decide on a filename

Here are the possible attributes what pandoc-pyplot understands:

  • directory=... : Directory where to save the figure.
  • format=...: Format of the generated figure. This can be an extension or an acronym, e.g. format=png.
  • caption="...": Specify a plot caption (or alternate text). Captions support Markdown formatting and LaTeX math ($...$).
  • dpi=...: Specify a value for figure resolution, or dots-per-inch. Default is 80DPI.
  • include=...: Path to a Python script to include before the code block. Ideal to avoid repetition over many figures.

Here are some example blocks in Markdown:

This is a paragraph

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

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

This is another paragraph

```{.pyplot dpi=150 format=SVG}
# This example was taken from the Matplotlib gallery

import numpy as np
import matplotlib.pyplot as plt

N = 5
menMeans = (20, 35, 30, 35, 27)
womenMeans = (25, 32, 34, 20, 25)
menStd = (2, 3, 4, 1, 2)
womenStd = (3, 5, 2, 3, 3)
ind = np.arange(N)    # the x locations for the groups
width = 0.35       # the width of the bars: can also be len(x) sequence

p1 =, menMeans, width, color='#d62728', yerr=menStd)
p2 =, womenMeans, width,
             bottom=menMeans, yerr=womenStd)

plt.title('Scores by group and gender')
plt.xticks(ind, (G1, G2, G3, G4, G5))
plt.yticks(np.arange(0, 81, 10))
plt.legend((p1[0], p2[0]), (Men, Women))

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)

Custom configurations are possible via the Configuration type and the filter functions plotTransformWithConfig and makePlotWithConfig.


Operating on single Pandoc blocks

makePlot :: Block -> IO Block Source #

Highest-level function that can be walked over a Pandoc tree. All code blocks that have the '.pyplot' parameter will be considered figures.

makePlotWithConfig :: Configuration -> Block -> IO Block Source #

like makePlot with with a custom default values.


Operating on whole Pandoc documents

plotTransform :: Pandoc -> IO Pandoc Source #

Walk over an entire Pandoc document, changing appropriate code blocks into figures. Default configuration is used.

plotTransformWithConfig :: Configuration -> Pandoc -> IO Pandoc Source #

Walk over an entire Pandoc document, changing appropriate code blocks into figures. The default values are determined by a Configuration.


For configuration purposes

configuration :: FilePath -> IO Configuration Source #

Building configuration from a YAML file. The keys are exactly the same as for Markdown code blocks.

If a key is either not present or unreadable, its value will be set to the default value.


data Configuration Source #

Configuration of pandoc-pyplot, describing the default behavior of the filter.

A Configuration is useful when dealing with lots of figures; it avoids repeating the same values.sta





type PythonScript = Text Source #

String representation of a Python script

For testing and internal purposes only

data PandocPyplotError Source #

Possible errors returned by the filter


ScriptError Int

Running Python script has yielded an error

ScriptChecksFailedError String

Python script did not pass all checks

makePlot' :: Configuration -> Block -> IO (Either PandocPyplotError Block) Source #

Main routine to include Matplotlib plots. Code blocks containing the attributes .pyplot are considered Python plotting scripts. All other possible blocks are ignored.