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 plain text in a readme or notebook formatting.

Using markdown in README files¶

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

• Scroll down and look at the readme for this repo or this repo. You can see that there is bolded and italics text, code, hyperlinks, and headers for sectioning. There is a lot more you can do with Markdown, but that will give you a taste.
• This is the raw version of how that readme/how that file looks before Github formats it nicely.
• Compare the raw version to the formatted version. See how I added the hyperlink in the second sentence?

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.

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?

Examples¶

Switch between these tabs and compare:

{tabbed}
````text

### 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)
````

{tabbed}

<h3> How to make sections, subsections, etc </h3>

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

<h3> Bold and italics  </h3>

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!

<h3> Lists, hyperlinks, and showing code  </h3>

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)

<h3> Including pictures  </h3>

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)

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: