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 | 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]
pandocsupports several markdown variants including CommonMark and GitHub Flavored Markdown, and other lightweight markup languages. - [2] Markdown support for
sphinxrequires therecommonmarkpackage. - [3] To use BibTeX citations in
sphinxdocumentation requires thesphinxcontrib-bibtexpackage. - [4]
knitrcan be considered as a preprocessor for R Markdown. Once it processes R Markdown into Markdown, the rest of the rendering job is handled bypandoc. - [5] From the same developer of
knitr,bookdownoffers 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.jlrequirespandocfor 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).
Additional notes
- My focus is on generating HTML and PDF output. However, many of these tools
also support other e-book formats like
epubandmobi. - Some tools listed here are better suited for building software
documentation than for writing a paper or book, for example,
doxygenandsphinx. However, there are indeed technical books written withsphinx, for example, Theoretical Physics Reference and Music for Geeks and Nerds. - Jekyll is useful for publishing your e-book as a website hosted on GitHub Pages.
- 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.
- 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.
