How to use custom LaTeX document classes and Pandoc templates to customize documents without losing focus on writing

I love the way that documents look after typesetting them with LaTeX. I find that the formatting helps to keep my focus reading in a way that I have a difficult time doing when reading the same material in, for example, a Word document. I also really value being able to keep everything in plain text files that don't get corrupted or bloated (well, if I exclude my own writing).

LaTeX files can be a pain to set up, though. It's not as easy as clicking and adding, for example, a running header. It requires a bunch of commands that can be tricky to remember. And without the customization, the files end up looking like every other file typeset by LaTeX.

A larger problem, though, is that writing in LaTeX distracts me focus on the text because adding sections or emphases require a whole bunch of LaTeX commands.

Below I describe how I set up the workflow that I use to have both pretty documents that keep me focused on writing. The process involves using custom LaTeX document classes with the program Pandoc.

Using Custom LaTeX Document Classes

LaTex typesets documents based on what type of document you want to typeset. A book will have different elements than an article, which will differ from a letter. The type, or class, of document are defined in special document class files that LaTeX uses to typeset the text.

Although the standard article document class that comes with LaTeX is fine, I don't think that it looks very pretty. In addition, I tend to use a handful of custom commands. Using the article document class would mean re-defining those custom commands over-and-over again.

Instead of doing that, I have created a custom manuscript class that I use for my manuscripts. I will guide you through how you may use my custom manuscript class to make your own documents.

Setting up TeX path

A TeX distribution looks in a particular path to find your custom document classes. To find where your distribution looks, I can enter the following command in your Terminal:

kpsewhich -var-value=TEXMFHOME

On my Mac, the value returned by the command is ~/Library/texmf. I don't like having things scattered all over my computer, however. When I get a new machine, I will have to remember to download the documents from that folder in addition to my documents, code, etc. I want everything in one place.

To avoid the problem, I use symbolic links to prevent having to keep everything in one place. I keep all of my workflow files in a subdirectory called workflow that itself sits in a work subdirectory of my home directory (i.e., the directory returned when I type ~ in Terminal). If you want the same setup, you would simply use the commands:

cd ~
mkdir work
cd work 
mkdir workflow

Now, to create the symbolic link so that your TeX distribution will look at your custom workflow folder for files you would use the following commands:

cd ~
mkdir ~/work/workflow/texmf
ln -s ~/work/workflow/texmf ~/Library/texmf

The first line returns you to your home directory. The second line creates a subdirectory called texmf in my ~/work/workflow subdirectory. The third line creates a symbolic link (the -s stands for symbolic). When my TeX distribution looks for the contents of ~/Library/texmf, then it will see the contents of ~/work/workflow/texmf, including any changes that I make to the ~/work/workflow/texmf directory in the future.

You need one more step to get your TeX distribution to recognize LaTeX documents. TeX distributions expect files to be organized in a particular set of subdirectories. You will need to create two subdirectories in the ~/work/workflow/texmf directory so that your TeX distribution knows where to look:

cd ~/work/workflow/texmf
mkdir tex
mkdir tex/latex

Adding Custom Class Files

Now that you have your LaTeX directory set up, you can add custom classes to that directory. TeX distributions will look in subdirectories of the LaTeX directory, so you may either add files into the LaTeX directory or into separate subdirectories for different classes.

If you have Git installed, you can simply clone the repository to begin using my custom class:

cd ~/work/workflow/texmf/tex/latex
git clone https://github.com/mikebader/latex-baderart

You will see your terminal print some messages. After it's done, you will see a new subdirectory at ~/work/workflow/texmf/tex/latex/latex-baderart that will contain a baderart.cls file (and a README file, too).

If you don't have Git, you can just download the baderart.cls file at and save it into the ~/work/workflow/texmf/tex/latex directory.

Now you may begin using the baderart document class in LaTeX. A .tex file with the following contents should produce a minimal working example of a document typeset using the baderart class:

\documentclass{baderart}
\title{My Paper}
\author{Michael Bader}
\begin{document}

This is my paper.

\end{document}

Working with Pandoc

Using Pandoc has two advantages: it makes it easier to focus on writing and it also makes producing output much easier.

Pandoc improves my focus on writing easier because you can use Markdown syntax to write, which does not clutter my writing with a bunch of backslashes and curly braces. I can really focus on the text and getting my information across.

It also makes things easier because I can, with a single command, typeset the document.¹

Win-win!

