Markdown

On this page

1. Everything you need
2. What goes wrong
3. In a notebook
4. On GitHub
5. Where to check yourself
6. Learn more

Markdown is plain text with a few marks in it that a renderer turns into headings, lists and tables. You already write it, in Slack and in Teams and anywhere a **bold** came out bold. The slides on it are at /topics/markdown-intro/slides/.

In this course you write it in these places, and a project's spec may name others.

Everything you need#

# A heading
## A smaller heading

Ordinary text. A blank line starts a new paragraph.

**Bold** and *italic*.

- a bullet
- another bullet

1. a numbered item
2. the next one

[A link](https://example.com)

`inline code`, for a column name like `OrderDate`

​```python
freight = 16.75
​```

| a | table |
|---|---|
| one | row |

> A quotation, or a note you want set apart.

That is the whole set. The rest of this page is what goes wrong.

What goes wrong#

Every one of these renders without an error. Nothing tells you. The first person to notice is whoever reads it.

A numbered list counts from its first number.

Top countries by revenue:

1. Belgium
3. Brazil
2. Germany

That renders as 1. Belgium, 2. Brazil, 3. Germany. The numbers after the first one are ignored, so put the lines in the order you mean.

One newline is not a line break. Two lines of text with a single newline between them become one line. To break a line without starting a paragraph, end the first line with two spaces, or leave a blank line and accept the paragraph.

Asterisks inside a word turn into italics. price*quantity*days comes out as pricequantitydays, silently, with the asterisks gone. Wrap anything that is code in backticks and the problem disappears: `price*quantity*days`.

A fenced block wants its language. ```python gets you syntax highlighting in both GitHub and marimo. A bare ``` gets you grey text.

A table needs the separator row. The |---|---| line under the header is what makes it a table. Without it you get a paragraph full of pipes.

In a notebook#

Add a cell, choose markdown, and type. That is the whole of it. Start headings inside a cell at ##, because the notebook already has a title.

You will meet the machinery when you read the file. A marimo notebook is a .py, so when you open one in VS Code, or look at a diff on GitHub, your paragraph appears like this:

@app.cell(hide_code=True)
def _(mo):
    mo.md(r"""
    ## Order 10248

    Freight is **16.75** and it belongs to no category, so splitting it across
    the three lines is a decision rather than a calculation.
    """)
    return

marimo wrote every character of that around your text. hide_code=True is why you see the prose and not the wrapper. The r before the quotes is why a Windows path like C:\Users\you survives instead of turning into an escape character.

You never type any of it. It is here so that the file makes sense the first time you read one.

On GitHub#

GitHub renders README.md on the front page of your repository. It is the first thing anybody sees, including me, and it costs about four lines:

# Coursework

Notebooks and data from this course, with one notebook per session.

- `notebooks/` one file per session
- `data/` files the notebooks read

GitHub also renders a .md file anywhere in the repository when you click on it, which is why a memo committed as memo.md reads properly and the same memo pasted into a text box does not.

Where to check yourself#

Preview it before you commit. In VS Code, press Ctrl+K and then V on Windows, or Cmd+K and then V on macOS, to open a preview beside your file. Ctrl+Shift+V (Cmd+Shift+V on macOS) turns the tab itself into the preview. In a notebook, run the cell. On GitHub, look at the file after you push.

If it looks wrong in the preview it will look wrong to a reader, and that is the whole reason to look.

Learn more#

• GitHub's markdown guide for what GitHub itself supports
• CommonMark for a ten-minute interactive tutorial

Last updated: Sunday, 11/1/2026