pandoc-plot-1.5.0: docs/MANUAL.html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang xml:lang>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>pandoc-plot 1.3.0 manual</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<link rel="stylesheet" href="data:text/css,html%20%7B%20font%2Dsize%3A%20100%25%3B%20overflow%2Dy%3A%20scroll%3B%20%2Dwebkit%2Dtext%2Dsize%2Dadjust%3A%20100%25%3B%20%2Dms%2Dtext%2Dsize%2Dadjust%3A%20100%25%3B%20%7Dbody%7Bcolor%3A%23444%3Bfont%2Dfamily%3AGeorgia%2C%20Palatino%2C%20%27Palatino%20Linotype%27%2C%20Times%2C%20%27Times%20New%20Roman%27%2C%20serif%3Bfont%2Dsize%3A12px%3Bline%2Dheight%3A1%2E5em%3Bpadding%3A1em%3Bmargin%3Aauto%3Bmax%2Dwidth%3A42em%3Bbackground%3A%23fefefe%3B%7Da%7B%20color%3A%20%230645ad%3B%20text%2Ddecoration%3Anone%3B%7Da%3Avisited%7B%20color%3A%20%230b0080%3B%20%7Da%3Ahover%7B%20color%3A%20%2306e%3B%20%7Da%3Aactive%7B%20color%3A%23faa700%3B%20%7Da%3Afocus%7B%20outline%3A%20thin%20dotted%3B%20%7Da%3Ahover%2C%20a%3Aactive%7B%20outline%3A%200%3B%20%7D%3A%3A%2Dmoz%2Dselection%7Bbackground%3Argba%28255%2C255%2C0%2C0%2E3%29%3Bcolor%3A%23000%7D%3A%3Aselection%7Bbackground%3Argba%28255%2C255%2C0%2C0%2E3%29%3Bcolor%3A%23000%7Da%3A%3A%2Dmoz%2Dselection%7Bbackground%3Argba%28255%2C255%2C0%2C0%2E3%29%3Bcolor%3A%230645ad%7Da%3A%3Aselection%7Bbackground%3Argba%28255%2C255%2C0%2C0%2E3%29%3Bcolor%3A%230645ad%7Dp%7Bmargin%3A1em%200%3B%7Dimg%7Bmax%2Dwidth%3A100%25%3B%7Dh1%2Ch2%2Ch3%2Ch4%2Ch5%2Ch6%7Bfont%2Dweight%3Anormal%3Bcolor%3A%23111%3Bline%2Dheight%3A1em%3B%7Dh4%2Ch5%2Ch6%7B%20font%2Dweight%3A%20bold%3B%20%7Dh1%7B%20font%2Dsize%3A2%2E5em%3B%20%7Dh2%7B%20font%2Dsize%3A2em%3B%20%7Dh3%7B%20font%2Dsize%3A1%2E5em%3B%20%7Dh4%7B%20font%2Dsize%3A1%2E2em%3B%20%7Dh5%7B%20font%2Dsize%3A1em%3B%20%7Dh6%7B%20font%2Dsize%3A0%2E9em%3B%20%7Dblockquote%7Bcolor%3A%23666666%3Bmargin%3A0%3Bpadding%2Dleft%3A%203em%3Bborder%2Dleft%3A%200%2E5em%20%23EEE%20solid%3B%7Dhr%20%7B%20display%3A%20block%3B%20height%3A%202px%3B%20border%3A%200%3B%20border%2Dtop%3A%201px%20solid%20%23aaa%3Bborder%2Dbottom%3A%201px%20solid%20%23eee%3B%20margin%3A%201em%200%3B%20padding%3A%200%3B%20%7Dpre%2C%20code%2C%20kbd%2C%20samp%20%7B%20color%3A%20%23000%3B%20font%2Dfamily%3A%20monospace%2C%20monospace%3B%20%5Ffont%2Dfamily%3A%20%27courier%20new%27%2C%20monospace%3B%20font%2Dsize%3A%200%2E98em%3B%20%7Dpre%20%7B%20white%2Dspace%3A%20pre%3B%20white%2Dspace%3A%20pre%2Dwrap%3B%20word%2Dwrap%3A%20break%2Dword%3B%20%7Db%2C%20strong%20%7B%20font%2Dweight%3A%20bold%3B%20%7Ddfn%20%7B%20font%2Dstyle%3A%20italic%3B%20%7Dins%20%7B%20background%3A%20%23ff9%3B%20color%3A%20%23000%3B%20text%2Ddecoration%3A%20none%3B%20%7Dmark%20%7B%20background%3A%20%23ff0%3B%20color%3A%20%23000%3B%20font%2Dstyle%3A%20italic%3B%20font%2Dweight%3A%20bold%3B%20%7Dsub%2C%20sup%20%7B%20font%2Dsize%3A%2075%25%3B%20line%2Dheight%3A%200%3B%20position%3A%20relative%3B%20vertical%2Dalign%3A%20baseline%3B%20%7Dsup%20%7B%20top%3A%20%2D0%2E5em%3B%20%7Dsub%20%7B%20bottom%3A%20%2D0%2E25em%3B%20%7Dul%2C%20ol%20%7B%20margin%3A%201em%200%3B%20padding%3A%200%200%200%202em%3B%20%7Dli%20p%3Alast%2Dchild%20%7B%20margin%3A0%20%7Ddd%20%7B%20margin%3A%200%200%200%202em%3B%20%7Dimg%20%7B%20border%3A%200%3B%20%2Dms%2Dinterpolation%2Dmode%3A%20bicubic%3B%20vertical%2Dalign%3A%20middle%3B%20%7Dtable%20%7Bborder%2Dcollapse%3A%20collapse%3Bborder%2Dspacing%3A%200%3Bwidth%3A%20100%25%3B%7Dth%20%7B%20border%2Dbottom%3A%201px%20solid%20black%3B%20%7Dtd%20%7B%20vertical%2Dalign%3A%20top%3B%20%7D%40media%20only%20screen%20and%20%28min%2Dwidth%3A%20480px%29%20%7Bbody%7Bfont%2Dsize%3A14px%3B%7D%7D%40media%20only%20screen%20and%20%28min%2Dwidth%3A%20768px%29%20%7Bbody%7Bfont%2Dsize%3A16px%3B%7D%7D%40media%20print%20%7B%2A%20%7B%20background%3A%20transparent%20%21important%3B%20color%3A%20black%20%21important%3B%20filter%3Anone%20%21important%3B%20%2Dms%2Dfilter%3A%20none%20%21important%3B%20%7Dbody%7Bfont%2Dsize%3A12pt%3B%20max%2Dwidth%3A100%25%3B%7Da%2C%20a%3Avisited%20%7B%20text%2Ddecoration%3A%20underline%3B%20%7Dhr%20%7B%20height%3A%201px%3B%20border%3A0%3B%20border%2Dbottom%3A1px%20solid%20black%3B%20%7Da%5Bhref%5D%3Aafter%20%7B%20content%3A%20%22%20%28%22%20attr%28href%29%20%22%29%22%3B%20%7Dabbr%5Btitle%5D%3Aafter%20%7B%20content%3A%20%22%20%28%22%20attr%28title%29%20%22%29%22%3B%20%7D%2Eir%20a%3Aafter%2C%20a%5Bhref%5E%3D%22javascript%3A%22%5D%3Aafter%2C%20a%5Bhref%5E%3D%22%23%22%5D%3Aafter%20%7B%20content%3A%20%22%22%3B%20%7Dpre%2C%20blockquote%20%7B%20border%3A%201px%20solid%20%23999%3B%20padding%2Dright%3A%201em%3B%20page%2Dbreak%2Dinside%3A%20avoid%3B%20%7Dtr%2C%20img%20%7B%20page%2Dbreak%2Dinside%3A%20avoid%3B%20%7Dimg%20%7B%20max%2Dwidth%3A%20100%25%20%21important%3B%20%7D%40page%20%3Aleft%20%7B%20margin%3A%2015mm%2020mm%2015mm%2010mm%3B%20%7D%40page%20%3Aright%20%7B%20margin%3A%2015mm%2010mm%2015mm%2020mm%3B%20%7Dp%2C%20h2%2C%20h3%20%7B%20orphans%3A%203%3B%20widows%3A%203%3B%20%7Dh2%2C%20h3%20%7B%20page%2Dbreak%2Dafter%3A%20avoid%3B%20%7D%7D" />
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header id="title-block-header">
<h1 class="title">pandoc-plot 1.3.0 manual</h1>
</header>
<!--
The file MANUAL.md is automatically generated by the tools/mkmanual.ps1 script. Do not edit manually.
-->
<h2 id="a-pandoc-filter-to-generate-figures-from-code-blocks-in-documents">A Pandoc filter to generate figures from code blocks in documents</h2>
<p><code>pandoc-plot</code> 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.</p>
<ul>
<li><a href="#features-overview">Features Overview</a>
<ul>
<li><a href="#captions">Captions</a></li>
<li><a href="#link-to-source-code">Link to source code</a></li>
<li><a href="#preamble-scripts">Preamble scripts</a></li>
<li><a href="#support-for-interactive-plots">Support for interactive plots</a></li>
<li><a href="#performance">Performance</a></li>
<li><a href="#compatibility-with-pandoc-crossref">Compatibility with pandoc-crossref</a></li>
</ul></li>
<li><a href="#detailed-usage">Detailed usage</a>
<ul>
<li><a href="#as-a-filter">As a filter</a></li>
<li><a href="#syntax">Syntax</a>
<ul>
<li><a href="#markdown">Markdown</a></li>
<li><a href="#latex">LaTeX</a></li>
</ul></li>
<li><a href="#parameters-and-options">Parameters and options</a>
<ul>
<li><a href="#code-highlighting">Code highlighting</a></li>
</ul></li>
<li><a href="#interactive-html-figures">Interactive HTML figures</a></li>
<li><a href="#configuration">Configuration</a>
<ul>
<li><a href="#executables">Executables</a></li>
<li><a href="#command-line-arguments">Command-line arguments</a></li>
<li><a href="#toolkit-specific-options">Toolkit-specific options</a></li>
<li><a href="#logging">Logging</a></li>
<li><a href="#strict-mode">Strict mode</a></li>
</ul></li>
<li><a href="#other-commands">Other commands</a>
<ul>
<li><a href="#finding-installed-toolkits">Finding installed toolkits</a></li>
<li><a href="#cleaning-output">Cleaning output</a></li>
<li><a href="#configuration-template">Configuration template</a></li>
</ul></li>
<li><a href="#as-a-haskell-library">As a Haskell library</a>
<ul>
<li><a href="#usage-with-hakyll">Usage with Hakyll</a></li>
</ul></li>
</ul></li>
<li><a href="#warning">Warning</a></li>
</ul>
<h2 id="features-overview">Features Overview</h2>
<h3 id="captions">Captions</h3>
<p>You can also specify a caption for your image. This is done using the optional <code>caption</code> parameter.</p>
<p><strong>Markdown</strong>:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{.matlabplot caption="This is a simple figure with a **Markdown** caption"}</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="in">x = 0: .1 : 2*pi;</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="in">y1 = cos(x);</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="in">y2 = sin(x);</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="in">figure</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="in">plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)</span></span>
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span></code></pre></div>
<p><strong>LaTex</strong>:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[caption=This is a simple figure with a caption]{matlabplot}</span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="vs">x = 0: .1 : 2*pi;</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="vs">y1 = cos(x);</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="vs">y2 = sin(x);</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="vs">figure</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="vs">plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<p>Caption formatting unfortunately cannot be determined automatically. To specify a caption format (e.g. “markdown”, “LaTeX”, etc.), see <a href="#configuration">Configuration</a>.</p>
<h3 id="link-to-source-code">Link to source code</h3>
<p>In case of an output format that supports links (e.g. HTML), the embedded image generated by <code>pandoc-plot</code> 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.</p>
<p>You can turn this on via the <code>source=true</code> key:</p>
<p><strong>Markdown</strong>:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{.mathplot source=true}</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="in">...</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span></code></pre></div>
<p><strong>LaTex</strong>:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[source=true]{mathplot}</span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="vs">...</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<p>or via a <a href="#Configuration">configuration file</a>.</p>
<h3 id="preamble-scripts">Preamble scripts</h3>
<p>If you find yourself always repeating some steps, inclusion of scripts is possible using the <code>preamble</code> parameter. For example, if you want all Matplotlib plots to have the <a href="https://matplotlib.org/tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py"><code>ggplot</code></a> style, you can write a very short preamble <code>style.py</code> like so:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="im">import</span> matplotlib.pyplot <span class="im">as</span> plt</span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>plt.style.use(<span class="st">'ggplot'</span>)</span></code></pre></div>
<p>and include it in your document as follows:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{.matplotlib preamble=style.py}</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="in">plt.figure()</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="in">plt.plot([0,1,2,3,4], [1,2,3,4,5])</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="in">plt.title('This is an example figure')</span></span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span></code></pre></div>
<p>Which is equivalent to writing the following markdown:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{.matplotlib}</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="in">import matplotlib.pyplot as plt</span></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="in">plt.style.use('ggplot')</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a><span class="in">plt.figure()</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a><span class="in">plt.plot([0,1,2,3,4], [1,2,3,4,5])</span></span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a><span class="in">plt.title('This is an example figure')</span></span>
<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span></code></pre></div>
<p>The equivalent LaTeX usage is as follows:</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[include=style.py]{matplotlib}</span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<p>This <code>preamble</code> 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.</p>
<h3 id="support-for-interactive-plots">Support for interactive plots</h3>
<p>Starting with version 0.8.0.0, <code>pandoc-plot</code> supports the creation of interactive plots (if a toolkit supports it). All you need to do is set the save format to <code>html</code>. The resulting plot is fully self-contained, so it can be displayed offline.</p>
<h3 id="performance">Performance</h3>
<p><code>pandoc-plot</code> minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. <code>pandoc-plot</code> will save the hash of the source code used to generate a figure in its filename. Before generating a figure, <code>pandoc-plot</code> 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.</p>
<p>Moreover, starting with version 0.5.0.0, <code>pandoc-plot</code> takes advantage of multicore CPUs, rendering figures <strong>in parallel</strong>.</p>
<p>Therefore, you can confidently run the filter on very large documents containing hundreds of figures, like a book or a thesis.</p>
<h3 id="compatibility-with-pandoc-crossref">Compatibility with pandoc-crossref</h3>
<p><a href="https://github.com/lierdakil/pandoc-crossref"><code>pandoc-crossref</code></a> is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents.</p>
<p>You can use <code>pandoc-crossref</code> in conjunction with <code>pandoc-plot</code> for the ultimate figure-making pipeline. You can combine both in a figure like so:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="in">```{#fig:myexample .plotly_python caption="This is a caption"}</span></span>
<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="in"># Insert figure script here</span></span>
<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span>
<span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a>As you can see in @fig:myexample, ...</span></code></pre></div>
<p>If the above source is located in file <code>myfile.md</code>, you can render the figure and references by applying <code>pandoc-plot</code> <strong>first</strong>, and then <code>pandoc-crossref</code>. For example:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--filter</span> pandoc-plot <span class="at">--filter</span> pandoc-crossref <span class="at">-i</span> myfile.md <span class="at">-o</span> myfile.html</span></code></pre></div>
<h2 id="detailed-usage">Detailed usage</h2>
<p><code>pandoc-plot</code> is a command line executable with a few functions. You can take a look at the help using the <code>-h</code>/<code>--help</code> flag:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc-plot</span> 1.3.0 <span class="at">-</span> generate figures directly in documents</span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">Usage:</span> pandoc-plot.EXE [<span class="er">(</span><span class="ex">-v</span><span class="kw">|</span><span class="ex">--version</span><span class="kw">)</span> <span class="kw">|</span> <span class="ex">--full-version</span> <span class="kw">|</span> <span class="kw">(</span><span class="ex">-m</span><span class="kw">|</span><span class="ex">--manual</span><span class="kw">)</span><span class="ex">]</span> </span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a> <span class="ex">[COMMAND]</span> [AST]</span>
<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a> <span class="ex">This</span> pandoc filter generates plots from code blocks using a multitude of</span>
<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a> <span class="ex">possible</span> renderers. This allows to keep documentation and figures in perfect</span>
<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a> <span class="ex">synchronicity.</span></span>
<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a><span class="ex">Available</span> options:</span>
<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a> <span class="ex">-v,--version</span> Show version number and exit.</span>
<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a> <span class="ex">--full-version</span> Show full version information and exit.</span>
<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a> <span class="ex">-m,--manual</span> Open the manual page in the default web browser and</span>
<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a> <span class="ex">exit.</span></span>
<span id="cb11-14"><a href="#cb11-14" aria-hidden="true" tabindex="-1"></a> <span class="ex">-h,--help</span> Show this help text</span>
<span id="cb11-15"><a href="#cb11-15" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-16"><a href="#cb11-16" aria-hidden="true" tabindex="-1"></a><span class="ex">Available</span> commands:</span>
<span id="cb11-17"><a href="#cb11-17" aria-hidden="true" tabindex="-1"></a> <span class="ex">toolkits</span> Show information on toolkits and exit.</span>
<span id="cb11-18"><a href="#cb11-18" aria-hidden="true" tabindex="-1"></a> <span class="ex">clean</span> Clean output directories where figures from FILE and</span>
<span id="cb11-19"><a href="#cb11-19" aria-hidden="true" tabindex="-1"></a> <span class="ex">log</span> files might be stored. WARNING: All files in</span>
<span id="cb11-20"><a href="#cb11-20" aria-hidden="true" tabindex="-1"></a> <span class="ex">those</span> directories will be deleted.</span>
<span id="cb11-21"><a href="#cb11-21" aria-hidden="true" tabindex="-1"></a> <span class="ex">write-example-config</span> Write example configuration to a file and exit.</span>
<span id="cb11-22"><a href="#cb11-22" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-23"><a href="#cb11-23" aria-hidden="true" tabindex="-1"></a><span class="ex">More</span> information can be found via the manual <span class="er">(</span><span class="ex">pandoc-plot</span> <span class="at">--manual</span><span class="kw">)</span> <span class="ex">or</span> the</span>
<span id="cb11-24"><a href="#cb11-24" aria-hidden="true" tabindex="-1"></a><span class="ex">repository</span> README, located at https://github.com/LaurentRDC/pandoc-plot</span></code></pre></div>
<h3 id="as-a-filter">As a filter</h3>
<p>The most common use for <code>pandoc-plot</code> is as a pandoc filter, in which case it should be called without arguments. For example:</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--filter</span> pandoc-plot <span class="at">-i</span> input.md <span class="at">-o</span> output.html</span></code></pre></div>
<p>If <code>pandoc-plot</code> fails to render a code block into a figure, the filtering will not stop. Your code blocks will stay unchanged, unless you activate <a href="#strict-mode">strict mode</a>.</p>
<p>You can chain other filters with it (e.g., <a href="https://github.com/lierdakil/pandoc-crossref"><code>pandoc-crossref</code></a>) like so:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--filter</span> pandoc-plot <span class="at">--filter</span> pandoc-crossref <span class="at">-i</span> input.md <span class="at">-o</span> output.html</span></code></pre></div>
<h3 id="syntax">Syntax</h3>
<p>The syntax for code blocks in documents is shown below. <code>pandoc-plot</code> looks for code blocks with a specific class, depending on the toolkit you want to use. <code>pandoc-plot</code> will run the code and capture the figure output. There can only be <strong>one</strong> figure per code block.</p>
<p>The possible parameters and options are described in <a href="#parameters-and-options">further below</a>.</p>
<h4 id="markdown">Markdown</h4>
<div class="sourceCode" id="cb14"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a> <span class="in">```{.cls param1=value1 param2=value2 ...}</span></span>
<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="in"> # script content</span></span>
<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="in"> ```</span></span></code></pre></div>
<h4 id="latex">LaTeX</h4>
<p>Note that the <code>minted</code> LaTeX package need not be installed.</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[param1=value1, param2=value2, ...]{cls}</span>
<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="vs">...</span></span>
<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<h3 id="parameters-and-options">Parameters and options</h3>
<p>There are parameters that affect the figure that will be included in your document. Here are all the possible general parameters, in Markdown syntax:</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a> <span class="in">```{.cls </span></span>
<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="in"> .language</span></span>
<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="in"> directory=(path) </span></span>
<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a><span class="in"> caption=(text) </span></span>
<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a><span class="in"> format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP|HTML|LATEX) </span></span>
<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="in"> source=(true|True|false|False) </span></span>
<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a><span class="in"> source_label=(text)</span></span>
<span id="cb16-8"><a href="#cb16-8" aria-hidden="true" tabindex="-1"></a><span class="in"> preamble=(path) </span></span>
<span id="cb16-9"><a href="#cb16-9" aria-hidden="true" tabindex="-1"></a><span class="in"> dpi=(integer)</span></span>
<span id="cb16-10"><a href="#cb16-10" aria-hidden="true" tabindex="-1"></a><span class="in"> dependencies=[...]</span></span>
<span id="cb16-11"><a href="#cb16-11" aria-hidden="true" tabindex="-1"></a><span class="in"> file=(path)</span></span>
<span id="cb16-12"><a href="#cb16-12" aria-hidden="true" tabindex="-1"></a><span class="in"> executable=(path) </span></span>
<span id="cb16-13"><a href="#cb16-13" aria-hidden="true" tabindex="-1"></a><span class="in"> caption_format=(text)</span></span>
<span id="cb16-14"><a href="#cb16-14" aria-hidden="true" tabindex="-1"></a><span class="in"> }</span></span>
<span id="cb16-15"><a href="#cb16-15" aria-hidden="true" tabindex="-1"></a><span class="in"> # script content</span></span>
<span id="cb16-16"><a href="#cb16-16" aria-hidden="true" tabindex="-1"></a><span class="in"> ```</span></span></code></pre></div>
<ul>
<li><code>cls</code> must be one of the following: <code>matplotlib</code>, <code>matlabplot</code>, <code>plotly_python</code>, <code>plotly_r</code>, <code>mathplot</code>, <code>octaveplot</code>, <code>ggplot2</code>, <code>gnuplot</code>, <code>graphviz</code>, <code>bokeh</code>, <code>plotsjl</code>, <code>plantuml</code> (<em>new in version 1.1.0</em>).</li>
</ul>
<p>All following parameters are optional, with their default values controlled by the <a href="#configuration">configuration</a>.</p>
<ul>
<li><code>language</code> specifies the programming language used in this block. This parameter is ignored by <code>pandoc-plot</code>, but your text editor may use it to highlight code. See <a href="#code-highlighting">Code highlighting</a> below.</li>
<li><code>directory</code> is a path to the directory where the figure and source code will be saved. You cannot control the file name. This path is either absolute, or relative from the working directory where you call <code>pandoc-plot</code>.</li>
<li><code>caption</code> is the caption text. The format of the caption is specified in the <code>caption_format</code> parameter, described below.</li>
<li><code>format</code> is the desired filetype for the resulting figure. Possible values for <code>format</code> are [<code>PNG</code>, <code>PDF</code>, <code>SVG</code>, <code>JPG</code>, <code>EPS</code>, <code>GIF</code>, <code>TIF</code>, <code>WEBP</code>, <code>HTML</code>, <code>LATEX</code>]. Not all toolkits support all formats. See <code>pandoc-plot toolkits</code> for toolkit-specific information regarding save formats. The <code>HTML</code> format is special; it can produce standalone, offline, interactive plots. As such, it only makes sense to use this format when creating HTML documents. Similarly, the <code>LATEX</code> format is special; plots in the LaTeX format will be embedded in the document. Therefore, it only makes sense to use this format when creating LaTeX documents.</li>
<li><code>source</code> is a boolean toggle that determines whether the source code should be linked in the caption or not. Possible values are [<code>true</code>, <code>True</code>, <code>false</code>, <code>False</code>].</li>
<li><code>source_label</code> is the text that links to source code (if <code>source=true</code>). This is useful if you are writing text in a different language. The default is <code>source_label="Source Code"</code>. You might want to set this via the <a href="#configuration">configuration</a> instead.</li>
<li><code>preamble</code> is a path to a script that will be included as a preamble to the content of the code block. This path is either absolute, or relative from the working directory where you call <code>pandoc-plot</code>.</li>
<li><code>dpi</code> is the pixel density of the figure in dots-per-inch. Possible values are positive integers. Not all toolkits respect this.</li>
<li><code>dependencies</code> is a list of files/directories that affect the figure, for example data files. If one of those files/directories changes, <code>pandoc-plot</code> will re-render the associated figure. Format is a comma-separated list, e.g. <code>dependencies=[data.txt, foo.bar, ~/wtv]</code>. Values for <code>dependencies</code> in the configuration file will be appended to the values in a code block.</li>
<li><code>file</code> is a path to a file from which to read the figure content. If this parameter is used, the content of the code block is ignored. By using this parameter, you can use all the standard tooling of your plotting toolkit of choice, which is especially useful for complex figures.</li>
<li><code>executable</code> is a path to the executable to use (e.g. <code>C:\\python3.exe</code>) or the name of the executable (e.g. <code>python3</code>).</li>
<li><code>caption_format</code> is the text format of the caption. Possible values are exactly the same as <code>pandoc</code>’s format specification, usually <code>FORMAT+EXTENSION-EXTENSION</code>. For example, captions in Markdown with raw LaTeX would be parsed correctly provided that <code>caption_format=markdown+raw_tex</code>. See Pandoc’s guide on <a href="https://pandoc.org/MANUAL.html#specifying-formats">Specifying formats</a>.</li>
</ul>
<h4 id="code-highlighting">Code highlighting</h4>
<p>If your editor supports code highlighting in code blocks, you can also include the programming language. In Markdown:</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a> <span class="in">```{.language .cls (options)}</span></span>
<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="in"> # script content</span></span>
<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a><span class="in"> ```</span></span></code></pre></div>
<p>or Latex:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a> <span class="kw">\begin</span>{<span class="ex">minted</span>}[(options)]{language, cls}</span>
<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="vs"> # script content</span></span>
<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="vs"> </span><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<p>For example, for GGPlot2 figures:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a> <span class="in">```{.r .ggplot2 caption=Highlighted code block}</span></span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="in"> # script content</span></span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a><span class="in"> ```</span></span></code></pre></div>
<p>or (Latex):</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a> <span class="kw">\begin</span>{<span class="ex">minted</span>}[caption=Highlighted code block]{r, ggplot2}</span>
<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="vs"> # script content</span></span>
<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="vs"> </span><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div>
<p>This way, you benefit from code highlighting <em>and</em> <code>pandoc-plot</code>.</p>
<h3 id="interactive-html-figures">Interactive HTML figures</h3>
<p>Interactive HTML figures are available for a few toolkits, e.g. <code>bokeh</code>. To make a figure interactive, use the output format <code>format=html</code>. This only makes sense if your output file is also HTML.</p>
<p>You can take a look at the <a href="https://laurentrdc.github.io/pandoc-plot/">demonstration page</a> for an example result.</p>
<p>Many interactive plots rely on javascript scripts stored on the internet. If you want to have a self-contained document that can be viewed offline – or you want your document to work for the next 10 years –, you can use pandoc’s <code>--self-contained</code> flag:</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--self-contained</span> <span class="at">--filter</span> pandoc-plot <span class="at">-i</span> mydoc.md <span class="at">-o</span> webpage.html </span></code></pre></div>
<p>The resulting output <code>webpage.html</code> will contain everything, at the cost of size.</p>
<h3 id="configuration">Configuration</h3>
<p>To avoid repetition, <code>pandoc-plot</code> can be configured using simple YAML
files. Here are <strong>all</strong> the possible parameters:</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="co"># This is an example configuration. Everything in this file is optional.</span></span>
<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="co"># Please refer to the documentation to know about the parameters herein.</span></span>
<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="co">#</span></span>
<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a><span class="co"># The `executable` parameter for all toolkits can be either the</span></span>
<span id="cb22-5"><a href="#cb22-5" aria-hidden="true" tabindex="-1"></a><span class="co"># executable name (if it is present on the PATH), or</span></span>
<span id="cb22-6"><a href="#cb22-6" aria-hidden="true" tabindex="-1"></a><span class="co"># the full path to the executable.</span></span>
<span id="cb22-7"><a href="#cb22-7" aria-hidden="true" tabindex="-1"></a><span class="co"># E.g.:</span></span>
<span id="cb22-8"><a href="#cb22-8" aria-hidden="true" tabindex="-1"></a><span class="co"># executable: python3</span></span>
<span id="cb22-9"><a href="#cb22-9" aria-hidden="true" tabindex="-1"></a><span class="co"># executable: "C:\Python37\Scripts\python.exe"</span></span>
<span id="cb22-10"><a href="#cb22-10" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-11"><a href="#cb22-11" aria-hidden="true" tabindex="-1"></a><span class="co"># The following parameters affect all toolkits</span></span>
<span id="cb22-12"><a href="#cb22-12" aria-hidden="true" tabindex="-1"></a><span class="co"># Directory where to save the plots. The path can be relative to pandoc-plot's</span></span>
<span id="cb22-13"><a href="#cb22-13" aria-hidden="true" tabindex="-1"></a><span class="co"># current working directory, or absolute.</span></span>
<span id="cb22-14"><a href="#cb22-14" aria-hidden="true" tabindex="-1"></a><span class="fu">directory</span><span class="kw">:</span><span class="at"> plots/</span></span>
<span id="cb22-15"><a href="#cb22-15" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-16"><a href="#cb22-16" aria-hidden="true" tabindex="-1"></a><span class="co"># Whether or not to include a link to the source script in the caption. </span></span>
<span id="cb22-17"><a href="#cb22-17" aria-hidden="true" tabindex="-1"></a><span class="co"># Particularly useful for HTML output.</span></span>
<span id="cb22-18"><a href="#cb22-18" aria-hidden="true" tabindex="-1"></a><span class="fu">source</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span>
<span id="cb22-19"><a href="#cb22-19" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-20"><a href="#cb22-20" aria-hidden="true" tabindex="-1"></a><span class="co"># When `strict: false`, pandoc-plot will leave code blocks untouched if a plot</span></span>
<span id="cb22-21"><a href="#cb22-21" aria-hidden="true" tabindex="-1"></a><span class="co"># could not be generated. This could happen if, for example, a toolkit is not</span></span>
<span id="cb22-22"><a href="#cb22-22" aria-hidden="true" tabindex="-1"></a><span class="co"># installed. If you want pandoc-plot to fail instead, use `strict: true`.</span></span>
<span id="cb22-23"><a href="#cb22-23" aria-hidden="true" tabindex="-1"></a><span class="fu">strict</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span>
<span id="cb22-24"><a href="#cb22-24" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-25"><a href="#cb22-25" aria-hidden="true" tabindex="-1"></a><span class="co"># Text label for links to source code.</span></span>
<span id="cb22-26"><a href="#cb22-26" aria-hidden="true" tabindex="-1"></a><span class="co"># You can change this label if you are writing a document in a non-English language. </span></span>
<span id="cb22-27"><a href="#cb22-27" aria-hidden="true" tabindex="-1"></a><span class="co"># This only matters if `source` is set to `true`.</span></span>
<span id="cb22-28"><a href="#cb22-28" aria-hidden="true" tabindex="-1"></a><span class="fu">source_label</span><span class="kw">:</span><span class="at"> Source code</span></span>
<span id="cb22-29"><a href="#cb22-29" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-30"><a href="#cb22-30" aria-hidden="true" tabindex="-1"></a><span class="co"># Default density of figures in dots per inches (DPI). </span></span>
<span id="cb22-31"><a href="#cb22-31" aria-hidden="true" tabindex="-1"></a><span class="co"># This can be changed in the document specifically as well.</span></span>
<span id="cb22-32"><a href="#cb22-32" aria-hidden="true" tabindex="-1"></a><span class="fu">dpi</span><span class="kw">:</span><span class="at"> </span><span class="dv">80</span></span>
<span id="cb22-33"><a href="#cb22-33" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-34"><a href="#cb22-34" aria-hidden="true" tabindex="-1"></a><span class="co"># Default format in which to save the figures. This can be specified </span></span>
<span id="cb22-35"><a href="#cb22-35" aria-hidden="true" tabindex="-1"></a><span class="co"># individually as well.</span></span>
<span id="cb22-36"><a href="#cb22-36" aria-hidden="true" tabindex="-1"></a><span class="fu">format</span><span class="kw">:</span><span class="at"> PNG</span></span>
<span id="cb22-37"><a href="#cb22-37" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-38"><a href="#cb22-38" aria-hidden="true" tabindex="-1"></a><span class="co"># Default files/directories on which all figures depend. If any of these files/directories</span></span>
<span id="cb22-39"><a href="#cb22-39" aria-hidden="true" tabindex="-1"></a><span class="co"># changes, all figures will be re-rendered.</span></span>
<span id="cb22-40"><a href="#cb22-40" aria-hidden="true" tabindex="-1"></a><span class="co"># Dependencies specified in code blocks will be appended to this list.</span></span>
<span id="cb22-41"><a href="#cb22-41" aria-hidden="true" tabindex="-1"></a><span class="fu">dependencies</span><span class="kw">:</span></span>
<span id="cb22-42"><a href="#cb22-42" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> file1.txt</span></span>
<span id="cb22-43"><a href="#cb22-43" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> file2.txt</span></span>
<span id="cb22-44"><a href="#cb22-44" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-45"><a href="#cb22-45" aria-hidden="true" tabindex="-1"></a><span class="co"># Text format for the captions. Unfortunately, there is no way to detect</span></span>
<span id="cb22-46"><a href="#cb22-46" aria-hidden="true" tabindex="-1"></a><span class="co"># this automatically. You can use the same notation as Pandoc's --from </span></span>
<span id="cb22-47"><a href="#cb22-47" aria-hidden="true" tabindex="-1"></a><span class="co"># parameter, specified here: </span></span>
<span id="cb22-48"><a href="#cb22-48" aria-hidden="true" tabindex="-1"></a><span class="co"># https://pandoc.org/MANUAL.html#option--from</span></span>
<span id="cb22-49"><a href="#cb22-49" aria-hidden="true" tabindex="-1"></a><span class="co"># Example: markdown, rst+raw_tex</span></span>
<span id="cb22-50"><a href="#cb22-50" aria-hidden="true" tabindex="-1"></a><span class="fu">caption_format</span><span class="kw">:</span><span class="at"> markdown+tex_math_dollars</span></span>
<span id="cb22-51"><a href="#cb22-51" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-52"><a href="#cb22-52" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-53"><a href="#cb22-53" aria-hidden="true" tabindex="-1"></a><span class="co"># Logging configuration</span></span>
<span id="cb22-54"><a href="#cb22-54" aria-hidden="true" tabindex="-1"></a><span class="fu">logging</span><span class="kw">:</span></span>
<span id="cb22-55"><a href="#cb22-55" aria-hidden="true" tabindex="-1"></a><span class="co"> # Possible verbosity values: debug, error, warning, info, silent</span></span>
<span id="cb22-56"><a href="#cb22-56" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">verbosity</span><span class="kw">:</span><span class="at"> warning</span></span>
<span id="cb22-57"><a href="#cb22-57" aria-hidden="true" tabindex="-1"></a><span class="co"> # If the filepath below is not present, then pandoc-plot will log to stderr</span></span>
<span id="cb22-58"><a href="#cb22-58" aria-hidden="true" tabindex="-1"></a><span class="co"> # Otherwise, log messages will be appended to the filepath.</span></span>
<span id="cb22-59"><a href="#cb22-59" aria-hidden="true" tabindex="-1"></a><span class="co"> # filepath: path/to/file.txt</span></span>
<span id="cb22-60"><a href="#cb22-60" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-61"><a href="#cb22-61" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Matplotlib toolkit</span></span>
<span id="cb22-62"><a href="#cb22-62" aria-hidden="true" tabindex="-1"></a><span class="fu">matplotlib</span><span class="kw">:</span></span>
<span id="cb22-63"><a href="#cb22-63" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: matplotlib.py</span></span>
<span id="cb22-64"><a href="#cb22-64" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">tight_bbox</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span>
<span id="cb22-65"><a href="#cb22-65" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">transparent</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span>
<span id="cb22-66"><a href="#cb22-66" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span>
<span id="cb22-67"><a href="#cb22-67" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-68"><a href="#cb22-68" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-69"><a href="#cb22-69" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the MATLAB toolkit</span></span>
<span id="cb22-70"><a href="#cb22-70" aria-hidden="true" tabindex="-1"></a><span class="fu">matlabplot</span><span class="kw">:</span></span>
<span id="cb22-71"><a href="#cb22-71" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: matlab.m</span></span>
<span id="cb22-72"><a href="#cb22-72" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> matlab</span></span>
<span id="cb22-73"><a href="#cb22-73" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-74"><a href="#cb22-74" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-75"><a href="#cb22-75" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Plotly/Python toolkit</span></span>
<span id="cb22-76"><a href="#cb22-76" aria-hidden="true" tabindex="-1"></a><span class="fu">plotly_python</span><span class="kw">:</span></span>
<span id="cb22-77"><a href="#cb22-77" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: plotly-python.py</span></span>
<span id="cb22-78"><a href="#cb22-78" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span>
<span id="cb22-79"><a href="#cb22-79" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-80"><a href="#cb22-80" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-81"><a href="#cb22-81" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Plotly/R toolkit</span></span>
<span id="cb22-82"><a href="#cb22-82" aria-hidden="true" tabindex="-1"></a><span class="fu">plotly_r</span><span class="kw">:</span></span>
<span id="cb22-83"><a href="#cb22-83" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: plotly-r.r</span></span>
<span id="cb22-84"><a href="#cb22-84" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> Rscript</span></span>
<span id="cb22-85"><a href="#cb22-85" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-86"><a href="#cb22-86" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-87"><a href="#cb22-87" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Mathematica toolkit</span></span>
<span id="cb22-88"><a href="#cb22-88" aria-hidden="true" tabindex="-1"></a><span class="fu">mathplot</span><span class="kw">:</span></span>
<span id="cb22-89"><a href="#cb22-89" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: mathematica.m</span></span>
<span id="cb22-90"><a href="#cb22-90" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> math</span></span>
<span id="cb22-91"><a href="#cb22-91" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-92"><a href="#cb22-92" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-93"><a href="#cb22-93" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the GNU Octave toolkit</span></span>
<span id="cb22-94"><a href="#cb22-94" aria-hidden="true" tabindex="-1"></a><span class="fu">octaveplot</span><span class="kw">:</span></span>
<span id="cb22-95"><a href="#cb22-95" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: octave.m</span></span>
<span id="cb22-96"><a href="#cb22-96" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> octave</span></span>
<span id="cb22-97"><a href="#cb22-97" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-98"><a href="#cb22-98" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-99"><a href="#cb22-99" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the ggplot2 toolkit</span></span>
<span id="cb22-100"><a href="#cb22-100" aria-hidden="true" tabindex="-1"></a><span class="fu">ggplot2</span><span class="kw">:</span></span>
<span id="cb22-101"><a href="#cb22-101" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: ggplot2.r</span></span>
<span id="cb22-102"><a href="#cb22-102" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> Rscript</span></span>
<span id="cb22-103"><a href="#cb22-103" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-104"><a href="#cb22-104" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-105"><a href="#cb22-105" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the gnuplot toolkit</span></span>
<span id="cb22-106"><a href="#cb22-106" aria-hidden="true" tabindex="-1"></a><span class="fu">gnuplot</span><span class="kw">:</span></span>
<span id="cb22-107"><a href="#cb22-107" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: gnuplot.gp</span></span>
<span id="cb22-108"><a href="#cb22-108" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> gnuplot</span></span>
<span id="cb22-109"><a href="#cb22-109" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-110"><a href="#cb22-110" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-111"><a href="#cb22-111" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the graphviz toolkit</span></span>
<span id="cb22-112"><a href="#cb22-112" aria-hidden="true" tabindex="-1"></a><span class="fu">graphviz</span><span class="kw">:</span></span>
<span id="cb22-113"><a href="#cb22-113" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: graphviz.dot</span></span>
<span id="cb22-114"><a href="#cb22-114" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> dot</span></span>
<span id="cb22-115"><a href="#cb22-115" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-116"><a href="#cb22-116" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-117"><a href="#cb22-117" aria-hidden="true" tabindex="-1"></a><span class="fu">bokeh</span><span class="kw">:</span></span>
<span id="cb22-118"><a href="#cb22-118" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: bokeh.py</span></span>
<span id="cb22-119"><a href="#cb22-119" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span>
<span id="cb22-120"><a href="#cb22-120" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-121"><a href="#cb22-121" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-122"><a href="#cb22-122" aria-hidden="true" tabindex="-1"></a><span class="fu">plotsjl</span><span class="kw">:</span></span>
<span id="cb22-123"><a href="#cb22-123" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: plotsjl.jl</span></span>
<span id="cb22-124"><a href="#cb22-124" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> julia</span></span>
<span id="cb22-125"><a href="#cb22-125" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span></span>
<span id="cb22-126"><a href="#cb22-126" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-127"><a href="#cb22-127" aria-hidden="true" tabindex="-1"></a><span class="fu">plantuml</span><span class="kw">:</span></span>
<span id="cb22-128"><a href="#cb22-128" aria-hidden="true" tabindex="-1"></a><span class="co"> # preamble: plantuml.txt</span></span>
<span id="cb22-129"><a href="#cb22-129" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> java</span></span>
<span id="cb22-130"><a href="#cb22-130" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span><span class="at"> -jar plantuml.jar</span></span>
<span id="cb22-131"><a href="#cb22-131" aria-hidden="true" tabindex="-1"></a><span class="co"> # On Linux, if you have `plantuml.jar` as an executable, you can also</span></span>
<span id="cb22-132"><a href="#cb22-132" aria-hidden="true" tabindex="-1"></a><span class="co"> # use the following configuration instead:</span></span>
<span id="cb22-133"><a href="#cb22-133" aria-hidden="true" tabindex="-1"></a><span class="co"> # plantuml:</span></span>
<span id="cb22-134"><a href="#cb22-134" aria-hidden="true" tabindex="-1"></a><span class="co"> # executable: plantuml</span></span>
<span id="cb22-135"><a href="#cb22-135" aria-hidden="true" tabindex="-1"></a><span class="co"> # command_line_arguments:</span></span></code></pre></div>
<p>A file like the above sets the <strong>default</strong> values; you can still override them in documents directly.</p>
<p>The easiest way to specify configuration for <code>pandoc-plot</code> is to place a <code>.pandoc-plot.yml</code> file in the current working directory. You can also specify a configuration file in document metadata, under the <code>plot-configuration</code> key. For example, in Markdown:</p>
<div class="sourceCode" id="cb23"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a><span class="an">title:</span><span class="co"> My document</span></span>
<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a><span class="an">author:</span><span class="co"> John Doe</span></span>
<span id="cb23-4"><a href="#cb23-4" aria-hidden="true" tabindex="-1"></a><span class="an">plot-configuration:</span><span class="co"> /path/to/file.yml</span></span>
<span id="cb23-5"><a href="#cb23-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span></code></pre></div>
<p>or on the command line, using the pandoc <code>-M/--metadata</code> flag:</p>
<div class="sourceCode" id="cb24"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--filter</span> pandoc-plot <span class="at">-M</span> plot-configuration=/path/to/file.yml ...</span></code></pre></div>
<p>The hierarchy of configuration files is as follows:</p>
<ol type="1">
<li>A configuration file specified in the metadata under the <code>plot-configuration</code> key;</li>
<li>Otherwise, a file in the current working directory named <code>.pandoc-plot.yml</code>;</li>
<li>Finally, the default configuration is used.</li>
</ol>
<h4 id="executables">Executables</h4>
<p>The <code>executable</code> parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable.</p>
<p>Examples:</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="fu">matplotlib</span><span class="kw">:</span></span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python3</span></span></code></pre></div>
<div class="sourceCode" id="cb26"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="fu">matlabplot</span><span class="kw">:</span></span>
<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> </span><span class="st">"C:\Program Files\Matlab\R2019b</span><span class="sc">\b</span><span class="st">in\matlab.exe"</span></span></code></pre></div>
<h4 id="command-line-arguments">Command-line arguments</h4>
<p><em>New in version 1.0.2.0</em></p>
<p>The <code>command_line_arguments</code> parameter available for all toolkits provides a way to customize the way interpreters are run. For example, if you want to run the <code>matplotlib</code> toolkit with all warnings shown:</p>
<div class="sourceCode" id="cb27"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Matplotlib toolkit</span></span>
<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="fu">matplotlib</span><span class="kw">:</span></span>
<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span>
<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span><span class="at"> -Wa</span></span></code></pre></div>
<p>Or if you want <code>julia</code> to use more than one thread:</p>
<div class="sourceCode" id="cb28"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="co"># The possible parameters for the Matplotlib toolkit</span></span>
<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a><span class="fu">plotsjl</span><span class="kw">:</span></span>
<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> julia</span></span>
<span id="cb28-4"><a href="#cb28-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">command_line_arguments</span><span class="kw">:</span><span class="at"> --threads auto</span></span></code></pre></div>
<h4 id="toolkit-specific-options">Toolkit-specific options</h4>
<h5 id="matplotlib">Matplotlib</h5>
<ul>
<li><code>tight_bbox</code> is a boolean that determines whether to use <code>bbox_inches="tight"</code> or not when saving Matplotlib figures. For example, <code>tight_bbox: true</code>. See <a href="https://matplotlib.org/api/_as_gen/matplotlib.pyplot.savefig.html">here</a> for details.</li>
<li><code>transparent</code> 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, <code>transparent: true</code>.</li>
</ul>
<h4 id="logging">Logging</h4>
<p>If you are running <code>pandoc-plot</code> on a large document, you might want to turn on logging. You can do so via the configuration file as follows:</p>
<div class="sourceCode" id="cb29"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a><span class="fu">logging</span><span class="kw">:</span></span>
<span id="cb29-2"><a href="#cb29-2" aria-hidden="true" tabindex="-1"></a><span class="co"> # Possible verbosity values: debug, error, warning, info, silent</span></span>
<span id="cb29-3"><a href="#cb29-3" aria-hidden="true" tabindex="-1"></a><span class="co"> # debug level shows all messages</span></span>
<span id="cb29-4"><a href="#cb29-4" aria-hidden="true" tabindex="-1"></a><span class="co"> # error level shows all but debug messages, etc.</span></span>
<span id="cb29-5"><a href="#cb29-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">verbosity</span><span class="kw">:</span><span class="at"> info</span></span>
<span id="cb29-6"><a href="#cb29-6" aria-hidden="true" tabindex="-1"></a><span class="at"> </span></span>
<span id="cb29-7"><a href="#cb29-7" aria-hidden="true" tabindex="-1"></a><span class="co"> # OPTIONAL: log to file</span></span>
<span id="cb29-8"><a href="#cb29-8" aria-hidden="true" tabindex="-1"></a><span class="co"> # Remove line below to log to stderr</span></span>
<span id="cb29-9"><a href="#cb29-9" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">filepath</span><span class="kw">:</span><span class="at"> log.txt</span></span></code></pre></div>
<p>By default, <code>pandoc-plot</code> logs warnings and errors to the standard error stream only.</p>
<h4 id="strict-mode">Strict mode</h4>
<p><em>New in version 1.0.2.0</em></p>
<p>By default, <code>pandoc-plot</code> leaves code blocks unchanged if a figure fails to be rendered. This might be the case if a plotting toolkit is not installed, or if running the code to render a figure returns an error. In <strong>strict mode</strong>, <code>pandoc-plot</code> will immediately halt if it encounters a problem. You can activate strict mode via configuration:</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="fu">strict</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span></code></pre></div>
<p>Strict mode is ideal if you want to ensure that the figures are correctly rendered in the document.</p>
<h3 id="other-commands">Other commands</h3>
<h4 id="finding-installed-toolkits">Finding installed toolkits</h4>
<p>You can determine which toolkits are available on your current machine using the <code>pandoc-plot toolkits</code> command. Here is the full help text:</p>
<div class="sourceCode" id="cb31"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true" tabindex="-1"></a><span class="ex">Usage:</span> pandoc-plot.EXE toolkits [--config PATH]</span>
<span id="cb31-2"><a href="#cb31-2" aria-hidden="true" tabindex="-1"></a> <span class="ex">Show</span> information on toolkits and exit.</span>
<span id="cb31-3"><a href="#cb31-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb31-4"><a href="#cb31-4" aria-hidden="true" tabindex="-1"></a><span class="ex">Available</span> options:</span>
<span id="cb31-5"><a href="#cb31-5" aria-hidden="true" tabindex="-1"></a> <span class="ex">--config</span> PATH Path to optional configuration file.</span>
<span id="cb31-6"><a href="#cb31-6" aria-hidden="true" tabindex="-1"></a> <span class="ex">-h,--help</span> Show this help text</span></code></pre></div>
<h4 id="cleaning-output">Cleaning output</h4>
<p>Figures produced by <code>pandoc-plot</code> can be placed in a few different locations. You can set a default location in the <a href="#configuration">Configuration</a>, but you can also re-direct specific figures in other directories if you use the <code>directory=...</code> argument in code blocks. These figures will build up over time. You can use the <code>clean</code> command to scan documents and delete the associated <code>pandoc-plot</code> output files. For example, to delete the figures generated from the <code>input.md</code> file:</p>
<div class="sourceCode" id="cb32"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc-plot</span> clean input.md</span></code></pre></div>
<p>This sill remove all directories where a figure <em>could</em> have been placed. <strong>WARNING</strong>: all files will be removed.</p>
<p>Here is the full help text for the <code>clean</code> command:</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a><span class="ex">Usage:</span> pandoc-plot.EXE clean [--config PATH] FILE</span>
<span id="cb33-2"><a href="#cb33-2" aria-hidden="true" tabindex="-1"></a> <span class="ex">Clean</span> output directories where figures from FILE and log files might be</span>
<span id="cb33-3"><a href="#cb33-3" aria-hidden="true" tabindex="-1"></a> <span class="ex">stored.</span> WARNING: All files in those directories will be deleted.</span>
<span id="cb33-4"><a href="#cb33-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb33-5"><a href="#cb33-5" aria-hidden="true" tabindex="-1"></a><span class="ex">Available</span> options:</span>
<span id="cb33-6"><a href="#cb33-6" aria-hidden="true" tabindex="-1"></a> <span class="ex">--config</span> PATH Path to optional configuration file.</span>
<span id="cb33-7"><a href="#cb33-7" aria-hidden="true" tabindex="-1"></a> <span class="ex">-h,--help</span> Show this help text</span></code></pre></div>
<h4 id="configuration-template">Configuration template</h4>
<p>Because <code>pandoc-plot</code> supports a few toolkits, there are a lot of configuration options. Don’t start from scratch! The <code>write-example-config</code> command will create a file for you, which you can then modify:</p>
<div class="sourceCode" id="cb34"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc-plot</span> write-example-config</span></code></pre></div>
<p>You will need to re-name the file to <code>.pandoc-ploy.yml</code> to be able to use it, so don’t worry about overwriting your own configuration.</p>
<p>Here is the full help text for the <code>write-example-config</code> command:</p>
<div class="sourceCode" id="cb35"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a><span class="ex">Usage:</span> pandoc-plot.EXE write-example-config [--path FILE]</span>
<span id="cb35-2"><a href="#cb35-2" aria-hidden="true" tabindex="-1"></a> <span class="ex">Write</span> example configuration to a file and exit.</span>
<span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb35-4"><a href="#cb35-4" aria-hidden="true" tabindex="-1"></a><span class="ex">Available</span> options:</span>
<span id="cb35-5"><a href="#cb35-5" aria-hidden="true" tabindex="-1"></a> <span class="ex">--path</span> FILE Target location of the configuration file. Default is</span>
<span id="cb35-6"><a href="#cb35-6" aria-hidden="true" tabindex="-1"></a> <span class="st">".example-pandoc-plot.yml"</span></span>
<span id="cb35-7"><a href="#cb35-7" aria-hidden="true" tabindex="-1"></a> <span class="ex">-h,--help</span> Show this help text</span></code></pre></div>
<h3 id="as-a-haskell-library">As a Haskell library</h3>
<p>To include the functionality of <code>pandoc-plot</code> in a Haskell package, you can use the <code>make</code> function (for single blocks) or <code>plotFilter</code> function (for entire documents). <a href="https://hackage.haskell.org/package/pandoc-plot">Take a look at the documentation on Hackage</a>.</p>
<h4 id="usage-with-hakyll">Usage with Hakyll</h4>
<p>In case you want to use the filter with your own Hakyll setup, you can use a transform function that works on entire documents:</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode haskell"><code class="sourceCode haskell"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="dt">Text.Pandoc.Filter.Plot</span> (plotFilter, defaultConfiguration)</span>
<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="dt">Text.Pandoc.Definition</span> (<span class="dt">Pandoc</span>, <span class="dt">Format</span>(..)) <span class="co">-- from pandoc-types</span></span>
<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="dt">Hakyll</span></span>
<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb36-5"><a href="#cb36-5" aria-hidden="true" tabindex="-1"></a><span class="ot">plotFilter' ::</span> <span class="dt">Pandoc</span> <span class="ot">-></span> <span class="dt">IO</span> <span class="dt">Pandoc</span></span>
<span id="cb36-6"><a href="#cb36-6" aria-hidden="true" tabindex="-1"></a>plotFilter' <span class="ot">=</span> </span>
<span id="cb36-7"><a href="#cb36-7" aria-hidden="true" tabindex="-1"></a> <span class="co">-- Notify pandoc-plot that the final conversion will be to HTML</span></span>
<span id="cb36-8"><a href="#cb36-8" aria-hidden="true" tabindex="-1"></a> <span class="co">-- This helps give better error messages and adjust default values</span></span>
<span id="cb36-9"><a href="#cb36-9" aria-hidden="true" tabindex="-1"></a> plotFilter defaultConfiguration (<span class="dt">Just</span> <span class="op">$</span> <span class="dt">Format</span> <span class="st">"html5"</span>) </span>
<span id="cb36-10"><a href="#cb36-10" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb36-11"><a href="#cb36-11" aria-hidden="true" tabindex="-1"></a><span class="co">-- Unsafe compiler is required because of the interaction</span></span>
<span id="cb36-12"><a href="#cb36-12" aria-hidden="true" tabindex="-1"></a><span class="co">-- in IO (i.e. running an external script).</span></span>
<span id="cb36-13"><a href="#cb36-13" aria-hidden="true" tabindex="-1"></a><span class="ot">makePlotPandocCompiler ::</span> <span class="dt">Compiler</span> (<span class="dt">Item</span> <span class="dt">String</span>)</span>
<span id="cb36-14"><a href="#cb36-14" aria-hidden="true" tabindex="-1"></a>makePlotPandocCompiler <span class="ot">=</span> </span>
<span id="cb36-15"><a href="#cb36-15" aria-hidden="true" tabindex="-1"></a> pandocCompilerWithTransformM</span>
<span id="cb36-16"><a href="#cb36-16" aria-hidden="true" tabindex="-1"></a> defaultHakyllReaderOptions</span>
<span id="cb36-17"><a href="#cb36-17" aria-hidden="true" tabindex="-1"></a> defaultHakyllWriterOptions</span>
<span id="cb36-18"><a href="#cb36-18" aria-hidden="true" tabindex="-1"></a> (unsafeCompiler <span class="op">.</span> plotFilter')</span></code></pre></div>
<h2 id="warning">Warning</h2>
<p>Do not run this filter on unknown documents. There is nothing in <code>pandoc-plot</code> that can stop a script from performing <strong>evil actions</strong>.</p>
</body>
</html>