Markdown is a plain text formatting syntax that you can easily use to write text that can be converted to formatted text, for example, HTML. Markdown was developed by John Gruber, who runs the popular Daring Fireball blog. Markdown has found many uses, two of which are relevant for this course:
Markdown is free software that is available under a BSD—style open source license. The Jupyter organization has documentation that demonstrates how to use Markdown within a cell to produce formatted text, and of course we often use documentation presented in Jupyter Notebooks that use Markdown cells.
The rest of this Jupyter Notebook will review the standard mechanisms for documenting your work in Markdown.
You can mark different sections of text by using different header levels (you can also use the IPython Notebook Header cells). Markdown provides support for six header levels, which are generally marked by one or more hash # characters, where the number of hash characters indicates the header level. For example, to make a first level header text called Markdown followed by a second level header called Header Text, you would use the following:
# Markdown
## Header TextNormally, you simply write text as normal for a document. Paragraphs are simply one or more lines that are enclosed in blank lines. If you need to insert a line break between two lines of text (sometimes useful when writing out lists), you simply add two or more blank spaces at the end of the line to break.
Here is a simple Markdown formatted text that consists of several sentences. This demonstrates how normal text can be written in a Jupyter Notebook cell, which can provide ancillary information about a specific data analytics effort.You can easily indicate text that should be italicized by enclosing the appropriate text in either single asterisk * characters or single underscore _ characters. Likewise, for bold text, you enclose the text in two asterisk ** or underscore __ characters. My personal preference is to underscore characters; for example, the following Markdown text will first create bold text followed by italics text:
first create __bold text__ followed by _italics text_Student Exercise
In the empty Markdown cell below, write a Markdown formatted document that includes a first level heading, a sentence, a second level heading, and another sentence. Be sure to include both bolded text and italicized text in the document.
You can easily create two types of lists in Markdown: unordered and ordered, both of which can be nested. To make a simple unordered list, we simply prefix the list entries (that is a line) by a single asterisk *, dash -, or plus + character. To create a nested list, you indent the nested list by one or more spaces. For consistency, I prefer to use the dash - character to indicate unordered lists. For example, the following Markdown:
- Item 1
- Item 2
- Item 2.1
- Item 2.2
- Item 3will produce the following list:
Ordered lists are similar, but are prefixed by numbers and a period, for example 1. for the first item. The Markdown numbers used to indicate list items do not have to start at one, nor must they be sequential. As an example, the text generated from the following Markdown will be formatted to begin at one and proceed sequentially.
2. Item 1
4. Item 2
1. Item 3will produce the following list:
One of the most useful features of Markdown is the ability to include formatted code directly in the text. Code elements can be included in two manners: inline and block. Inline code elements are simply wrapped in single starting quote ` characters (also called tick marks). For example, the Markdown `print("Hello World!")` renders as print("Hello World!"). Code blocks can also be placed on a single line with no quote characters by indenting the line four characters:
print("Hello World!")For longer code blocks, you can enclose the block in three single quote characters ```. For example, the following code block in Markdown:
markdown
\`\`\`
x = 3
y = 4
z = 5
print("%b" % (x\*\*2 + y\*\*2 = z\*\*2)
\`\`\`will produce the following code block:
x = 3
y = 4
z = 5
print("%b" % (x**2 + y**2 = z**2)You also can use what is known as Github flavored Markdown to indicate the target program language by adding the language name after the initial three single quote characters. For example, to indicate Python, you would use ```python, while to indicate Javascript, you would use ```javascript. For example, applying this to the previous example produces the syntax-highlighted version:
x = 3
y = 4
z = 5
print("%b" % (x**2 + y**2 = z**2)
You also can write quoted text by prefixing the line with a greater-than > character. You can also write multi-line block quoted text by prefixing every line with a greater-than > character. For example, the following Markdown:
\> Here is a long line of text
\> that we wrapped over multiple lines by inserting a Markdown line break
\> that is of course multiple space characters inserted at the end
\> of a line.will produce the following formatted text:
Here is a long line of text
that we wrapped over multiple lines by inserting a Markdown line break
that is of course multiple space characters inserted at the end
of a line.
For more detailed discussion, look at the official Markdown documentation.
Student Exercise
In the empty Markdown cell below, write a Markdown formatted document that includes an unordered list, an ordered list, a quotation, and a simple python script (you can copy the previous Python script from this notebook).
We can include detailed math formulae in a markdown call by using LaTeX, a general purpose text formatting language that is commonly used in academia for scientific articles. LaTeX can be difficult to master but is fairly simple for writing simple math formulae. The LaTeX formulae are translated for display in a web browser by the MathJax Javascript display engine.
To indicate a LaTeX formulae, the simplest approach is to enclose the relevant LaTeX between dollar sign characters, $ ... $ or to make the expression appear on its own line you enclose the expression between double dollar sign characters, $$ ... $$. Many specific functions or math symbols are prefixed with a forward slash character, \. For example, to write the LaTeX formulae for lowercase Greek character theta, you would write $\theta$. The support for mathematical expressions in LaTeX is quite extensive, and there are tools, such as LaTeXit or browser add-ons that can help build and test LaTeX expressions.
For example, the LaTeX expression
$\int_0^{\pi} \sin(\theta)\ d\theta = 2$is translated into
$\int_0^{\pi} \sin(\theta)\ d\theta = 2$
in an IPython markdown cell by MathJaX.
LaTeX can also be used in code blocks to provide cleaner or more descriptive plot labels (for example, theta versus $\theta$).
The following links are to additional documentation that you might find helpful in learning this material. Reading these web-accessible documents is completely optional.
© 2017: Robert J. Brunner at the University of Illinois.
This notebook is released under the Creative Commons license CC BY-NC-SA 4.0. Any reproduction, adaptation, distribution, dissemination or making available of this notebook for commercial use is not allowed unless authorized in writing by the copyright holder.