# Markdown

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/](/topics/markdown-intro/slides/).

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

| where | what it is |
|---|---|
| **A markdown cell in a notebook** | where you state what a number means, and what you checked |
| **`README.md`** | the front page of your repository, rendered by GitHub for anybody who opens it |
| **A project write-up** | whatever its spec asks for, such as the section headed *How I know these numbers are right* |

## Everything you need

```markdown
# 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.**

```markdown
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 price*quantity*days, 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:

```python
@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:

```markdown
# 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](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for what GitHub itself supports
- [CommonMark](https://commonmark.org/help/) for a ten-minute interactive tutorial