Markdown Demystified

Modern digital workflows often involve producing content for different purposes such as notes, emails, blog posts, or presentations. The predominant tools used for these scenarios follow the so-called What-You-See-Is-What-You-Get (WYSIWYG) approach and most likely you have already worked with some of them such as Microsoft Word or Google Docs. While these apps are undoubtedly useful, they come with their limitations: Quite often they work with proprietary data formats and support only a limited number of options to which you can convert your content. This limits the effective processing of your writings through other tools and devices and basically locks in your content.

Wouldn’t it be great if you would need to produce your content only once on any device you have currently at hand and can convert it to any format you like later on?

While looking for tools to overcome the above restrictions, you might have heard of markup languages and, in particular, of Markdown which are based on platform-independent plain text. In this article, we demystify markup languages and Markdown and see that these plaintext-based approaches are in no way inferior to the widely used WYSIWYG processors for producing content.

Even if you’ve never encountered the above mentioned limitations: You might be surprised to find out that you can use Markdown in one of the most preferred messenger apps worldwide…

What is a markup language?

Before diving into Markdown, let’s have a look at what a markup language is. Markup languages are presentational languages that declare the structure and meaning of the content by adding syntax to the text. You might be familiar with markups from editors on authors’ manuscripts — in digital media such markups exist as well in order to specify what the parts of a document are rather than details on how they will get displayed. At its core, a markup language is the same: a specific syntax that gets added to the plain text and allows a computer to “understand” the structure of the text while it is still (more or less) readable for humans. But beware: markup languages are not programming languages. A markup language doesn’t really “do” anything in the sense of a programming language, it is not an executable script and doesn’t contain any programming logic. It is simply a series of markups that are used alongside plain text.

In the context of markup languages, you’ve most likely heard of the Hypertext Markup Language, better known as HTML, for displaying content in a web browser. HTML uses tags which, however, make the content hard to read for humans. This problem inspired John Gruber to develop Markdown, a new markup language which became widely successful and turned into one of the most popular markup languages there is.

Mark… what?

