Appendix A — Introduction to Markdown

Created in 2004, markdown is a markup language used to format plain text with markings that indicate what formatting is to be applied when the text is converted to HTML, PDF, or some other format. It is used in markdown cells in Jupyter, text cells in Google Colab, and many other places, such as Reddit and Github.

In markdown cells in Jupyter, or text cells in Colab, you can enter plain text plus markdown. Then, when the cell is run (or rendered) the text shows up with the specified formatting.

This Appendix provides an overview of some features of markdown that you can use to format markdown cells in your Jupyter notebooks. This can be very useful when you use a Jupyter notebook to create a research report or some other document for communicating with others.

In the following examples the markdown code (text with special elements to indicate the rendered format) is first displayed, and then the rendered output of that markdown text is displayed.

A.1 Headings

Headings are indicated with one or more pound characters followed by a space, and then the heading text. The fewer pound characters the larger the heading. Below is an example of some markdown to produce various heading levels and what the result looks like when rendered:

Markdown text:

# First level heading
## Second level heading
### Third level heading
#### Fourth level heading

Formatted text resulting from rendering the markdown text:

First level heading

Second level heading

Third level heading

Fourth level heading


A.2 Italics, bold, and bold italics

Italics, bold, and bold italics are indicated by surrounding text with single, double, and triple asterisks, respectively.

Markdown text:

*Here is some italicized text.*

**Here is some bold text.**

***Here is some bold italicized text.***

Formatted text resulting from rendering the markdown text:

Here is some italicized text.

Here is some bold text.

Here is some bold italicized text.


A.4 Bulleted Lists

A bulleted list is indicated by starting the line with an asterisk then a space. Indent two spaces for indentd bullets. You must leave a blank line above and below the bulleted list. Below is an example of the markdown and the result.

Markdown text:

Bulleted List:

* List item
  * Sub item
  * Sub item
    * Sub Sub item
* List item
* List item

Formatted text resulting from rendering the markdown text:

Bulleted List:

  • List item
    • Sub item
    • Sub item
      • Sub Sub item
  • List item
  • List item


A.5 Numbered Lists

A numbered list is indicated by starting the line with a number followed by a period and then a space. It is recommended to just use the number one. The entries will be automatically numbered when the markdown is rendered. Use a tab to indent to the next level. You must leave a blank line above and below the numbered list. Below is an example of the markdown and the result.

Markdown text:

Numbered List:

1. List item  
    1. sub item
    1. sub item
    1. sub item
1. List item
1. List item

Formatted text resulting from rendering the markdown text:

Numbered List:

  1. List item
    1. sub item
    2. sub item
    3. sub item
  2. List item
  3. List item


A.6 Paragraphs and line breaks

Paragraphs should be separated by one or more blank lines. A line break is indicated by ending a line with two spaces and then the Enter key. To force an empty line the HTML <br> tag may be used.

Markdown text:

Here is a nice paragraph of text. It is a nice paragraph
of text indeed.
Notice how the paragraph doesn't 
have the line breaks you see here in the markup. That is 
because the line breaks are not preceded by two space characters.

In this paragraph, however, all the lines are ended with two space characters,  
so, the line breaks are recognized and the line breaks in  
the rendered text match the line breaks in the markdown.

Here is some text <br> separated from the following text by an HTML break tag.

Formatted text resulting from rendering the markdown text:

Here is a nice paragraph of text. It is a nice paragraph of text indeed. Notice how the paragraph doesn’t have the line breaks you see here in the markup. That is because the line breaks are not preceded by two space characters.

In this paragraph, however, all the lines are ended with two space characters,
so, the line breaks are recognized and the line breaks in
the rendered text match the line breaks in the markdown.

Here is some text
separated from the following text by an HTML break tag.

A.7 Blockquotes and Simple Code Formatting

Blockquotes are indented sections of text. They are indicated by preceding the text with a greater sign followed by a space.

Code text can be indicated by surrounding the text with backticks, which causes it to be rendered in a monospace font with a faint background.

Markdown text:

> Here is a nice paragraph of text. that is blockquoted. It is a very nice paragraph indeed.
> It is probably one of the most impressive paragraphs ever produced. Blockquoting is nice because it
> separates and draws attention to the blockquoted text.

Within some text, a code expression, such as `print(result)` or `pd.DataFrame()` 
may be indicated by surrounding the code expression with backticks.

Formatted text resulting from rendering the markdown text:

Here is a nice paragraph of text. that is blockquoted. It is a very nice paragraph indeed. It is probably one of the most impressive paragraphs ever produced. Blockquoting is nice because it separates and draws attention to the blockquoted text.

Within some text, a code expression, such as print(result) or pd.DataFrame() may be indicated by surrounding the code expression with backticks.


A.7.1 Formatting for Longer Code Blocks

Longer code sections can be indicated with triple backticks or by indenting each line at least 4 spaces. If the code language is indicated directly after the first set of triple backticks the rendered code will include syntax highlighting.

Markdown text:

A block of code can be indicated by indenting each line at least 4 spaces:

     for i in range(10):
         if i > 8:
             print(f"Now at {i}. This is the end.")
         else:
             print(i)

A block of code can also be indicated with triple backticks:

```
for i in range(10):
    if i > 8:
        print(f"Now at {i}. This is the end.")
    else:
        print(i)
```

If the language of the code is indicated right after the first set 
of triple backticks syntax highlighting will be applied:

```python
for i in range(10):
    if i > 8:
        print(f"Now at {i}. This is the end.")
    else:
        print(i)
```

Formatted text resulting from rendering the markdown text:

block of code can be indicated by indenting each line at least 4 spaces:

 for i in range(10):
     if i > 8:
         print(f"Now at {i}. This is the end.")
     else:
         print(i)

A block of code can also be indicated with triple backticks:

for i in range(10):
    if i > 8:
        print(f"Now at {i}. This is the end.")
    else:
        print(i)

If the language of the code is indicated right after the first set of triple backticks syntax highlighting will be applied:

for i in range(10):
    if i > 8:
        print(f"Now at {i}. This is the end.")
    else:
        print(i)


A.8 Escaping Special Markdown Characters

If you want to use one of the special markdown characters, such as the pound sign or asterisk, as a regular character and not a markup character you can “escape” it by putting a backslash in front of it. This causes its meaning as a markup character to be ignored.

Markdown text:

The \#1 rule about using special markup characters as normal characters in 
markdown is that you have to escape\* them.

\* Escaping is done with the backslash character.

Formatted text resulting from rendering the markdown text:

The #1 rule about using special markup characters as normal characters in markdown is that you have to escape* them.

* Escaping is done with the backslash character.