pandoc-plot: A Pandoc filter to include figures generated from code blocks using your plotting toolkit of choice.

[ documentation, gpl, library, program, text ] [ Propose Tags ]

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

[Skip to Readme]
Versions [faq],,,,,,,,,,,,,,,, (info)
Change log
Dependencies async (==2.*), base (>=4.11 && <5), bytestring, containers, data-default-class (>=0.1.2 && <0.2), deepseq, directory, filepath (>=1.4 && <2), githash (>= && <1), hashable (==1.*), mtl (==2.2.*), open-browser (>=, optparse-applicative (>=0.14 && <1), pandoc (>=2.8 && <3), pandoc-plot, pandoc-types (>=1.20 && <2), shakespeare (>=2.0 && <3), template-haskell (>2.7 && <3), temporary, text (==1.*), turtle (>=1.5 && <2), typed-process (>=0.2.1 && <1), yaml (>=0.8 && <1) [details]
License GPL-2.0-only
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 2020-05-25T13:14:55Z
Distributions NixOS:
Executables pandoc-plot
Downloads 2677 total (820 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2020-05-26 [all 1 reports]


[Index] [Quick Jump]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for pandoc-plot-

[back to package description]


A Pandoc filter to generate figures from code blocks in documents

Hackage version Stackage version (nightly) Build status Build Status GitHub Conda Version

pandoc-plot turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more.

Table of content


This program is a Pandoc filter. It can therefore be used in the middle of conversion from input format to output format, replacing code blocks with figures.

The filter recognizes code blocks with classes that match plotting toolkits. For example, using the matplotlib toolkit:

# My document

This is a paragraph.

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 in an HTML page:

pandoc --filter pandoc-plot --output output.html

Note that pandoc-plot only works with pandoc >= 2.8 because of some breaking changes in pandoc's API.

Supported toolkits

pandoc-plot currently supports the following plotting toolkits (installed separately):

To know which toolkits are useable on your machine (and which ones are not available), you can check with the --toolkits/-t flag:

pandoc-plot --toolkits

Wish your plotting toolkit of choice was available? Please raise an issue!



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


```{.matlabplot caption="This is a simple figure with a **Markdown** caption"}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)


\begin{minted}[caption=This is a simple figure with a caption]{matlabplot}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)

Caption formatting unfortunately cannot be determined automatically. To specify a caption format (e.g. "markdown", "LaTeX", etc.), see Configuration.

Link to source code

In case of an output format that supports links (e.g. HTML), the embedded image generated by pandoc-plot can show a link to the source code which was used to generate the file. Therefore, other people can see what code was used to create your figures.

You can turn this on via the source=true key:


```{.mathplot source=true}



or via a configuration file.

Preamble scripts

If you find yourself always repeating some steps, inclusion of scripts is possible using the preamble parameter. For example, if you want all Matplotlib 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')

The equivalent LaTeX usage is as follows:



This preamble 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.


pandoc-plot minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. pandoc-plot will save the hash of the source code used to generate a figure in its filename. Before generating a figure, pandoc-plot will check it this figure already exists based on the hash of its source! This also means that there is no way to directly name figures.

Moreover, starting with version, pandoc-plot takes advantage of multicore CPUs, rendering figures in parallel.

Therefore, you can confidently run the filter on very large documents containing hundreds of figures, like a book or a thesis.

Compatibility with pandoc-crossref

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

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

```{#fig:myexample .plotly_python 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-plot first, and then pandoc-crossref. For example:

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


To avoid repetition, pandoc-plot can be configured using simple YAML files. pandoc-plot will look for a .pandoc-plot.yml file in the current working directory. Here are all the possible parameters:

# The following parameters affect all toolkits
directory: plots/
source: false
dpi: 80
format: PNG
caption_format: markdown+tex_math_dollars

# The possible parameters for the Matplotlib toolkit
  tight_bbox: false
  transparent: false
  executable: python

# The possible parameters for the MATLAB toolkit
  preamble: matlab.m
  executable: matlab

# The possible parameters for the Plotly/Python toolkit
  executable: python

# The possible parameters for the Mathematica toolkit
  preamble: mathematica.m
  executable: math

# The possible parameters for the GNU Octave toolkit
  preamble: octave.m
  executable: octave

# The possible parameters for the ggplot2 toolkit
  preamble: ggplot2.r
  executable: Rscript

# The possible parameters for the gnuplot toolkit
  executable: gnuplot

A file like the above sets the default values; you can still override them in documents directly.

Using pandoc-plot write-example-config will write the default configuration to a file which you can then customize.


The executable parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable.


  executable: python3
  executable: "C:\Program Files\Matlab\R2019b\bin\matlab.exe"

Toolkit-specific options


  • tight_bbox is a boolean that determines whether to use bbox_inches="tight" or not when saving Matplotlib figures. For example, tight_bbox: true. See here for details.
  • transparent is a boolean that determines whether to make Matplotlib figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, transparent: true.

Detailed usage

pandoc-plot is a command line executable with a few functions. You can take a look at the help using the -h/--help flag:

$ pandoc-plot --help
pandoc-plot - generate figures directly in documents using your plotting toolkit
of choice.

Usage: pandoc-plot.exe ([-v|--version] | [--full-version] | [-m|--manual] |   
                       [-t|--toolkits]) [COMMAND] [AST]
  This pandoc filter generates plots from code blocks using a multitude of    
  possible renderers. This allows to keep documentation and figures in perfect

Available options:
  -v,--version             Show version number and exit.
  --full-version           Show full version information and exit.
  -m,--manual              Open the manual page in the default web browser and
  -t,--toolkits            Show information on toolkits and exit. Executables
                           from the configuration file will be used, if a
                           '.pandoc-plot.yml' file is in the current directory.
  -h,--help                Show this help text

Available commands:
  clean                    Clean output directories where figures from FILE
                           might be stored. WARNING: All files in those
                           directories will be deleted.
  write-example-config     Write example configuration to a file.

More information can be found via the manual (pandoc-plot --manual) or the repository README, located at

As a filter

The most common use for pandoc-plot is as a pandoc filter, in which case it should be called without arguments. For example:

pandoc --filter pandoc-plot -i -o output.html

If pandoc-plot fails to render a code block into a figure, the filtering will not stop. Your code blocks will stay unchanged.

You can chain other filters with it (e.g., pandoc-crossref) like so:

pandoc --filter pandoc-plot --filter pandoc-crossref -i -o output.html

Cleaning output

Figures produced by pandoc-plot can be placed in a few different locations. You can set a default location in the Configuration, but you can also re-direct specific figures in other directories if you use the directory=... argument in code blocks. These figures will build up over time. You can use the clean command to scan documents and delete the associated pandoc-plot output files. For example, to delete the figures generated from the file:

pandoc-plot clean

This sill remove all directories where a figure could have been placed. WARNING: all files will be removed.

Configuration template

Because pandoc-plot supports a few toolkits, there are a lot of configuration options. Don't start from scratch! The write-example-config command will create a file for you, which you can then modify:

pandoc-plot write-example-config

You will need to re-name the file to .pandoc-ploy.yml to be able to use it, so don't worry about overwriting your own configuration.

As a Haskell library

To include the functionality of pandoc-plot in a Haskell package, you can use the makePlot function (for single blocks) or plotTransform function (for entire documents). Take a look at the documentation on Hackage.

Usage 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.Plot (plotTransform)

import Data.Default (def) -- From data-default package, for default configuration
import Hakyll

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


Binaries and Installers

Windows, Linux, and Mac OS binaries are available on the GitHub release page. There are also Windows installers.


Like pandoc, pandoc-plot is available as a package installable with conda. Click here to see the package page.

To install in the current environment:

conda install -c conda-forge pandoc-plot

From Hackage/Stackage

pandoc-plot is available on Hackage and Stackage. Using the cabal-install tool:

cabal update
cabal install pandoc-plot


stack update
stack install pandoc-plot

From source

Building from source can be done using stack or cabal:

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


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