The Markdown language was created in 2004 by John Gruber with the help of Aaron Swartz. Gruber thought that using tags in HTML is unnatural and makes the content very hard to read for humans. He even described writing HTML as “repetitive monkey work”. These issues inspired him to develop his own markup language with the goal to enable people to write in a plain text format that is easy to read, easy to write, and can be converted into (X)HTML. As Gruber puts it:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.(http://daringfireball.net/projects/markdown)

In addition to that he also created a text-to-HTML conversion tool for web writers. Thus, Markdown is basically two things:

1. A formatting syntax for plain text
2. A software tool that converts the plain text formatting into HTML

As already mentioned, most of the traditional text processing applications, such as Microsoft Word, follow the WYSIWYG approach that allows content to be edited in a form that corresponds to its appearance when printed or displayed. Markdown doesn’t work like that! The Markdown syntax gets added to the text you are writing to indicate the structure and meaning of the content. This allows you to create rich text using a plain text editor.

And why should you bother…?

I have to admit, I was wondering the same in the beginning. With so many applications that follow the WYSIWYG approach, why should you even bother with Markdown? Turns out, there are plenty of reasons why Markdown is useful even if you are not planning to use HTML at all. These include:

• Portability: Unlike WYSIWYG tools that use binary data formats, Markdown files are only text files, which is great for portability as they can be easily parsed on different platforms (Linux, Windows, macOS, the web, iOS, Android, etc.). You can edit your documents with any text-capable application on any platform.
• Ubiquity: Since Markdown formatted files are portable and easy to convert into different formats, it is almost everywhere. Not just a lot of online platforms such as Reddit, StackOverflow, and GitHub support Markdown, also many popular messaging apps, like WhatsApp and Slack, do. Markdown even started to be used beyond the web to author books, articles, slide shows, letters, and lecture notes.
• Readability: Files written with Markdown syntax are human-readable, even for people who are not familiar with it. By making use of indentation and line breaks in the Markdown syntax, the text looks very structured.
• Flexibility: Markdown formatted files can be easily post-processed and translated to a wide array of formats such as PDF, HTML, or LaTeX. This allows to write content and formatting once and reuse it for different purposes.
• Efficient version control: Unlike binary files, plain text files only contain textual data and changes are therefore much more easy to track. This allows an efficient version control for example with git.
• Writing flow: Since the Markdown formatting is expressed through text markups, you can directly integrate them into your writing. In other words, you don’t have to stop typing and move your hands from the keyboard to find the buttons in the toolbar to add the formatting to your text. This allows you to become much faster with writing once you’ve got the hang of it.

Markdown basics

How to start

This is another of the big advantages of Markdown: You don’t need to buy or download an (expensive) app, you can simply start by opening the text editor that comes pre-installed with your operating system. When you store the file, do so as a plain text file with a .md or .markdown extension. The next step is to get an editor that can translate the markups within the text to actual formatting. Applications that convert your Markdown file into the file format you need are also called Markdown processors or parsers. If you just want to play a bit with the syntax, one online converter from Markdown to HTML and vice versa is the one from Dillinger, alias John Gruber: On the left side you can type in your text with Markdown syntax and on the right side ("Preview") you can switch between the HTML or how the formatted text will look like on a webpage. A popular open source app for macOS is MacDown which was also used for writing this blog post. It renders the content real time into HTML and displays it in a preview. An advantage is that it supports the original Markdown syntax but also offers to turn on/off popular but non-standard syntaxes.

Headings

A heading in Markdown is prefixed with a # symbol. There are 6 levels which you can use and the number of hashes indicates the level of the heading.

Line breaks

To add a line break you can use <br>. Alternatively, in some Markdown editors such as MacDown you have the option to render the newline literally, i.e., by simply inserting one new line. This new line will be in the same paragraph. If you want to add a new paragraph simply add two new lines as shown below.

Text formatting

As already mentioned, you have several options to highlight your text. You can find the most common ones in the table below:

Depending on the editor you are using, the syntax can be slightly different and you might have to use _ instead of * for bold/italic text.

Lists

With Markdown it is very easy to create bulleted (unordered) and numbered (ordered) lists. For bulleted lists we use *, + or - for each bullet point.

For ordered lists we use the numbering 1., 1., 1.. Wait — no consecutive numbers? No! Markdown takes care of the correct numbering automatically which is very useful if you want to add an additional element within your list at some later point. See the example below.

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab.

Check boxes

Markdown allows you as well to create lists with check-boxes. You simply create a list as shown above and add [] after the symbol for each list item. If you want to check a box just add x in the square brackets.

Quotes

By using > Text a quote will be inserted. Blockquotes can be nested (i.e., a blockquote-in-a-blockquote) by adding additional levels of >:

Links and clickable email addresses

If you want to add a link in your text, wrap the text to be linked in square brackets [Text to be linked] followed by the link in parentheses (link). Markdown supports the following two options to include links.

1. Inline-style:
   [Text to be linked](link "Optional Title")
This is an example inline link with an optional title that appears when you hover over it.
2. Reference-style: Instead of providing the link in parenthesis you give a reference name in square brackets and the link later on in the text or in a reference section at the end of your file.
   [Text to be linked][reference name]
[reference name]: link

To add a clickable email address in your text just put angle brackets around the email address: <exts@epfl.ch>. This will produce the following: exts@epfl.ch

Images

Images can be inserted the same way as links, except they are prefixed by!. The text in the square brackets is the descriptive text for the image ([descriptive text]) and the path to the image is given in parentheses ((path_to_image)). If you want to add a title when the user hovers over the image, write it with quotation marks around it right after the reference (as shown in the first example for links). You have also the inline-style and the reference-style option.

1. Inline-style:
   ![text](path_to_image "Optional Title")
2. Reference-style:
   ![text][reference name]
[reference name]: path_to_image

Example of an inline-style image:

Code snippets

You have two options to include code in your text. You can either use inline code by wrapping the code in backticks ` or you can add a block of code by wrapping it in three backticks ```:

Even though syntax highlighting isn’t part of the Markdown specifications, some Markdown editors support it: You can specify the programming language by adding the name of the programming language after the first three backticks (without a whitespace in between!). For example:

You can even show changes in code by adding diffafter the first three backticks and prefixing the lines with either + or -. The output will be as follows:

Visual separations

Visual separations in a text can be added by using three dashes ---, asterisks *** or underscores ___. This will produce a line as shown below:

Escaping

What if you actually want to use * or - in your text and not having it appear formatted when processed? Simply prefix the symbol with a backslash \ or write it as inline code wrapping it in backticks `.

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column. You can optionally add pipes on either end of the table. See the example below:

Wrapping it up

Even though there is an original Markdown syntax, over time a lot of different “dialects” evolved which are also called “flavors” of Markdown. For example, one of the flavors is GitHub flavored Markdown (or GFM) which is GitHub’s own version of the Markdown syntax and provides additional features that make it easier to work with content on GitHub. A useful cheatsheet on the basic Markdown syntax and GFM can be found here.

Depending on the editor you are using, you also might have a slightly different syntax. If you’ve never worked with Markdown before, I would recommend to use an editor with a good documentation as it will make your start much easier.

To summarize, if you want to write content that can be used with different platforms and applications, distributed via email, and converted into presentations or blog posts, remember this article and give Markdown a shot. I am sure you won’t regret it!

To benefit from the many opportunities of the digital age it becomes increasingly important to have digital skills and knowing how to use markup languages is only one of them. If you are interested in extending your digital skill set, consider taking a course with the EPFL Extension School in programming (such as Thinking and Creating with Code), data science, machine learning or others. For further details, please visit our website and reach out to us by e-mail or Twitter.