Markdown + pandoc + Make = 💚

The formats

• The PDF file I build has a wide outer margin for notes and is useful if my editor prefers to print the article and hand me a marked-up version. ¹
• The HTML file contains the content I eventually put online onto our website, because a copy-and-paste from a DOCX file inevitably adds a lot of unnecessary code to the HTML. The format is also particularly good if the reader of the draft is on a phone, as the responsive layout is much better for reading than PDF/DOCX.
• The DOCX output is because nearly all my colleagues prefer to use it – rather than the ODF standard – for writing, but also for sending comments and edits with changes tracked. Further, the tool that our in-house translation team uses requires DOCX files as input.

My workflow

I author the article in a Markdown file (here YYYYMMDD_FILENAME.md), with each sentence residing on a new line. At the top of this file, you need to add some YAML “frontmatter”. Most of the YAML below is for the PDF output; you can get rid of some of it (like urlcolor, geometry, documentclass etc.) if you are not interested in generating PDFs. For your PDF output, you can optionally insert margin notes using \(\LaTeX\) – just add \marginpar{Lorem ipsum} in the appropriate place in your Markdown file and it will insert the text “Lorem ipsum” in the outer margin as defined by geometry:

---
title: "This is the title of my article"
subtitle: "This is the subtitle (or strap) of the article"
author: "Byline: Achintya Rao"
date: "Scheduled for 1 October 2020"
# I don’t like having to manually change the language for DOCX files
lang: en-GB 
urlcolor: blue
# A wide margin for the PDF allowing you to insert margin notes using:
# \marginpar{Lorem ipsum}
geometry: "twoside, top=3cm, bottom=3cm, inner=3cm, outer=6.5cm, marginparwidth=3cm, marginparsep=0.5cm"
documentclass: article
# Use the exact name of the font you wish to have the PDF formatted in.
# In my case, I’m using Alegreya (the same font as the main text in this blog): 
# https://www.huertatipografica.com/en/fonts/alegreya-ht-pro
mainfont: "Alegreya"
linestretch: 1.2
# You can also include LaTeX packages using `header-includes`.
# The package here disables hyphenation of long words in the PDF output.
header-includes:
- \usepackage[none]{hyphenat}
---

Initially, I used to pop open a terminal and invoke the appropriate pandoc command every time I saved the Markdown file:

# PDF
$ pandoc -V papersize:a4 --pdf-engine xelatex -o YYYYMMDD_FILENAME.pdf YYYYMMDD_FILENAME.md

# HTML (with the CSS file in ~/Documents/CSS/pandoc.css)
$ pandoc -s --css ~/Documents/CSS/pandoc.css --self-contained -o YYYYMMDD_FILENAME.html YYYYMMDD_FILENAME.md

# DOCX
$ pandoc -o YYYYMMDD_FILENAME.docx YYYYMMDD_FILENAME.md

This quickly got tiresome since I had to remember all the pandoc spells commands for every new article and change the name of the input and output files.

# Make sure you change the filename from YYYYMMDD_FILENAME.md to something meaningful.
SOURCE := YYYYMMDD_FILENAME.md

HTML := $(patsubst %.md,%.html, $(SOURCE))
PDF := $(patsubst %.md,%.pdf, $(SOURCE))
DOCX := $(patsubst %.md,%.docx, $(SOURCE))

STYLE := ~/Documents/CSS/pandoc.css
# Source: https://gist.github.com/killercup/5917178
# Make sure you save this in the same directory as shown or change the path.

.PHONY : all
all : $(HTML) $(PDF) $(DOCX)

%.html : %.md $(STYLE)
    @echo --- Generating HTML ---
    @pandoc -s --css $(STYLE) --self-contained -o $@ $<

# You will need to have the appropriate pdf-engine installed.
%.pdf : %.md
    @echo --- Generating PDF ---
    @pandoc -V papersize:a4 --pdf-engine xelatex -o $@ $<

%.docx : %.md
    @echo --- Generating DOCX ---
    @pandoc -o $@ $<

.PHONY : clean
clean :
    @echo --- Deleting generated files ---
    @-rm $(HTML) $(PDF) $(DOCX)

$ tree
├── YYYYMMDD_FILENAME.md
└── makefile

$ make
--- Generating HTML ---
--- Generating PDF ---
--- Generating DOCX ---

$ tree
├── YYYYMMDD_FILENAME.docx
├── YYYYMMDD_FILENAME.html
├── YYYYMMDD_FILENAME.md
├── YYYYMMDD_FILENAME.pdf
└── makefile

Rebuilding on save

Happily, I came across the entr program recently, which I use to automatically re-run the make command every time I save the source file: ³

$ ls *.md | entr make

Here is my workflow in action: ⁴

Emacs with three panes. The top-left pane has the raw Markdown while the top-right pane has the generated PDF. The bottom pane has a terminal emulator running the make command.

I hope you like it! Please let me know on Scholar.Social or on Twitter if you have any suggestions to improve the code here. You can also leave comments on this page itself (thanks to hypothes.is) by selecting any text and annotating it.