Shreyas

This post is a continuation of Part 1. If you haven’t read it I would encourage you to skim through the first paragraph.

Now that we have dispensed with the initial hurdles of setting up our tools and getting a hang of markdown syntax, it’s time to discuss how markdown can prove useful to academics. While I write as someone from a mathematical background, I am sure people from other areas will find this equally useful. I have structured this article as a sequence of sections each devoted to one particular feature that most markdown flavours offer, and I find useful. In particular, both the editors I have described in Part 1 support these features. I also mention some more niche features that certain flavours of markdown offer. I finally discuss ways to publish the content online using static site generators. This can help you publish your content such as lecture notes, documentation, or blogs on the web with very little effort on your part.

Tables

The pain of typesetting tables would be familiar to anybody using the table environment in latex. The endless commands, the tabular environment, the necessity to constantly plug in &’s to separate cells in a row and so on. And if you miss and &, finding it can be a big headache. In many situations, we do not need all the paraphernalia that latex’s table environment offers us. A simple table is preferable. For these situations, markdown has a remarkably intuitive solution. See for yourself. The following is the source for a table.

| Name | Fruit/Vegetable|
|------|----------------|
| Potato | Vegetable|
| Tomato | Vegetable|
| Peach | Fruit|
| Apple | Fruit|
| Okra | Vegetable|
| Mango | Fruit|

This is how it is rendered.

To get into the details, tables always start in a new paragraph (skip a line, hit Enter twice after your last paragraph). The header row is essential. It determines the column structure of your table. Markdown uses the horizontal bar | for demarcating columns. An initial and final horizontal bar | is necessary. After the header row, it is essential to have another row, whose column structure matches the header row and whose entries are all three or more hyphens. Subsequent rows are used for entering the data tuples and the pattern of the header row is repeated for demarcating columns. It is important that the column structure of header match the column structure of all subsequent rows of the table.

The Math Itself

Many extended flavours of markdown offer the ability to include mathematical formulae in latex syntax within markdown documents. Let’s first look at how math itself is inserted into a markdown document before we discuss some important issues regarding support for various latex commands and environments.

Like latex there are two kinds of math renderings supported.

• Inline Math: This is math that appears as part of a line or paragraph of text. You can use almost every latex math command within the inline math delimiters $..$. For example $\tan^2(x) = \frac{\sin^2(x)}{\cos^2(x)}$ yields $\tan(x) = \frac{\sin(x)}{\cos(x)}$. If you make latex errors such as this: $\frac{1}$, you may get error messages or simply an image of the text like this $\frac{1}$, depending on the markdown flavour.
• Display math: This is math that appears in it’s own line and centered. Most markdown flavours support the $$...$$ delimiters by default.

When using math in markdown it is important to keep the following things in mind:

• When using the _ character for subscripting it is advisable to escape it, i.e. type it as \_. This is because markdown interprets _ as the beginning of italicised text, and the subscript notation might go missing from the rendered math. Part of the problem lies with the absence of standardisation of math in markdown.
• Always start the dislay math mode after a blank line, as you would to start a paragraph.
• The display math mode supports many common text mode environments such as align and equation which are used for inserting math. These environments cannot be inserted outside the display mode math delimiters. Some markdown renderers also support the equivalent math mode environments such as alignedAt. If you are publishing web pages, check the notes below on differences between renderers.
• Equation numbering is an optional extra that some markdown flavours offer. Typora is one such editor. The same goes for theorem numbering. In practice, I recommend against relying on these numbering schemes. If your document relies on precise equation numbering then markdown is probably not appropriate for your task. I have used it for intense mathematical derivations, but these were a part of lecture notes and notes for exams, not parts of a thesis or a paper.
• Any latex command must be surrounded by math mode delimiters. Commands for macro definitions such as \newcommand and \renewcommand, and environment definitions such as \newtheorem must always be inside the display math mode delimiters. Not all markdown flavours support these commands, but my vscode editor and typora have some support for them.
• Debugging math can be a little hard so divide your math into smaller chunks, It is okay to have multiple separately delimited lines of math.

