Markdown Cells
Markdown cells are how notebooks communicate: headings, narrative, lists, tables, math, and embedded images. Since notebooks double as reports, the quality of your Markdown determines whether a reader can follow your analysis without running a single cell.
Core Markdown
# Heading 1
## Heading 2
**bold**, *italic*, `code`
- list item
1. numbered item
[link text](https://jupyter.org)
> blockquote for a calloutTables
| Model | Accuracy | Notes |
|-------|----------|-------|
| Baseline | 0.71 | simple |
| Tuned | 0.83 | + features |Math with LaTeX
Inline math is $...$; display math is a line starting and ending with $$:
The loss is $L = \frac{1}{n} \sum (y - \hat{y})^2$.
$$\nabla_\theta L(\theta)$$Embedding Images
Paths are relative to the notebook file. For plots you generate in code, save to a file first (plt.savefig("output/plot.png")) and reference it.
Letting Code Render Directly
You do not need files for many outputs: code cells can produce rich output that behaves like embedded content. For example, returning a matplotlib figure from the last expression of a cell renders it inline, and pandas DataFrames render as styled HTML tables automatically.
Best Practices
- Title the notebook and write a one-paragraph summary at the top.
- Use headings to create a table of contents a reader can skim.
- Explain decisions in Markdown, not only in code comments - comments are easy to miss.
- Keep claims near their evidence: a table cell next to the code that produced it.
Summary
Write structure in Markdown: headings for a skimmable outline, tables for results, LaTeX for math, and image references for saved plots. Let code cells render DataFrames and figures directly, and treat the Markdown as the narrative spine of the report - a good notebook reads like a paper with live exhibits.