# 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

• [1] pandoc supports several markdown variants including CommonMark and GitHub Flavored Markdown, and other lightweight markup languages.
• [2] Markdown support for sphinx requires the recommonmark package.
• [3] To use BibTeX citations in sphinx documentation requires the sphinxcontrib-bibtex package.
• [4] knitr can be considered as a preprocessor for R Markdown. Once it processes R Markdown into Markdown, the rest of the rendering job is handled by pandoc.
• [5] From the same developer of knitr, bookdown offers more advanced features for writing technical and academic books.
• [6] To be honest this comparison is not fair for Jekyll because it is used as a static site generator. It is best suited for serving your digital book as a website. There are great examples of online textbooks served with Jekyll.
• [7] Like R markdown, Weave.jl requires pandoc for rendering Markdown.
• [8] Languages with officially supported Jupyter kernels include Python, R, Julia, and C++. There are more than 100 different language kernels supported through community efforts (see Jupyter kernels).

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.