Rekka Bellum

Contents

What is Pandoc?

Pandoc is a terminal utility that converts files from one markup format into another. You can convert an HTML page to Markdown, Markdown to PDF, Markdown to EPUB etc. It's a useful tool to create articles, scientific papers, and books.

When generating PDFs, Pandoc's use of LaTeX (a document preparation system) encourages authors not to worry too much about the appearance of their documents but to concentrate on getting the right content.

This is a list of notes I've compiled when came time to learn how to generate PDFs with Pandoc. This guide was made and tested on the Elementary Linux distribution. It is for people with limited command-line experience.

Pandoc Markdown

Make sure that the file you want turned into a PDF has a .txt or .md (if you want syntax highlighting) extension, and take note of the path to your project file, as you'll need that to generate your PDF later. The next step is to add Pandoc Markdown syntax to the text.

Pandoc Markdown is an extended and slightly revised version of John Gruber’s Markdown syntax. Markdown is a simple, and easy-to-use markup language to format plain-text content. This language is used to annotate a document in a way that is syntactically distinguishable from the text.

For example, to make text bold, add two asterisks on each side of the word:

In January 2016, we bought our first sailboat, a **Yamaha 33**.

Hash symbols preceding a word or phrase make a heading. Be sure to add a space between the hash and the first word:

## Introduction

One hash would make the title bigger, three would make the heading smaller, four even smaller, five even smaller etc.

Once your text file has Markdown syntax, it is time to install Pandoc.

Installing Pandoc on Linux

To install pandoc on Linux, you can generally use your package manager, or download the latest version from the website directly. You'll want to get pandoc-2.11.2-linux-amd64.tar.gz. When you've downloaded it, unzip the file, and move the folder (named pandoc-x.xx.x) to your Applications folder.

You've got Pandoc, but it's not usable yet. You've got to use the terminal to 'unpack' the files. Write the path to Pandoc package, followed by the sudo command:

cd ~/Applications
sudo dpkg -i ./pandoc-2.11.1

You'll be asked for your password. Enter your password, and press enter to install Pandoc.

You should have the latest version of Pandoc installed, to verify the version, type the following in the command line:

pandoc --version

You'll see the name of the version on top, which in this case, is version 2.11.1.

pandoc 2.11.2
Compiled with pandoc-types 1.22, texmath 0.12.0.3, skylighting 0.10.0.3,
citeproc 0.2, ipynb 0.1.0.1
User data directory: /home/user/.local/share/pandoc or /home/user/.pandoc
Copyright (C) 2006-2020 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

You now have Pandoc installed on your computer.

Installing Tex Live

For converting text files (written in Pandoc Markdown) to PDF, Pandoc makes use of LaTeX and XeTeX as the rendering engine. This is what will make your documents beautiful. Tex Live is a package specific to Linux, enter the following command to install it:

sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-generic-recommended

From Markdown to pdf

To generate a PDF from your .md or .txt file, locate your project file using the terminal. Use cd to navigate to your project folder. The example below is if you'd saved your project file to Documents, under a folder named "myproject". Remember, caps matter when using cd:

cd Documents/myproject/

Enter the following command, replacing "filename" with the name of your project file, and "filename_export" with for the final exported PDF file:

pandoc filename.txt --pdf-engine=xelatex -o filename_export.pdf

In that same folder where you had your .txt file saved, you'll find your Pandoc-generated PDF!

Using Pandoc Markdown Extensions

In Pandoc, you can use Extensions (see below) to specify the output of your PDF more granularly, say if you want to change the paper size, add tables or footnotes etc.

Changing papersize

By default, the Pandoc PDF format is a4. If you want to change it, you'll have to add the following when generating the PDF in the command line:

--variable=geometry:a5paper

Appended with the rest, to generate the PDF from a Markdown file, it'll look like this:

pandoc --variable=geometry:a5paper filename.txt --pdf-engine=xelatex -o filename_export.pdf

If you're file is a .md, change the extension of your project file.

Adding extensions

If you want add tables, you'll have to add an Extension. Extensions are specified in the command line when generating a PDF. In the example below, after -- from markdown, I've added a + followed by the extension simple tables. If the extension name has two words, adding an underscore between them is necessary.

--from markdown+simple_tables

You can add more extensions, adding a + inbetween each one. In the example below, I've added both simple tables and citations.

--from markdown+simple_tables+citations

Below is an example of a terminal command for a PDF generated from a .txt file, in a5 format, with the simple tables extension.

pandoc --variable=geometry:a5paper filename.txt --pdf-engine=xelatex --from markdown+simple_tables -o filename_export.pdf