Making Markdown

I’m writing more and more of my papers in Markdown and use pandoc to produce PDF files for submission. The settings and customizations necessary to produce a PDF document conforming with specifications can make the build process quite complex. Consequently I’ve been using makefiles to run pandoc with the right settings for a specific publication and to keep track of the dependencies, such as bibliographies, header includes, custom template, etc.

You can easily invoke make with M-x compile to “build” the document (I’ve bound it to the F5 key).¹ However, as I started to use it more often, two things started to irritate me:

1. The fact that running compile opens a buffer that I had to manually “bury” (i.e., close) afterwards to restore my window layout.
2. The fact that I needed to manually reload the PDF.

The first issue can be easily fixed by installing the bury-successful-compilation package, which does exactly what it says: if the compilation is successful, the *compilation* buffer is automatically closed; otherwise it stays open, so that you can track down the problem. Once the compilation succeeds, the previous window configuration is automatically restored.

The second issue was particularly annoying because I’ve gotten used to the PDF view being automatically updated after compilation when writing LaTeX with AUCTeX and using PDF Tools to display the PDF in Emacs. This doesn’t rely on monitoring files—which is prone to refresh the display too early or too late—but AUCTeX explicitly tells PDF Tools to “revert” (i.e., reload) the buffer once the compilation has finished.

When we use compile, we can use the same approach by adding a function to the compilation-finish-functions hook, which is run after compilation has finished. In fact, we can even use AUCTeX’s TeX-revert-document-buffer function. The main complication is to find out just which buffer to revert; as the hook is run inside the *compilation* buffer, not the Markdown buffer, we can’t just look at the buffer file name.

I’m using GNU make’s pattern rules, so saying make paper.pdf will create paper.pdf from paper.md. Here’s an example of such a rule:

TEMPLATE=pandoc/lni-pandoc-template.tex
BIB=${HOME}/lib/tex/bibtex/bib/all.bib

%.pdf: %.md ${BIB} pandoc/*.tex
    pandoc -o $@ --template=${TEMPLATE} \
      --include-in-header=pandoc/custom-latex.tex \
      --number-sections --bibliography=${BIB} \
      --filter pandoc-crossref --biblatex \
      --pdf-engine=latexmk \
      --pdf-engine-opt=-xelatex \
      --pdf-engine-opt=-recorder \
      --pdf-engine-opt=--synctex=1 \
      --pdf-engine-opt=-bibtex-cond
      --pdf-engine-opt=-outdir=.latexmk $<

The PDF file name is thus the last argument to make, and it ends in .pdf, so we can easily extract it from the compilation-arguments variable.

While I was at it, I also added some code to automatically preset compile-command for Markdown buffers, and I defined C-c C-v to open the PDF in a separate frame, which is what I normally want.

I’ve made a short video to demonstrate it:

If this sounds useful, feel free to check out my markdown-mode customizations for details.

---

1. Yes, there’s also pandoc-mode, but I don’t think it really matches my usage of pandoc, while adding a lot of complexity.↩︎

---

---