1.5. Markdown basics

Tip

Copy the resources below to somewhere handy in your class notes folder for quick reference, or bookmark those links. (Or, both!)

Almost all of the work in class will involve writing python files (.ipynb “notebooks”) and readmes. Any text you type in a readme or a notebook file is, by default, just plain text.

Markdown is a just way to give text in a readme or notebook formatting.

1.5.1. Using markdown in README files

GitHub automatically shows the readme on every repo with formatted markdown:

1.5.2. Using markdown in notebooks

When we work in Jupyter, we will write python code in files called python notebooks (ipynb files, for “IPYthon NoteBooks”). In these ipynb files, we can have python code interspersed with sections of markdown text. As a result, we can write code and analysis that is easy to follow and execute. In other words, ipynb files are useful to create code that is reproducible, reusable, and shareable.

1.5.3. Resources

I’ll recommend four resources to practice and learn markdown. Look at them all quickly, and you’ll have the gist in under 15 minutes:

  1. A very good markdown tutorial

  2. A good cheat sheet

  3. Github’s markdown explainer

  4. Google “How do I <do something > in markdown?

1.5.4. Examples

Switch between these tabs and compare:

### How to make sections, subsections, etc

One "#" at the start of a line makes a "title header". Two "##" means a section header, three a subsection, and so on.

### Bold and italics

For example, **to make this phrase bold**, I add two asterisks before and after it.

_Putting an underscore at the start and end of a phrase makes italics._ Easy!

### Lists, hyperlinks, and showing code

You can make lists with hyphens:
- If you want text to look like code, put it inside two backticks: `print("hello world")`
- Or, if the code is multiple lines (a "code block"), put it inside three backticks:

```python
# the "python" i put on the line above tells markdown that this code black
# should use python syntax highlighting
print("hello world")
print("why hello to you!")
```

You can make numbered lists easily:
1. Put brackets and parentheses back-to-back
2. Put the text you want in the brackets
3. And the link in the parentheses
4. [Like this](https://www.espn.com/college-football/game/_/gameId/401282781)

### Including pictures

The syntax is `![]()` and you put the path to the picture inside the parentheses.

Here is an example:

![](img/why_i_am_not_sleeping.jpg)

How to make sections, subsections, etc

One “#” at the start of a line makes a “title header”. Two “##” means a section header, three a subsection, and so on.

Bold and italics

For example, to make this phrase bold, I add two asterisks before and after it.

Putting an underscore at the start and end of a phrase makes italics. Easy!

Lists, hyperlinks, and showing code

You can make lists with hyphens:

  • If you want text to look like code, put it inside two backticks: print("hello world")

  • Or, if the code is multiple lines (a “code block”), put it inside three backticks:

# the "python" i put on the line above tells markdown that this code black
# should use python syntax highlighting
print("hello world")
print("why hello to you!")

You can make numbered lists easily:

  1. Put brackets and parentheses back-to-back

  2. Put the text you want in the brackets

  3. And the link in the parentheses

  4. Like this

Including pictures

The syntax is ![]() and you put the path to the picture inside the parentheses.

Here is an example:

1.5.5. Editing markdown files in Jupyterlab

In .ipynb files, Jupyterlab renders markdown cells nicely and easily.

If you want to edit any .md files (like “README .md” files) in Jupyterlab and see the output immediately, use this trick: