Writing notes in Markdown

How to format the notes in your notebooks: headings, lists, emphasis, and code, plus what makes notes useful.

The notes in your notebooks go in Markdown cells. Markdown is a simple way to format text with ordinary characters: you type a few symbols, and when you run the cell with shift + return (shift + enter on Windows) they turn into formatting. You write Markdown in many places besides notebooks, including README files on GitHub. This page covers what you will need.

The basics

You type You get
# Title a large heading
## Section a smaller heading (use more # for smaller headings)
*italic* italic
**bold** bold
`len(words)` len(words), formatted as code
[NSIDC](https://nsidc.org) a link: NSIDC

Leave a blank line between paragraphs. A single line break without a blank line does not start a new paragraph.

Lists

Start each item of a bulleted list with a dash and a space, and each item of a numbered list with a number and a period. Leave a blank line before the list.

Things I noticed:

- The first word is 'twinkle,' with a comma.
- Slices stop before the second number.

1. Read the file.
2. Split it into words.

Code and output

To show a few lines of code in a Markdown cell (for example, code you tried that did not work), put three backticks on the line before and the line after:

```python
words.count("twinkle")
```

Math

Put math between dollar signs, as in $R^2 = 0.80$, which shows as \(R^2 = 0.80\).

What makes notes useful

Your notebook should make sense to someone who was not in class, and to you in a few weeks.

  • Start with an introduction. Begin the notebook with a title and a few sentences on what data you are using and what you are trying to find out.
  • Explain code in your own words, especially anything new or confusing. Writing an explanation shows you which parts you do not understand yet.
  • Explain what each result means. After a plot or a number, add a sentence or two. What does it show, and is it what you expected?
  • Record your questions. If something is still confusing, write it down so you can ask about it.
  • Do not copy the tutorial’s words. The tutorial and your notebook have different purposes. Headings that follow the tutorial’s are fine, but the explanations should be yours.

For more, see GitHub’s guide to basic writing and formatting syntax.

Back to top