Using Markdown¶

Markdown¶

Markdown is a simple markup language. It used to write formatted text in HTML, the language of the web, but without the need to learn all of the tags involved in HTML. For example, to create large bold font like in the header above, followed by an italic word, and then a normally formatted sentence, we could write it in HTML like the following:

<h2>Markdown</h2>
<i>Markdown</i> is a simple programming language.

Or, we could write the same thing more easily using Markdown:

## Markdown 
*Markdown* is a simple programming language.

The Markdown example is easier to read and write, and describes the same rendered result as if we had written HTML.

Learning objectives¶

This tutorial is intended to refresh your memory about the usage of Markdown -- which we briefly introduced previously within a jupyter notebook -- and to provide links to further instructions that you can easily search when you need to use Markdown.

Why use markdown?¶

There are several other languages similar to markdown, such as restructuredText (rst), but markdown is generally the most popular and easy to use. Markdown is particularly useful for writing documentation, or notes about code on GitHub, since GitHub automatically renders markdown documents into rendered (formatted) text. For this reason, the README file that is standard on every GitHub repo is usually written in Markdown.

README files¶

Remember, your first GitHub tutorial (hello-world) had you create a new branch to edit the README file, and then merge that branch with your main. The README file can be used for a variety of purposes. Generally, it is meant as a place for introducing the repo -- telling visitors what the code is for, and how to use it. But you can also use it as a place to write yourself notes, or really for any purpose you want.

Learning Markdown¶

Start by reading a tutorial, and then get your hands dirty and start writing. There are many online tools where markdown text is instantly rendered side-by-side with your code, which is great for testing. Try out the following app https://stackedit.io/app. You can even use Markdown inside our course chatroom (gitter). You can learn more at the following two links:

Formatting code block with markdown:¶

You can format a code block in Markdown -- meaning that it will apply specific styling to the font and color of text to look nice for a computer language -- by writing the code inside of blocks delimited with three backticks (ignore the forward slashes below).

```python
x = 3
print(x)
```

See here for more details. Try it out in the scratchpad link above. Notice how if you change the name of the language the "syntax highlighting" can change slightly. Try the following code in the stackedit app and notice the difference when you change "language" to python, r, perl, or bash.

x = 3
y = "string"
print(x)
print(y)

You have now completed this tutorial. No assessment is required. Proceed to the next tutorial.