Shreyas

I am back after a ten month hiatus. While I am keen on continuing my Dynamic Complexity series, in this two post series, I wish to write on a topic of broader interest to people working in mathematical disciplines: The use of markdown for typesetting. This subject is fairly large so I split it into two parts. In part-1, I do not go into math and diagrams, so readers who are expecting math would be disappointed. I’ve got you covered in part 2. I think, and I hope you will agree, that it is only fair that I give an introduction to markdown to those who may not have heard of it.

To those who are new to markdown, I welcome you to a beautiful and simple language that will save you tonnes of time, if you invest a very small chunk of it learning markdown. In particular, if you are a student or professor who has to typeset mathematical lecture notes, problem sheets, or even blogs, you will find this useful. Many mathematicians, physicists, and computer scientists do use it in their blogs. This post is for those who haven’t discovered markdown yet.

Why Markdown?

$\LaTeX$ is an indispensable tool in the mathematical sciences for writing documents containing mathematical notation. A wide range of documents can be typeset in $\LaTeX$ including lecture notes, class notes, problem sheets, presentations, research articles, and theses. While one cannot avoid Latex when writing formal documents such as a research paper or a thesis which must conform to strict formatting requirements, one can be relatively lax with lecture notes and problem sheets. For these use-cases, Latex can prove to be rather cumbersome. Think of the last time you typeset a table or used tikz to typeset standard diagrams or imported a piechart image. Fortunately there are simpler alternatives, markdown being one of them. It is already in common use among computer science folks. I hope to introduce this tool to a broader audience.

Markdown was, to quote wikipedia, designed as “a lightweight markup language with plain text formatting syntax”. $\LaTeX$ was designed with much loftier objectives and is commensurately complex. Markdown has a much simpler syntax. It was originally designed to be translated into the HTML file format* which is the lingua franca of web browsers. Over the years this simple language has been extended to add many features including the ability to insert Latex math formulae, flow charts, diagrams etc.

The charming simplicity of the syntax and its compatibility with web pages* combined with the powerful tools that have grown to support it, makes me believe that markdown is a tool that deserves to explored by anybody who has the unenviable task of typesetting mathematics. So let’s dive into it right away.

*It can be converted to the HTML format, PDF format as well as a bunch of other formats

Full Disclosure: I have used markdown with live preview to take notes in mathematical lectures with lots of formulae. I couldn’t have done that on latex proper.

Tools for working with Markdown

Markdown files typically have a .md extension. Technically speaking, any text editor, even something as elementary as notepad will suffice to create and edit markdown files. After all markdown is just another document specification format, and you could use a variety of command line tools including, but not limited to, pandoc to render and convert it to other file formats. Nevertheless, I am trying to simplify typesetting for my readers and that calls for better tools. Editors supporting markdown have come a long way since the 1990s and it is now possible to obtain a live preview of the document as you type it. Two of my favourites are:

• VSCode: This text editor, comes with a number of extensions that support various flavours of markdown. I recommend installing it. It has a very gentle learning curve and if this is the first time you are using an advanced rich text editor I recommend playing around with it to make yourself comfortable with its features, especially the command palette and extension management. Although there are probably many good extensions out there, I prefer the “Markdown-all-in-one” extension, purely because I am accustomed to it. It offers a rich set of features and markdown flavours. Like most extensions for markdown, it supports live previews in a pane that is positioned right beside your typing pane. I would encourage readers to configure it to their convenience. You can tune it to open the preview as soon as you open markdown files. Alternatively you can configure a keyboard shortcut to open and close the preview pane. By using the Save As option on the preview pane (keyboard shortcut Ctrl + Shift + S), you can save the preview you see as an html file.
• Typora: This is a relatively new editor which supports multiple flavours of markdown as well as several features for rendering it. It renders markdown live and in-place, as you type. It has a small collection of well-designed themes for rendering the output. When you install it at first, you will need to go to Files > Preferences and enable inline math, if you wish to be able to use math within lines of text, enclosed by $ signs, as against using it exclusively in separate lines (the equivalent of using the equation or align enviroments, or $$ in latex). I would also encourage first time users to watch out for the focus mode. It is a useful feature that helps you focus on the current segment you are working on by making the other parts of the document look light. But it can also confuse users. To toggle this feature go to the View menu and click on the Focus Mode option. The website offers you instructions for installation. This is my current editor of choice. It is still in the process of development, so some people might have reservations about using it. Even so, the product appears more or less finished to me and hasn’t given me any trouble so far. To save the output as an HTML or PDF file, look for the Export option in the File menu.

For beginners I would strongly recommend Typora or other equivalent editors. This is not a product endorsement. Just a personal preference. There are other text editors such as atom and sublime which have their own markdown extensions.

Once you have installed it, you are all set to play with markdown. In the next section I will give an outline of the standard markdown syntax. If you are familiar with it, I recommend that you skip the rest of this post. The meat of this series of posts lies in part 2.

Markdown Basics

There are many different flavours of markdown. Each flavour offers its own extensions, on top of a common core syntax, the standard markdown syntax. This standard syntax is relatively simple. But it offers the ability to produce well-formatted rich text documents. Let’s get started on that first. We will discuss the features that makes them useful for mathematical work in part 2.

There is a very good 10-minute hands on markdown tutorial to quickly get you through the basic syntax. I’d encourage all readers to go through it. But here’s a quick summary anyway:

• The characters _ and * can be interchangably used to modify the style of text. When you surround text with single *s around some piece of *text*, you get italicised text. When you surround **text** with double *’s you get bold text. If you want to use either of these symbols just to print them then prepend them with a backslash like this \* or this \_. In CS lingo, you are escaping the * and _ characters.
• To start a new line, end the previous line with a single \ followed by no spaces or two spaces.
• To start a new paragraph, just hit enter twice (i.e. leave a line empty)
• Headings are indicated using #s followed by a space. Headings must always begin in a new line. While some editors are lax about this, strictly speaking the heading symbol must be followed by one space. The entire line following the heading symbol becomes the heading text. indicate There are six levels of headings corresponding to the six heading tags in HTML.
  • # Heading 1: The largest and usually used for article, page or chapter titles.
  • ## Heading 2: Is slightly smaller and typically equivalent to section headings in $\LaTeX$.
  • ### Heading 3: Can be used for subsection headings.
  • #### Heading 4: Is useful for indicating theorems, lemmas, proofs etc. It’s text size is typically about the same as the rest of the text
  • ##### Heading 5: Is useful for footnotes and indices.
  • ###### Heading 6: Let me know if you find a use for this one. It is ridiculously small.

• Block quotes: You can produce block quotes by beginning a new paragraph with the > symbol. You get something like the following. Strictly speaking each line in a blockquote must begin with a >. In practice many markdown editors don’t require this and include the paragraph that immediately follows a > in a blockquote. They look something like this: > This is a block quote. Note how this text is highlighted. These are useful for re-iterating important points or making remarks. To break out of a block quote, hit enter twice i.e. start a new paragraph.

• Lists: As usual there are two kinds of lists.

  • Unordered Lists: To start an unordered list, start a new paragraph, and mark each item in the list with a - or * as the first character of the line followed by a space after which you can insert the contents of the list item. Lists are usually indented
  • Ordered Lists: Ordered Lists are pretty much started the same way except, instead of * or -, you start an item say item no.1 with 1. or 1)
  • Nested Lists: In markdown you can have lists nested inside list items. Typically to start a list inside a list item, hit enter, but instead of starting a new list item right away with a *,-,1., or 1), add a couple of spaces in the beginning of the line before you insert an item as usual. It will appear as a nested list in the output.

• You might occasionally want to add hyperlinks to some text. You can do that using the syntax [text](http://example.net). the output looks like this : text. You can also link to headings within the same markdown document. To explain how the link to a header must be obtained, consider the section title Why Markdown. This translates to the link #why-markdown. Notice the # at the beginning of the link. It indicates an internal link. Further if you have a mult-word link with varying capitalisation, the corresponding link can be obtained by transforming all characters to lower case and replacing each space by a hyphen. Here, try this internal link back to the Why Markdown section.

• Images: The syntax for adding images is very similar to that of links except the exclamation mark (!). It looks like this [Image title](Link to image). The link to the image can be a local file or a hyperlink on the web.

• Code. This one is going to be hard to give a syntax demo. Basically code is any section that the markdown parser treats as text that is to be left as it is. Markdown renderers typically display it as a highlighted block of code. I have been writing this post in markdown and have been using the code syntax. To add some code inline, enclose the text in single backticks (`). If you wish to write multiple lines of code, start a new line with three backticks (```) go to the next line, enter your code, and then on a new line, enter three backticks again to close off the code section. This multi-line code section offers interesting possibilities which we will discuss in part-2.

It can take a while to get accustomed to this syntax. So it is a very good idea to use a markdown cheat sheet like this one in the beginning.

The End of Part - 1

That completes the description of basic markdown syntax. Now I recommend that you play around in your chosen editor for a while and watch the preview of the rendered markdown. In the next part, I will discuss how you can insert math and diagrams into your document, which is the primary goal of this two part series.