Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 39 ยท Cells and Magics

Cell Types and Markdown

Write documentation in Jupyter Markdown cells: headings, emphasis, lists, tables, code blocks, links, images, LaTeX math with MathJax, HTML, and raw cells explained.

Code tells a computer what to do; Markdown tells a human why. A notebook with only code cells is hard to follow, while one with a clear heading, a sentence of context before each step, and a short conclusion becomes a document people can read and trust. Markdown cells are how you write that text, and they support formatting, tables, links, images and mathematical formulas.

Jupyter has three cell types:

Type Use
Code Source run by the kernel. Its output is stored below it.
Markdown Formatted text; rendered when you run the cell.
Raw Text kept exactly as typed; ignored by Jupyter, but passed to converters such as nbconvert (for example to insert raw LaTeX in a PDF export).

Change a cell's type from the toolbar drop-down, or press M (Markdown), Y (code) in command mode. To edit a rendered Markdown cell, double-click it or press Enter; run it with Shift+Enter to render again.

The Markdown flavour in Jupyter is CommonMark with GitHub-style tables and a few extras. Our runnable stand-ins implement tiny pieces of a converter, just to show what happens. They are not a full Markdown engine.

Headings, emphasis and lists

MARKDOWN
# Title (level 1)
## Section (level 2)
### Subsection (level 3)

This is **bold**, this is *italic*, this is ~~struck~~, and this is `inline code`.

1. First step
2. Second step
   - A nested bullet
   - Another

- [ ] An unchecked task item
- [x] A done item

> A quotation or a highlighted remark.

Use headings consistently: JupyterLab builds a table of contents panel from them, and nbconvert makes HTML anchors from them. Start the notebook with one level-1 heading, then use level 2 for the main parts.

MARKDOWN
[Project page](https://example.com/project)        <- a link
[See the cleaning section](#Data-cleaning)         <- link to a heading in the same notebook
![Chart of sales](images/sales.png)                <- an image next to the notebook
  • Heading links use # plus the heading text with spaces replaced by hyphens.
  • Images are normally files in a folder next to the notebook. Paths are relative, so keep the folder with the notebook when you share it. You can also paste or drag an image into a Markdown cell: Jupyter stores it as an attachment inside the .ipynb (base64, in the cell's attachments), so it travels inside the file, but it grows the file.
  • Fenced code blocks show code without running it. Put the language after the opening fence:
MARKDOWN
```python
def greet(name):
    return f"Hello, {name}!"
```

Tables

MARKDOWN
| Model | Accuracy | Notes |
| ----- | -------: | :---- |
| Linear | 0.81 | baseline |
| Forest | 0.88 | slower |

Colons in the separator row set alignment: :--- left, :---: centre, ---: right. For large tables, generate them from data (see Tables and DataFrame display) instead of typing.

Maths with LaTeX

Jupyter renders mathematics with MathJax. Put inline formulas between single dollar signs and display (centred) formulas between double dollar signs:

MARKDOWN
The mean is $\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i$.

$$
\sigma^2 = \frac{1}{n}\sum_{i=1}^{n}(x_i - \bar{x})^2
$$

Common LaTeX pieces: \frac{a}{b}, x^2, x_i, \sqrt{x}, \sum, \int, Greek letters like \alpha and \beta, and matrices with \begin{bmatrix} ... \end{bmatrix}. A dollar sign meant as money needs a backslash: \$5.

The stand-in below scans text for the maths spans, the first step a renderer takes:

Python Stand-in: find the math in a Markdown cell

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

HTML inside Markdown

Markdown allows raw HTML when you need something it cannot do:

MARKDOWN
<span style="color: crimson">Careful</span> with this step.

<details><summary>Show the formula</summary>

$E = mc^2$

</details>

<details> creates a collapsible section; keep blank lines around the content so Markdown inside renders. Scripts do not run in Markdown cells (Jupyter sanitises them), and heavy HTML makes notebooks hard to read as plain text, so use it sparingly.

Callouts and conventions

There is no built-in "warning box", but a quotation with an emoji or bold label is widely understood:

MARKDOWN
> **Warning:** this cell overwrites `clean.csv`.

Good practice: start each section with one or two sentences saying what the next cells do and what you expect to learn, and end with what you actually found. Keep paragraphs short, since notebooks are read on screens.

A tiny Markdown converter

To demystify rendering, this stand-in turns a small Markdown subset into HTML. Real converters handle far more cases, but the idea is the same: recognise line patterns, then inline patterns.

Python Stand-in: a mini Markdown to HTML converter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Raw cells and exporting

A raw cell is never rendered or executed. It matters when you convert the notebook: for example, a raw cell with the format set to LaTeX is copied verbatim into the LaTeX output of nbconvert. Set the format with the cell metadata (View โ†’ Cell tools in the classic app). You will rarely use raw cells, but now you know why they exist.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which key turns the selected cell into a Markdown cell in command mode?

    M switches to Markdown, Y back to code, and R to raw.
  2. 2. How do you write a centred, display-style formula?

    $$ ... $$ produces a display equation; single dollars give inline math.
  3. 3. Where do images pasted into a Markdown cell end up?

    Pasted images become base64 attachments stored in the cell, so the file carries them but grows.
  4. 4. What is a raw cell for?

    Raw cells are neither rendered nor executed; converters can embed their content as-is.

Summary

  • Notebooks have code, Markdown and raw cells; M, Y and R switch the type.
  • Markdown gives headings, emphasis, lists, tables, links, fenced code and images.
  • Math uses LaTeX between $...$ (inline) and $$...$$ (display), rendered by MathJax.
  • Headings build the table of contents; keep a clear level-1 title and level-2 sections.
  • Raw HTML works for small needs but scripts are not executed.
  • Explain intent before each step and state the finding afterwards.

Next: Line and cell magics