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.
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
.tex to name a few.
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
--variable mainfont=: Specifies the main font to use. Requires
--variable geometry:margin=1in: Manually set the margin widths.