Pandoc's Markdown interpreter allows authors to set variables in the header of the document. The most obvious variables are title, author, abstract, etc. By having a simple set of variables and values, Pandoc makes it straightforward to set all of the meta information about a document without worrying about a bunch of code or commands.

The document's variables can be set in a block before the document using something called YAML markup language. Really the only YAML aspect necessary to know is that the options need to start with a line of three dashes (---) and end with a line of either three dashes or three periods (...). A Markdown version of an article will look like this:

---
title: "My Article: Learning to Use LaTeX and Pandoc Together"
author: Michael Bader
---

This is my paper.

That's a whole lot cleaner than the LaTeX document above!

For those unfamiliar with Pandoc, it works by taking a document written in one format, say Markdown and converts it to another format, say LaTeX. It can even write and typeset binary files like PDFs and Microsoft Word documents. Assuming your file is named myarticle.md (the .md stands for "Markdown"), you may typeset this document into a PDF with the following command (the -o switch tells Pandoc to output the file after the switch--be careful, it will overwrite the file without asking):

pandoc myarticle.md -o myarticle.pdf

Pandoc Templates

The cost of this win-win, however, is a little bit of initial set up if you want to customize your output.

The document will be typeset using the article documentclass and a whole bunch of defaults. In fact, if you want to save the intermediary LaTeX document that Pandoc created to typeset into the PDF, you can use the following command (the -s switch tells Pandoc to create a stand-alone document):

pandoc myarticle.md -o myarticle.tex -s

You will notice that the file contains a whole lot more information than the simple document that we wrote above. That's because Pandoc uses a template to produce a document. The template takes all of the options in the YAML block and inserts them where they should go in the LaTeX document. You can view the standard LaTeX template Pandoc uses with the following the command:

pandoc -D latex

In the output, you will notice a bunch of words enclosed in dollar signs. For example, you will the following lines in the output:

$if(title)$
\title{$title$$if(thanks)$\thanks{$thanks$}$endif$}
$endif$

Pandoc uses the dollar signs to indicate variables created in the YAML block of the Markdown file. The first line tells Pandoc to move to the next line if the variable title is present in the Markdown file. The second line tells Pandoc to write the value of the title variable into the LaTeX document (it also includes a command to write out an acknowledgment footnote if the thanksvariable is present). After running our Markdown document through the template, Pandoc will create line in the LaTeX file that reads \title{My Article: Learning to Use LaTeX and Pandoc Together: Learning to Use LaTeX and Pandoc Together}. You can, in fact, find that text if you search the myarticle.tex file that you created above.

The awesome thing about Pandoc templates is that they allow you to define arbitrary variables in Markdown documents and then insert the values of those variables into the converted document.

I created a Pandoc template to use my custom baderart LaTeX document class, and that also allows me to use some of the custom features that I wrote into that baderart document class. For example, I allow a short title to be declared in the preamble of a LaTeX document with the command \shorttitle{} that will typeset the value of the command in the header of the manuscript.

If you look at the code of my custom Pandoc template, you will see the following lines:

$if(shorttitle)$
\shorttitle{$shorttitle$}
$else$
\shorttitle{\@title}
$endif$

In the Pandoc template that I created, I can define the shorttitle variable and Pandoc will insert that value of that variable into the \shorttitle{} command (and insert the full title if the shorttitle variable is not defined).

In my Markdown file, I can now write the following and have only "My Article" show up in the header on pages of the manuscript:

---
title: My Article: Learning to Use LaTeX and Pandoc Together
shorttitle: My Article
author: Michael Bader
---

This is my paper.

To use the new template, I will use the --template flag on the pandoc command followed by the file I want Pandoc to use. I download all of my pandoc filters into the directory ~/work/workflow/pandoc. Therefore, I would enter the command

pandoc myarticle.md -o myarticle.pdf --template ~/work/workflow/pandoc/manuscript.latex

and Pandoc will use my custom manuscript.latex template to typeset the file using my custom baderart document class.

Now I can just focus on the text of my document, writing more than "This is my paper." I don't need to worry about LaTeX codes or anything else. Just the text!

Summary

I like having pretty manuscripts but I also like being able to write without distractions. A custom LaTeX document class allows me to define extra features that I use frequently, features like notes for different publication statuses, extra LaTeX commands that I use, and defining a short title. And a Pandoc template allows me to use those features without needing to write a bunch of extraneous LaTeX code. As a result, I can focus on writing the best articles that I can without a bunch of workflow issues getting in the way.

I hope this helps you make pretty documents while focusing on your own writing!