💾 Archived View for sdf.org › rsdoiel › blog › 2020 › 11 › 09 › index1.htm captured on 2023-03-20 at 19:21:45.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<h1 id="pandoc-partial-templates">Pandoc Partial Templates</h1>
<p>Most people know about <a href="https://pandoc.org/">Pandoc</a> from its fantastic ability to convert various markup formats from one to another. A little less obvious is Pandoc can be a template engine for rendering static websites allowing you full control over the rendered content.</p>
<p>The main Pandoc documentation of the template engine can be found in the <a href="https://pandoc.org/MANUAL.html#templates">User Guide</a>. The documentation is complete in terms of describing the template capabilities but lacks a tutorial for using as a replacement for more ambitious rendering systems like <a href="https://jekyllrb.com/">Jekyll</a> or <a href="https://gohugo.io/">Hugo</a>. Pandoc takes a vary direct approach and can be deceptively simple to implement.</p>
<h2 id="use-your-own-template">Use your own template</h2>
<p>First thing is in this tutorial is to use our own template with Pandoc when rendering a single webpage. You use the <code>--template</code> option to provide your a template name. I think of this as the page level template. This template, as I will show later, can then call other partial templates as needed.</p>
<p>Example, render the <a href="Pandoc-Partials.txt">Pandoc-Partials.txt</a> file using the template named <a href="index1.tmpl">index1.tmpl</a>:</p>
<pre class="shell"><code>
pandoc --from=markdown --to=html \
--template=index1.tmpl Pandoc-Partials.txt > index1.htm
</code></pre>
<p>This is a simple template page level template.</p>
<pre class="html-code"><code>
<!DOCTYPE html>
<html>
<head>
</head>
<body>
${body}
</body>
</html>
</code></pre>
<p>When we run our Pandoc command the file called <a href="Pandoc-Partials.txt">Pandoc-Partials.txt</a> is passed into the template as the “body” element where it says <code>${body}</code>. See this Pandoc <a href="https://pandoc.org/MANUAL.html#templates">User Guide</a> for the basics.</p>
<p>Example 1 rendered: <a href="index1.htm">index1.htm</a></p>
<h2 id="variables-and-metadata">Variables and metadata</h2>
<p>Pandoc’s documentation is good at describing the ways of referencing a variable or using the built-in template functions. Where do the variables get their values? The easiest way I’ve found is to set the variables values in a JSON metadata file. While Pandoc can also use the metadata described in YAML front matter Pandoc doesn’t support some of the other common front matter formats. If you’re using another format like JSON or TOML for front matter there are tools which can split the front matter from the rest of the markdown document. For this example I have created the metadata as JSON in a file called <a href="metadata.json">metadata.json</a>.</p>
<p>Example <a href="metadata.json">metadata.json</a>:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a> <span class="fu">{</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Pandoc Partial Examples"</span><span class="fu">,</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true"></a> <span class="dt">"nav"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true"></a> <span class="fu">{</span><span class="dt">"label"</span><span class="fu">:</span> <span class="st">"Pandoc-Partials"</span><span class="fu">,</span> <span class="dt">"href"</span><span class="fu">:</span> <span class="st">"Pandoc-Partials.html"</span> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a> <span class="fu">{</span><span class="dt">"label"</span><span class="fu">:</span> <span class="st">"Version 1"</span><span class="fu">,</span> <span class="dt">"href"</span><span class="fu">:</span> <span class="st">"index1.htm"</span> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a> <span class="fu">{</span><span class="dt">"label"</span><span class="fu">:</span> <span class="st">"Version 2"</span><span class="fu">,</span> <span class="dt">"href"</span><span class="fu">:</span> <span class="st">"index2.htm"</span> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb3-8"><a href="#cb3-8" aria-hidden="true"></a> <span class="fu">{</span><span class="dt">"label"</span><span class="fu">:</span> <span class="st">"Version 3"</span><span class="fu">,</span> <span class="dt">"href"</span><span class="fu">:</span> <span class="st">"index3.htm"</span> <span class="fu">}</span></span>
<span id="cb3-9"><a href="#cb3-9" aria-hidden="true"></a> <span class="ot">]</span></span>
<span id="cb3-10"><a href="#cb3-10" aria-hidden="true"></a> <span class="fu">}</span></span></code></pre></div>
<p>Let’s modify our initial template to include our simple navigation and title.</p>
<p>Example <a href="index2.tmpl">index2.tmpl</a>:</p>
<pre class="html-code"><code>
<!DOCTYPE html>
<html>
<head>
${if(title)}<title>${title}</title>${endif}
</head>
<body>
<nav>
${for(nav)}<a href="${it.href}">${it.label}</a>${sep}, ${endfor}
</nav>
<section>
${body}
</section>
</body>
</html>
</code></pre>
<p>We would include our navigation metadata with a Pandoc command like</p>
<pre class="shell"><code>
pandoc --from=markdown --to=html \
--template=index2.tmpl \
--metadata-file=metadata.json Pandoc-Partials.txt > index2.htm
</code></pre>
<p>When we render this we now should be able to view a web page with simple navigation driven by the JSON file as well as the body content contained in the Pandoc-Partials.txt file.</p>
<p>Example 2 rendered: <a href="index2.htm">index2.htm</a></p>
<h2 id="partials">Partials</h2>
<p>Sometimes you have more complex documents. Putting this all in one template can become tedious. Web designers use a term called “partials”. This usually means a template for a “part” of a page. In our initial example we can split our navigation into it’s own template.</p>
<h2 id="implementing-partials">Implementing partials</h2>
<p>Pandoc will look in the current directory for partials as well as in a sub directory called “templates” of the current direct. In this example I am going to include my partial template for navigation in the current directory along side my <a href="index3.tmpl">index3.tmpl</a>. My navigation template is called <a href="nav.tmpl">nav.tmpl</a>.</p>
<p>Here’s my partial template:</p>
<pre class="html-code"><code>
<nav>
${for(nav)}<a href="${it.href}">${it.label}</a>${sep}, ${endfor}
</nav>
</code></pre>
<p>Here’s my third iteration of our index template, <a href="index3.tmpl">index3.tmpl</a>.</p>
<pre class="html-code"><code>
<!DOCTYPE html>
<html>
<head>
${if(title)}<title>${title}</title>${endif}
</head>
<body>
${if(nav)}
${nav.tmpl()}
${endif}
<section>
${body}
</section>
</body>
</html>
</code></pre>
<p>Pandoc only requires you to reference the partial by using its base name. Many people will name their templates with the extension “.html”. I find this problematic as if you’re trying to list the templates in the directory you can not easily list them separately. I use the “.tmpl” extension to identify my templates. Since I have other documents that share the base name “nav” I explicit call my navigation partial using the full filename followed by the open and closed parenthesis. I have also chosen to wrap the template in an “if” condition. That way if I don’t want navigation on a page I skip defining it in my metadata file.</p>
<p>Inside the partial template we inherit the parent metadata object. You can use all the built-in Pandoc template functions and variables provided by Pandoc in your partial templates.</p>
<p>Putting it all together:</p>
<pre class="shell"><code>
pandoc --from=markdown --to=html \
--template=index3.tmpl \
--metadata-file=metadata.json Pandoc-Partials.txt > index3.htm
</code></pre>
<p>Example 3 rendered: <a href="index3.htm">index3.htm</a></p>
</body>
</html>