What is Markdown?

Markdown is a language. It's not a programming language, though. It is what you call a markup language. A markup language is a way of annotating a text document to include hints about how the document should be displayed. When the markup document is processed (displayed), the markup language is not shown. Instead, it is used to format the text and only the formatted text is shown.

According to Wikipedia, the name markup comes from "marking up" of paper manuscripts, something that editors do when suggesting corrections. Ok, so that's a fancy name, but what is Markdown? Chances are you've been using it already (if you've ever formatted Slack messages, for example), but perhaps you didn't know it was called that. Markdown is essentially a way to write formatted text.

The formatting options allowed by Markdown are not varied (for example, you cannot specify font style or colors), but they are powerful enough to significantly increase the readability of a text document. Using Markdown, you can quickly include headers, links, images, bold, italic text, paragraphs, and ordered or unordered lists.

In this guide, I'll be using Jupyter Notebook to demonstrate Markdown, however note that Markdown is not Jupyter specific. Many other services and products use it to allow easy text formatting.

 

• Quick Guide: How to Start a New Jupyter Notebook
• Intro to Programming: How to Get Your Computer Ready to Run Python

NOTE: In this quick guide on how to use Jupyter notebooks, I mention that Jupyter allows changing the type of a cell to make it a Markdown cell. To follow the examples below, please make sure to change your cell types from code to Markdown in your Jupyter notebook.

 

• How to Write and Run Code in Jupyter Notebook

 

What Are the Advantages of Using Markdown?

Of course, you can format text in a text editor, so why would you choose Markdown?

First of all, unlike the text format used by many editors, Markdown is just plain text, meaning it's very easy to share between computers. It is not proprietary, so anyone can use it. It is also very simple, yet quite powerful. Just a few symbols and rules are required to write Markdown.

And last, but not least, it is compatible with the web. What I mean by this is that Markdown can easily be converted to HTML, and so it can easily be displayed in browsers.

In fact, this is exactly what happens in Jupyter notebooks. Because Jupyter notebooks are displayed in a browser, the Markdown is actually converted to HTML and it is the various HTML tags that tell the browser how to actually display the Markdown formatted text. While HTML is beyond the scope of this tutorial, here are a few examples of the kind of Markdown-to-HTML transformation that happen when Markdown is displayed in a Jupyter notebook:

 

• Bold text becomes plain text inside strong tags. Browsers display text inside strong text in bold.
• Images are converted to img tags. Browsers know how to render these tags as images.
• Headers are converted to h1, h2, etc. tags. Browsers know how to display these tags as headers.

 

When Should You Use Markdown in a Jupyter Notebook?

Markdown is a way to format text. By default, Jupyter notebook cells are formatted to display code, so without Markdown, there is no easy way to include explanatory text in your notebooks. Of course, you can always include code comments, but those cannot be formatted. What about links or images?

 

• Intro to Programming: How to Write Python Code Comments

Jupyter notebooks are great for presenting research-type work. In fact, that's where they have their roots - in presenting scientific work. Consider, for example, the screenshot below, representing a small section of a Jupyter notebook I wrote which introduces the concept of linear regression in classical machine learning.

Image Source: Markdown in a Jupyter notebook, Edlitera

Notice how seamlessly the Markdown and code cells alternate, allowing me to create a presentation that includes both explanatory text and executable code. While I could have used Python comments instead of Markdown cells, I argue that Markdown creates a much more enjoyable experience for the reader.

So, to summarize, I encourage you to use Markdown in your Jupyter notebooks whenever you have to include a large body of plain text that would benefit from being formatted.

If you are convinced and want to learn Markdown, then let's jump into the tutorial. Markdown is very simple - you'll only need a few minutes and you'll be an expert at it.

NOTE: Below, I show the Markdown (what you need to type) in purple and the result displayed right underneath it.

 

How to Write Text in Markdown

 

Bold

To write bold text, simply surround the text with **. For example:

**this is a bold text** 

this is a bold text

 

Italics

To write italic text, simply surround the text with _. For example:

_this is an italic text_

this is an italic text

 

Bold and Italic

To write text that is both bold and italic use both ** and _. For example:

**_this is both bold and italic_**

this is both bold and italic

 

How to Write Paragraphs in Markdown

 

Paragraphs

Perhaps the most confusing thing about Markdown for a beginner are paragraphs. Here's why: try typing the following text in a Jupyter notebook Markdown cell:

Two households, both alike in dignity,
In fair Verona, where we lay our scene,
From ancient grudge break to new mutiny,
Where civil blood makes civil hands unclean.

If you typed these lines from Shakespeare's Romeo and Juliet exactly as they appear above, the text will be displayed as follows:

Two households, both alike in dignity, In fair Verona, where we lay our scene, From ancient grudge break to new mutiny, Where civil blood makes civil hands unclean.

What happened to the line breaks? Well, Markdown ignored them. Instead, it offers two ways of breaking lines: soft breaks and hard breaks.

 

Soft Breaks

Soft breaks are achieved by adding two spaces after each line. Let's revisit the example above, and now let's add two spaces after each line.

NOTE: Since spaces are invisible, below we represent each space with the + symbol, but when you try this out in your Jupyter notebook, make sure to replace the + symbols with spaces.

Two households, both alike in dignity,++
In fair Verona, where we lay our scene,++
From ancient grudge break to new mutiny,++
Where civil blood makes civil hands unclean.

If you typed the lines with the two white spaces at the end, the text will be displayed as follows:

Two households, both alike in dignity,
In fair Verona, where we lay our scene,
From ancient grudge break to new mutiny,
Where civil blood makes civil hands unclean.

 

Hard Breaks

Hard breaks are used to separate paragraphs. You can achieve this in Markdown by simply including a blank line in between paragraphs. For example, consider the following Markdown of two paragraphs from Oscar Wilde's The Picture of Dorian Gray:

In the centre of the room, clamped to an upright easel, stood the full-length portrait of a young man of extraordinary personal beauty, and in front of it, some little distance away, was sitting the artist himself, Basil Hallward, whose sudden disappearance some years ago caused, at the time, such public excitement and gave rise to so many strange conjectures.

 

As the painter looked at the gracious and comely form he had so skilfully mirrored in his art, a smile of pleasure passed across his face, and seemed about to linger there. But he suddenly started up, and closing his eyes, placed his fingers upon the lids, as though he sought to imprison within his brain some curious dream from which he feared he might awake. 

Notice the break (empty line) in between the two paragraphs. If you displayed this Markdown in a Jupyter notebook it would show up as:

In the centre of the room, clamped to an upright easel, stood the full-length portrait of a young man of extraordinary personal beauty, and in front of it, some little distance away, was sitting the artist himself, Basil Hallward, whose sudden disappearance some years ago caused, at the time, such public excitement and gave rise to so many strange conjectures.

As the painter looked at the gracious and comely form he had so skilfully mirrored in his art, a smile of pleasure passed across his face, and seemed about to linger there. But he suddenly started up, and closing his eyes, placed his fingers upon the lids, as though he sought to imprison within his brain some curious dream from which he feared he might awake. 

That's exactly what you need when writing paragraphs.

 

How to Make Headers in Markdown

There are 6 header levels in Markdown. h1, h2, h3, h4, h5 and h6. h1 is the largest, h6 is the smallest. To write a header, include # before the text for h1 header, ## before the text for h2 header, ### before the text for h3 header, and so on.

NOTE: In Jupyter notebooks, you must leave a space between the group of # signs and the text. This is not required in Markdown in general, but rather it's a Jupyter notebook quirk.

For example:

# this is header 1

this is header 1

---

## this is header 2

this is header 2

---

### this is header 3

this is header 3

---

#### this is header 4

this is header 4

---

##### this is header 5

this is header 5

NOTE: In Jupyter notebooks, header 5 (h5) is shown as both bold and italic.

---

###### this is header 6

this is header 6

NOTE: In Jupyter notebooks, header 5 (h5) and header 6 (h6) are displayed identically.

 

How to Add Links in Markdown

Markdown allows you to easily insert links into plain text. To do that, simply wrap the text for the link in [ ] and wrap the URL in ( ).

NOTE: Remember to include http:// or https:// for absolute links, otherwise the links will be considered relative.

[this is a link to Edlitera](https://www.edlitera.com/)

this is a link to Edlitera

 

How to Add Images in Markdown

Adding images to a Jupyter notebook Markdown cell is very similar to adding links. The only difference is that the square brackets are prefaced with an exclamation point.


Image Source: Photo by Kari Shea on Unsplash

NOTE: When displaying an image in markdown, the text between the square brackets (e.g. [image of a cat sitting on a chair]) becomes the value assigned to the alt attribute of the image. This attribute is important for accessibility. Screen readers use the value of this attribute to describe the image to people who may have difficulty seeing it. So while you can leave it blank (and the image will still show), it is a good idea to get in the habit of adding it by including descriptive text between the square brackets.

 

How to Add Blockquotes in Markdown

Blockquotes are used to draw attention to quotes from other sources. They are not as common in Jupyter notebooks, however I will introduce them here, in case you need them. To display blockquotes simply include a "greater than" sign (>) before the text you want to quote.

> Someone once told me that time was a predator that stalked us all our lives. But I rather believe that time is a companion who goes with us on the journey and reminds us to cherish every moment because they'll never come again. What we leave behind is not as important as how we've lived. **Jean-Luc Picard**

 

Someone once told me that time was a predator that stalked us all our lives. But I rather believe that time is a companion who goes with us on the journey and reminds us to cherish every moment because they'll never come again. What we leave behind is not as important as how we've lived. Jean-Luc Picard

NOTE: I included some bold text in my blockquote, as an example. This is just to show that you can combine various Markdown formatting to achieve exactly what you need.

 

How to Add Lists in Markdown

You have two types of lists: ordered and unordered.

 

Ordered Lists

In ordered lists, each list item starts with a number. What's interesting about Markdown in Jupyter notebooks is that you don't have to include the numbers yourself. You can start each list item with 1, for example, and when the Markdown is displayed, the correct numbers will be filled in.

This feature makes it very easy to reorder items without having to edit all those numbers!

What you need to type:

What gets displayed:

 

Unordered Lists

Unordered lists are lists that start with bullet points. They are also very easy to create with Markdown.

What you need to type:

What gets displayed:

Lists can be nested. You can also mix and match. Check out the example below:

What you need to type:

What gets displayed:

Hopefully this gives you a sense of how easy it is to create lists in Markdown. Also note that Jupyter notebooks include syntax highlighting for Markdown, making it easy to distinguish between the various levels of your nested lists.

I hope you enjoyed this quick guide on how to write Markdown in Jupyter notebooks.

 

• Read next: Intro to Programming: What is Programming and How to Start? >>