But all these caveats aside, it is usually a pleasure to typeset markdown in mathematics. At this stage it is important to mention something about using markdown for webpages. When markdown flavours convert markdown files to html files, the mathematical parts are inserted in the TeX format. Javascript libraries, typically MathJax or KaTeX are included in the html files which then render the math output. MathJax has been the mainstay of rendering math on the web for some time although KaTeX is beginning to catch up thanks to its faster rendering. That said, there are differences in the commands and environments that are supported by these libraries. For instance KaTeX only supports the alignedAt environment for math, whereas MathJaX is more liberal in its support for text and math environments. The choice of libraries is typically made for you by your editor or website generator. If you have the patience to tinker with configuration files and source files, you can make changes to the default options. I will not go down that rabbit hole in this post. For this blog, I replaced the KaTeX library with MathJax, specifically for \newcommand support. Typically, this requires inserting your own script tag for the mathjax or katex source. I personally prefer MathJax for its much broader support for latex commands, even though KaTeX appears to be much faster at rendering.

Source Code

While this feature is a part of most markdown flavours including github’s, I believe it merits its own brief section. Source code can be rendered in inline and display modes just like math. To render source code inline we use back-ticks `...` as delimiters. On standard US English keyboards, this key is present under the Esc key along with the ~ symbol. For multiline source code in display mode, the code is enclosed between three back-ticks as delimiters, exactly like the $$ delimiters. See this example below

    ```
        Source
    ```

This will be rendered as

    Source

Some markdown flavours and editors also offer syntax highlighting for a limited set of languages. In such cases, the language of the source code is specified after the opening delimiter as shown below

    ```python
        def fn():
            print "Hello"
    ```

This is rendered as:

    def fn():
        print "hello"

Enclosing text in backticks renders the text exactly as it is with no processing. So how does one include backticks within such text? If the text to be enclosed is inline, then it suffices to enclose it in double backticks. For display mode, indenting with four spaces is necessary.

Other extensions

Various markdown flavours and editors offer further extensions. Here’s a brief list of some of them

• Both Typora and VSCode (with extensions), support mermaid. Mermaid lets you easily insert directed graphs (networks), flowcharts, sequence diagrams, and gantt charts.
• Bibliography a la bibtex, although it requires a lot of work to get it right.
• Checkboxes which can come in handy on web pages which contain checklists
• Definition Lists
• Line charts, bar charts, histograms, polar charts, etc with the javascript library chart.js
• footnotes
  

These additional features have limited support. Some of them may require using specific markdown editors or alternatively, some extra tinkering with source files. They are not universally available in all markdown flavours, and not all editors support them. Therefore I’ll leave it to the reader to explore these features. The markdown plus flavour supports most of these features.

Data scientists may already be familiar with markdown, since it is an integral part of jupyter notebooks. Others may find R markdown a very useful tool for presenting their work in all sorts of formats using markdown.

Publishing Online

While markdown processors, especially pandoc, offer the ability to render your markdown into dozens of different file formats, markdown is particularly useful for blogging on the web. Standard blogging platforms like medium or wordpress offer very little if any support for typesetting math. In wordpress one has to seek out the right plugins and be careful to avoid wordpress or plugin specific shortcodes. Static site generators are the best bet for such work. They are extensively configurable and can be hosted easily, either on your own server or on a free service like Github Pages. Jekyll and Hugo are two very popular static site generators. Sphinx with readthedocs is a powerful combination for lecture notes. I write this blog with Hugo. These generators allow you to write your article and generate sites according to the theme you pick. Their documentation is accessible to someone who has basic familiarity with text editors and markdown and can copy and paste commands on their shell. Typically they compile your markdown pages and paste the output in a folder labelled public, which contains the static site you need to upload onto your server’s public folder. I would highly recommend exploring these tools if you are considering blogging.

Some final thoughts

I started this two post series on markdown with the limited goal of introducing markdown for people from the mathematical sciences. The title of these posts Markdown for Math reflects this initial goal. However it looks like I have deviated significantly from this original goal, in an effort to highlight what markdown has to offer to academics. Nevertheless I hope you find this long rambling two part series useful. I apologise for any typographical errors. I started writing this post over a month ago, and have had little time to complete it. I’ll be glad to take suggestions and offer clarifications.