A Few More Useful Pandoc Tricks

by: Scott Nesbitt | 13 May 2021

A few articles ago, I shared some simple but what I think are useful Pandoc tricks. If you've used Pandoc, then you know what a multi-purpose utility it is. Which means there are any number of tricks that you can perform with it.

This time 'round, I'd like to share three more useful Pandoc tricks.

Using a Custom Template

It's easy to quickly go from Markdown (or any other markup language that Pandoc supports) to a word processor file using Pandoc. The results, while serviceable, are kind of bland. You can add a bit more visual flair to converted documents using a custom template.

To get started, you'll need to create a file called custom-reference.odt (or custom-reference.odt if you use Microsoft Word), which contains a set of styles that Pandoc uses in a conversion.

Do that by running this command:

pandoc --print-default-data-file reference.odt > custom-reference.odt

Next, open the file custom-reference.odt in a word processor and:

Modify the styles, like headings, body text, and list.
Change the page size.
Add headers and footers.

To use the custom-reference.odt file, run this command:

pandoc -t odt filename.md -o filename.odt --custom-reference [path-to]/custom-reference.odt

You can also drop the file into the .pandoc folder in your personal directory to have Pandoc use the file without you specify it in the command.

Adding Metadata to a Document From a File

In my previous look at some Pandoc tricks, I shared how to add some basic information about a document to the header of a Pandoc file.

Another way to do that is to use file containing your metadata. I usually do this with my ebooks, and I know people who do the same with their books, reports, and even articles that they're collaborating on.

The file containing the metadata is formatted in YAML, which is short for Yet Another Markup Language. Don't worry about the technical details of YAML. Those aren't important. What is important is what's in the file and how it's formatted.

The YAML file can contain this information:

A document's title and subtitle.
The names of one or more authors.
Some keywords.
The publisher.
The license under which you're publishing the document.

And more. What I've listed above is the metadata that I use.

As for how the file is formatted, here's the contents of the metadata file that I use with my books:

---
title:
- type: main
  text: Your Book's Title
- type: subtitle
  text: Your Book's Subtitle
creator:
- role: author
  text: Your Name
publisher:  Me
rights: © 202x Your Name, License (for example, CC BY-NC)
...

To use a metadata file in a conversion, run a command like this one:

pandoc myDocument.md --metadata-file=metadata.yaml -o myDocument.pdf

Creating Internal Links

By internal link I mean a link from one section of your document to another section. You stay on the page rather than jumping out to another page or website.

You can use internal links:

As part of a table of contents for a longer document.
To refer back to something you've written in the document.

To create the link, surround the word or words that will act as the link with a pair of square brackets, followed by parentheses. Between the parentheses, add a hashtag followed by the name of the link's destination.

Here's what it looks like:

[Inserting a Bookmark](#bookmark)

Give the destination a meaningful name — for example, one of the main words in the heading the link jumps to.

Next, go to the heading that you want the link to jump to. At the end of the heading, add a space. Then, add the name of the destination surrounded by curly braces:

{#bookmark}

Do that for every link that you want to create.

As with the last batch of tricks, this isn't even close to being everything that you can do with Pandoc. In fact, another batch of tricks might be coming your way before you know it.