A Few Useful Pandoc Tricks

To say that Pandoc does a lot is a bit of an understatement. I’ve been using it for years and have barely taken advantage of a fraction of its capabilities. Every so often, though, I come across a trick that makes me appreciate Pandoc even more.

Here are a few of those tricks, which I’d like to share with you.

Add Metadata to a Document

Metadata, for those who might not know, is information about a document. That could be, for example, the title of an HTML file or the title, author, and keywords in the PDF version of a report.

If you’re working from a file formatted with Markdown, you can include metadata at the top of a file, like this:

% My Title
% My Name

Pandoc understands that the first line is always the title of your document, and that the second line is always your name. You can also add a date on the third line; I never do.

Here’s what that metadata becomes when you convert a file to ODT:

Metadata becomes the first heading in an ODT file

Adding a Table of Contents to a Document

If you’re working on a longer document, a table of contents is a must. A table of contents not only makes navigating a long document easier it also gives your readers an overview of what’s before them.

When converting to formats like HTML, PDF, or word processor formats like ODT or .docx, you can tell Pandoc to generate a table of contents using the --toc option, like this:

pandoc -t odt myReport.md --toc -o myReport.odt

Example of a simple table of contents generated with Pandoc

Out of the box, Pandoc adds the first three levels of headings to the table of contents — assuming, of course, you have that many (or more) levels of heading in your document. If you need to more or fewer headings in the table of contents, you can use the --toc-depth= option. So, to only include two levels of heading in your table of contents you’d use this command:

pandoc -t odt myReport.md --toc --toc-depth=2 -o myReport.odt

Suppressing an Image Caption

There are times when you need to include one or more images in what you’re writing. If you’re formatting your work with Markdown, you can add ALT text to the image markup, like this:

![A photo of my new puppy!](images/newPuppy.jpg)

When you convert that file to another format, Pandoc converts the ALT text into a caption that appears below the image. I don’t know about you, but I often don’t want that caption to display. It’s easy to suppress, though. Just add a backslash (\) at the end of the image tag like this:

![A photo of my new puppy!](images/newPuppy.jpg)\

Is that everything? Of course not! Tune in again soon for a few more useful Pandoc tricks.