I was recently introduced to a remarkable tool called Pandoc. If you haven't heard of this yet, it can greatly expand your documentation formats and abilities. It essentially is a tool to convert markup from one format to another, and it supports hundreds of combinations of formats. A (large) diagram is available here that displays all of the different available format conversions.

In this post, I'd like to walk through installing Pandoc and compiling a document.

Installing Pandoc

To install Pandoc, begin by visiting the Downloads page on the project's homepage. You'll need to install the version of Pandoc that is compatible with your operating system, as well as a compatible version of LaTeX.

After the installation, you should be able to execute the following command in your terminal:

$ pandoc --version

If Pandoc is properly installed, then you'll receive a message with the version that you've installed, along with some other useful information.

Starting a Document

Pandoc has support for many different formats, but I've found writing documents using Markdown and converting them to the format you require makes life quite easy. Open up your favorite text editor and add the following to it.

% Getting Started with Pandoc
% Oct. 3, 2013

This is a test of [Pandoc](http://johnmacfarlane.net/pandoc/).

## Second level header

* This is a bulleted list.
  - item a
  - item b

### Third level header

> _Wow, this is awesome!_

Pandoc is the __greatest__.

Save the file as pandoc_test.md in the directory of your choice, and fire up the terminal. cd to the folder containing your markdown file and issue the following command:

$ pandoc pandoc_test.md -o pandoc_test.pdf

This will generate a PDF of the previously written pandoc_test.md markdown file in the same directory. This is the general output for any format that you'd like to convert to, such as .docx, .pdf, .epub, .md, .html, and .tex to name a few.

Useful Options

Pandoc has a ton of options, but here are a few that I've found useful:

• --toc: Generates a table of contents at the beginning of the document
• --latex-engine: Specifies the LaTeX engine of your choice such as xelatex, lualatex, or pdflatex (default).
• --variable mainfont=: Specifies the main font to use. Requires xelatex or lualatex engine.
• --variable geometry:margin=1in: Manually set the margin widths.

Click here to check out this post compiled to a PDF using Pandoc and the corresponding markdown.