By Roy H. Goodman
Figure 1. In a LaTeX document, it becomes difficult for users to see the content amid all of the markup text.
Much of an applied mathematician’s working life is spent writing. Primary tasks of course involve drafting articles and grant proposals, and LaTeX remains the most important tool for this purpose. However, Markdown is now a better option for smaller writing projects, and
SIAM News readers should be aware of its many capabilities.
Like LaTeX and HTML, Markdown is a markup language. A large ecosystem of applications allows documents written in Markdown to be exported to a variety of formats, including PDF and HTML. Designer John Gruber wanted plain-text Markdown documents to be human readable, without markup instructions overwhelming the text. When working with simple documents devoid of heavy mathematical typesetting, writing in Markdown is faster and easier than using LaTeX. The time investment required to learn the language is also much less than that of LaTeX, especially for experienced TeX users. Indeed, I wrote this article in Markdown.
A Brief History
In 2004, Gruber created Markdown with two components: the language itself and a Perl script to convert Markdown documents to valid HTML. His website is one of the best sources of relevant information and features an introduction to the design philosophy, a description of the syntax, and an online sandbox in which users can experiment with the language and preview results.
Many variants or flavors of Markdown have since been created; these variations extend the language with additional features—such as tables, footnotes, and citations—at the cost of complexity and some human readability of plain-text documents. Github Flavored Markdown, utilized by the software-hosting and version-control site Github to render README files and other documentation, is the most widely-used type. Readers may have used it themselves when posting a question to a Stack Exchange forum or adding formatted text to a Jupyter Notebook.
Figure 2. When written in Markdown, the content from Figure 1 is easy to read.
The Markdown Language
Markdown is simple to both read and write, and has much less document overhead than LaTeX. A “Help” page with an overview of the syntax is available through any online editor, and a more complete description is accessible via the MarkDown Guide. Figures 1 and 2 depict a basic comparison for headings, itemized and enumerated lists, and tables for the formatted output of Figure 3.
Software
As with LaTeX, Markdown requires a plain-text editor and a program that converts the text to either HTML or another format. While any text editor works sufficiently, several have modes or extensions that perform syntax highlighting and live preview of the formatted text. I am partial to the Atom text editor with the “Markdown Writer” and “Markdown Preview Enhanced” extensions. Users should also know about Pandoc, a document format converter that can convert between multiple markup formats, including PDF, HTML, Markdown, LaTeX, and—to some extent—Microsoft Word. One can use this to output Markdown text to multiple formats.
Trying one of the many online editors/previewers is the easiest way to begin. Most can also export documents to HTML or PDF. Like Google Docs, HackMD allows multiple authors to log in and simultaneously edit the same file, keep track of projects, and share notes containing integrated mathematics with collaborators and students.
Figure 3. Output from either the LaTeX sample in Figure 1 or the Markdown sample in Figure 2.
My Experience
In the past few years, I have used Markdown for a variety of documents that require some—but not much—mathematical typesetting, especially for online use. For example, I employ it to create syllabi and problem sets for classes that I teach. I also utilize it to respond to referees. These responses typically contain minimal mathematical content, and the live preview makes writing significantly easier. I have previously tried to keep a research diary using Evernote, but was frustrated by its inability to display equations. I now use an inexpensive alternative called Quiver that works with Markdown and LaTeX, which solves this problem.
Markdown has impacted my workflow most substantially in the management of numerical simulations. When I run simulations, I tend to run the same code repeatedly with different parameters; this necessitates a way to store and—more importantly—retrieve the results when writing a paper. A MATLAB program called cell2md allows me to export a Markdown table that lists the parameters, date, and time of each run, along with links to image files and exported data. I have written a program to create a unique directory for the data and add a new line to the Markdown-based index every time I run the code. The whole index is visible in the open-source viewer/editor MacDown, thus providing an easy interface to my runs (see Figure 4).
Figure 4. Table of runs, with Markdown on the left and details on the right.
Limitations
By design, Markdown has a limited feature set. It is currently not powerful enough to replace LaTeX for the purpose of writing articles, though several projects are trying to overcome this deficiency. While extensions exist for equation numbering, bibliography management, and BibTeX integration, such extensions are not standardized; this makes them inconsistent when exporting between different formats. I have found several pages whose authors describe their personal workflow for writing scientific articles in Markdown, but the documentation and tools that would allow an average user to begin adopting Markdown for this purpose simply do not exist.
The Atom editor can generate a live preview of equations produced with a large subset of LaTeX commands. However, its failure to read a document preamble makes it incapable of live-typesetting commands from additional packages or user-defined macros.
I would love to create slides in Markdown and have tried several Markdown-based presentation programs. All seem adequate for very basic presentations, but I have not yet found one that can handle the level of typesetting and structuring necessary for a mathematical presentation.
Parting Words
In closing, do you have a homepage written by hand in Emacs or via Mozilla Composer (which was last updated in 2005, and looks like it)? Use Pandoc to export the page to Markdown and take 20 minutes to rewrite it. If you want a more full-featured homepage, try Hugo, which also uses Markdown. While Markdown cannot replace LaTeX for all of your writing needs, it is quick to learn and will make your life easier and your web pages more readable and professional.
Roy H. Goodman is an associate professor in the Department of Mathematical Sciences at the New Jersey Institute of Technology. He is a member of the SIAM Activity Group on Dynamical Systems and the Activity Group on Nonlinear Waves and Coherent Structures.