how to write an acm-styled conference paper using markdown/pandoc


I do not have much time for writing this post. Please insert here the obligatory rant against LaTeX syntax despite of its powerful functionality. Also insert here how Markdown syntax is fresh and readable.

Let’s go straight to the point. I don’t know about my peers, but if LaTeX lacked support from editors and plugins for achieving desirable features such as quick autocompletion (especially when citing material), I would likely switch to Word. That is why plugins like LaTeXing and platforms like Overleaf, ShareLaTeX, and Authorea were born, where automation drives innovation. Well, I want that for Markdown, too. I should mention that Authorea does support Markdown. However, I want to achieve the same, if not better, in offline mode.

A couple of days ago, I was whining about how Markdown (and its powerful cousin Pandoc) is lacking support from tools in the context of academic writing.

So I tried a little experiment. My goal was to be able to write an academic article using Markdown (from now on called Pandoc, as this is the variant of Markdown I am using). However, the produced PDF had to be ready for submission and follow any academic publishing style and guidelines. I chose to experiment with ACM. Here is the result:


Let’s see how I managed to achieve this. My approach should also work fine with other publishers such as IEEE, Springer, and friends. At the end of this post you will find an example project, too.


My experiment heavily borrows from Christopher Grainger’s excellent flow.


This is what you need installed on your machine.

Installing the required software is a matter of apt-get, brew install, pip, or whatever. Easy peasy.

The paper project structure

Create a folder that will host your paper project. Put inside the folder any LaTex-related file that the publisher provides. For the ACM specific case, you need:

The metadata

Papers have title, subtitle, authors, and abstract. Here are some good news and bad news. Good news: pandoc supports the metadata using YAML. Bad news: publishers hardcode some metadata into some custom LaTeX preamble commands. For example, ACM needs a series of commands such as numberofauthors, author, setcopyright, doi, etc.

All the supported metadata can be provided using YAML language. The non-supported metadata has to be provided as LaTeX command.

Create a file called metadata.yml with the following content:

title:  'It is actually possible to write ACM papers using Markdown'
subtitle: 'With pandoc and a very long bash command'
abstract: |
  This is the abstract.
header-includes: |
  conferenceinfo{PLDI '13}{June 16--19, 2013, Seattle, WA, USA}
  conferenceinfo{WOODSTOCK}{'97 El Paso, Texas USA}
  Ben Trovatotitlenote{Dr.~Trovato insisted his name be first.}\
         affaddr{Institute for Clarity in Documentation}\
         affaddr{1932 Wallamaloo Lane}\
         affaddr{Wallamaloo, New Zealand}\
         email{[email protected]}
  % 2nd. author
  G.K.M. Tobin\
         affaddr{Institute for Clarity in Documentation}\
         affaddr{P.O. Box 1212}\
         affaddr{Dublin, Ohio 43017-6221}\
         email{[email protected]}
  % 3rd. author
  alignauthor Lars Th{o}rv{"a}ld\
         affaddr{The Th{o}rv{"a}ld Group}\
         affaddr{1 Th{o}rv{"a}ld Circle}\
         affaddr{Hekla, Iceland}\
         email{[email protected]}

Anything under header-includes is included into the intermediary LaTeX file when typesetting to a PDF, in its preamble. Pity that header-includes is required as Pandoc does provide support for authors and affiliations.

The usepackage{booktabs} line is required for handling tables with a two-column layout using a pandoc filter.

The actual paper

Here is the easy and relaxing part. Just write the paper using Markdown/Pandoc. You are free to use a single file or split it into multiple files. Here is my example:

# Introduction
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris pulvinar quis lorem id aliquet. Nam vitae volutpat arcu. Curabitur aliquet, orci at blandit ultricies, velit sapien consequat odio, eu placerat nisl mi id lectus. Etiam semper sem vel ex porttitor, sed imperdiet urna malesuada. Praesent tempus blandit nulla a ultricies. Integer non commodo nisl. Nam nec fermentum metus, in porttitor diam. Mauris vulputate, tellus id scelerisque feugiat, est urna pharetra erat, sit amet scelerisque metus elit in mi. Nullam convallis porttitor lectus vel convallis.

Donec quis nunc sit amet dui scelerisque imperdiet. Cras gravida elit felis, quis aliquet dolor luctus at. Ut sit amet metus facilisis, finibus ligula eget, scelerisque ante. Nulla facilisi. Aliquam erat volutpat. Nam in sapien sapien. Nullam vehicula risus vitae odio suscipit, id dignissim turpis convallis [@bowman:reasoning].

![This is the caption label{my_figure}](fly.eps)

Non-English or Math|Frequency |Comments          
O                 |1 in 1,000|For Swedish names 
$pi$              |1 in 5    |Common in math    
$                 |4 in 5    |Used in business  

Table: (Table title) label{my_table}

See Table ref{my_table} for more.

See Figure ref{my_figure} for more.


Thank you pandoc.


This should be familiar. Citations are handled using the @ symbol followed by the BibTeX label. My example includes a picture, too. Please keep that in mind if you are copy-pasting my code from here.


This is easy, too. I typeset the project using the following command, which is for OS X but it can be easily adapted to GNU/Linux.

    -f markdown 
    --variable documentclass=sig-alternate-05-2015 
    -o sig-alternate-sample.pdf

Let’s break it down:

That is all. You will obtain a nice-looking PDF, which conforms to your publisher’s guidelines.

Tip: Markdown/Pandoc is not as powerful as LaTeX. Sometimes you need to revert to LaTeX. Again, that is easy. Just type the LaTeX commands in text. They are supported.

Clone my example project

You can git clone my example project or download it as a zip file to start writing.

Autocompletion of references and commands

See Christopher Grainger post for more. There you will learn about the AcademicMarkdown and Citer plugins for Sublime Text. They support the syntax and autocompletion. Citer in particular is cool as you link it to a bib file, then it will autocomplete citations starting with the @ symbol.

I do not use a commenting system anymore, but I would be glad to read your feedback. Feel free to contact me.