A comparison of some markdown publishing systems

Markdown is the new LaTeX for technical and academic writing. Although LaTeX is still the gold standard, if your writing does not involve a whole lot of theorems and proofs, drawing diagrams in TikZ and PGF, or some heavy tweaking of the page styles, Markdown may suffice for your use cases. A lightly marked text format like Markdown helps the writer concentrate on the contents rather than the styles.

In the past few years, I have gradually replaced some of my writing tasks in LaTeX with automated generation of LaTeX and PDF from Markdown by pandoc. The workflow is simple and quite reliable. You need to spend time making a nice LaTeX template first. Once you have it, you can keep using the same template until you are bored with it.

Out of curiosity, I searched over the landscape of tools for writing papers, e-books, and documentation in Markdown or other similar text formats. My requirement is rather simple: a document generator that takes lightweight markup text formats as the input and outputs HTML, LaTeX, and PDF. BibTeX citations and bibliographies would be a bonus.

My conclusion is that pandoc is the best generic tool for writing papers and technical books. But it is not the only one out there. Which tool is the best depends on the requirements of the task. For example, if you are writing a tutorial for a programming language or a package, you may be interested in writing in a literate programming manner, which may be best done in the Markdown variant of that language (e.g., R Markdown for R), or in the versatile Jupyter Notebook. And once you have rendered your book in HTML, you may use Jekyll to publish it on GitHub Pages. The moral is to use the right tool for the right task.

Below is a list of some popular tools that render Markdown or other text-based formats in HTML, LaTeX, and PDF. It is by no means exhaustive.

Name Input HTML LaTeX PDF BibTeX citation Literate programming
pandoc Multiple markup formats[1] Yes Yes Yes Yes No
sphinx reStructuredText, Markdown[2] Yes Yes Yes Yes[3] No
doxygen Markdown, self-documented source code Yes Yes Yes Yes No
knitr[4] R Markdown Yes Yes Yes Yes R, Python, and SQL
bookdown[5] R Markdown Yes Yes Yes Yes R, C/C++, Python, and SQL
jekyll[6] Markdown, Liquid, HTML Yes No No No No
scribble Racket, scrbl files Yes Yes Yes Yes Racket
pollen Pollen and Pollen Markdown Yes Yes Yes Yes Racket
Weave.jl[7] Julia Markdown Yes Yes Yes Yes Julia
Jupyter Notebook Jupyter Notebook ipynb files Yes Yes Yes Yes Languages with a Jupyter kernel[8]

Footnotes

Additional notes

  1. My focus is on generating HTML and PDF output. However, many of these tools also support other e-book formats like epub and mobi.
  2. Some tools listed here are better suited for building software documentation than for writing a paper or book, for example, doxygen and sphinx. However, there are indeed technical books written with sphinx, for example, Theoretical Physics Reference and Music for Geeks and Nerds.
  3. Jekyll is useful for publishing your e-book as a website hosted on GitHub Pages.
  4. Literate programming seems to be most popular in dynamic languages like R, Python, and Julia. But theoretically, you can do it in any language that is supported by Jupyter Notebook.
  5. Racket has good-looking documentation (in my opinion, better than Python’s). However, the documentation tools (Scribble and Pollen) require basic understanding of Racket syntax. I’m not well versed in any Lisp dialect and therefore did not look at them in detail. Maybe I’ll revisit them in a few years.