Using Pandoc for your documents

I got you, my first post was not about how I made my blog. It's the second one that was!

One of my favourite tools is probably Pandoc. It allows you to write documents in a multitude of markup languages and output them in many different formats. It has a dauntingly long manual listing a lot of options, but I mainly like using it with its Markdown extensions:

pandoc input.md > output.html

There are ~40 input and ~60 output formats, and ~70 extensions supported by Pandoc, so you could also, for example:

Output PDFs with -o file.pdf
Write manual pages with -t man, view them with pandoc -t man | man -l -
Write a Literate Haskell document in reStructuredText with -f rst+lhs

The next sections will talk about putting together blog-ish (really I use it for everything) HTML pages, ~~(and this is directed at some people I want to convert)~~ but if I've convinced you to install it, do poke around the user's guide!

Out of the box you get a lot of Markdown extensions, let's see some of them!

Hello, Pandoc!

## Hello, Pandoc!

You can use *italics* and **bolds**, but also superscripts^2^ and subscripts~i~. You can use [named links] like that or like [this][named links]. You can use footnote references[^1] or write them inline.^[Like that!]

::: note
You can create `<div>`{.html}s like this. Oh, and add attributes like that.

::: warning
You have been warned. They can be nested.
:::

:::

[named links]: /this-is-a-really-long-path-with-fifty-four-characters

[^1]: This shows up at the bottom of the page!

The above looks like this:

You can use italics and bolds, but also superscripts² and subscripts_i. You can use named links like that or like this. You can use footnote references¹ or write them inline.²

You can create <div>s like this. Oh, and add attributes like that.

You have been warned. They can be nested.

Page metadata

Adding metadata to markdown files can be done with YAML blocks:

---
title: My awesome post
subtitle: it's real good
author: You
date: Apr. 01, 1970
---

These fit in the document's template. If you don't want to bother with one, --standalone includes a default for all formats, and there are several more variables for each format.

If you're writing a man(1) page, the title should be in the name(section) format. There's also a shorter syntax for setting a title, author and date:

% rini(1)
% Rini Curry
% April 1970

Template crash course

You can use --template to specify a file with the skeleton of the document. Templates are interpolated with $variables$ . Here's a really simple one:

<!doctype html>
<html lang="en">
  <body>
    <header>
      <h1>$title$</h1>
    </header>

    <main>
      $body$
    </main>
  </body>
</html>

Sometimes it's nice to have some optional metadata:

<header>
  <h1>$title$</h1>
  $if(subtitle)$
  <p>$subtitle$</p>
  $endif$
</header>

Or, maybe lots of metadata:

$for(author)$$author$$sep$, $endfor$

$sep$ is a nice directive that only adds the text following it if its between two elements. Also, $for$ doesn't need to always iterate through an array- if it's one element, it'll iterate once, if it's empty, it won't iterate. Quite handy!

Putting it together

Now that we have our own template, making a blog is pretty easy. We can create a configuration file to avoid passing lots of options in the CLI, like so:

template: template.html # use our template
reader: markdown-smart # disable “smart” quotes
wrap: none # disable wrapping input to 72 columns, it's $curYear!

And run pandoc for each markdown file in a folder. The following is basically (but not quite, I have a little fancier thing to avoid updating too many files) what I have on my website:

for $post in posts/*; do
  pandoc --defaults pandoc.yaml $post -o public/posts/$(basename $post .md).html
done

This shows up at the bottom of the page!↩︎
Like that!↩︎