Markdown 单元格的魔力
Markdown 单元格让你的 Notebook 变成一份完整的报告。Jupyter 使用 CommonMark 规范的 Markdown,并额外支持 MathJax 数学公式渲染。
双击渲染后的 Markdown 单元格进入编辑模式;按 Shift+Enter 或 Ctrl+Enter 渲染。
标题与分节
# 一级标题(对应 <h1>)
## 二级标题
### 三级标题
#### 四级标题
TIP
在 Notebook 中,约定使用
# 一级标题作为整个笔记本的主标题,## 作为各节标题,### 作为小节标题。良好的标题结构会让 Notebook 自动生成目录(使用 nbconvert 导出时)。
文字格式
**粗体文字** → 粗体文字 *斜体文字* → 斜体文字 ***粗斜体*** → 粗斜体 ~~删除线~~ → ~~删除线~~ `行内代码` → 等宽字体代码 > 块引用 → 缩进的引用块
列表
# 无序列表(- 或 * 或 +) - Python - NumPy - ndarray - broadcasting - pandas # 有序列表 1. 安装 Jupyter 2. 启动服务器 3. 创建 Notebook 1. 选择 Kernel 2. 开始编码
代码块
```python import numpy as np arr = np.array([1, 2, 3, 4, 5]) print(arr.mean()) # 3.0 ``` ```bash pip install notebook jupyter notebook ```
INFO
代码块中指定语言名称(
python、bash、sql 等)可以启用语法高亮,让 Notebook 导出为 HTML 时代码更美观。
表格
| 语言 | 创建年份 | 主要用途 |
|------------|----------|-------------|
| Python | 1991 | 数据科学 |
| R | 1993 | 统计分析 |
| Julia | 2012 | 科学计算 |
# 对齐控制:
| 左对齐 | 居中对齐 | 右对齐 |
|:--------|:---------:|-------:|
| 内容 | 内容 | 内容 |
链接与图片
# 超链接 [Jupyter 官网](https://jupyter.org) # 插入图片(本地或网络)  # 也可以用 HTML 控制大小 <img src="plot.png" width="400">
HTML 混用
Markdown 单元格支持直接嵌入 HTML:
<div style="background: #fff3cd; padding: 1rem; border-radius: 8px;"> <strong>注意:</strong> 这是一个自定义样式的提示框。 </div> <details> <summary>点击展开详情</summary> 这里是折叠的内容。 </details>
LaTeX 数学公式
Jupyter 集成了 MathJax 渲染引擎,支持完整的 LaTeX 数学语法。
Jupyter 中渲染的 LaTeX 数学公式:积分公式、标准差公式,效果与 LaTeX 文档相当
行内公式(Inline Math)
用单个美元符号 $...$ 包裹,与文字混排:
爱因斯坦质能公式 $E = mc^2$ 是物理学的基础。
当 $x > 0$ 时,$f(x) = \sqrt{x}$ 的导数为 $f'(x) = \frac{1}{2\sqrt{x}}$。
独立公式(Display Math)
用双美元符号 $$...$$ 包裹,独占一行居中显示:
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
$$\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i - \mu)^2}$$
$$\hat{\beta} = (X^TX)^{-1}X^Ty$$
常用 LaTeX 符号速查
| LaTeX 代码 | 含义 | 渲染效果描述 |
|---|---|---|
x^2 | 上标(幂) | x² |
x_i | 下标 | xᵢ |
\frac{a}{b} | 分数 | a/b(分式形式) |
\sqrt{x} | 平方根 | √x |
\sum_{i=1}^{n} | 求和符号 | Σ(带上下标) |
\int_a^b | 积分符号 | ∫(带上下限) |
\lim_{x \to 0} | 极限符号 | lim(带趋向) |
\alpha, \beta, \gamma | 希腊字母 | α β γ |
\infty | 无穷大 | ∞ |
\neq, \leq, \geq | 不等号 | ≠ ≤ ≥ |
\cdot, \times | 乘号 | · × |
\mathbf{A} | 粗体(矩阵) | A |
矩阵
$$A = \begin{pmatrix}
a_{11} & a_{12} & a_{13} \\
a_{21} & a_{22} & a_{23} \\
a_{31} & a_{32} & a_{33}
\end{pmatrix}$$
# 行列式(方括号边框)
$$\det(A) = \begin{vmatrix}
a & b \\
c & d
\end{vmatrix} = ad - bc$$
分段函数
$$f(x) = \begin{cases}
x^2 & \text{if } x \geq 0 \\
-x^2 & \text{if } x < 0
\end{cases}$$
WARNING
在 Markdown 单元格中,
_(下划线)既是 Markdown 斜体标记,也是 LaTeX 下标标记,可能产生冲突。如果公式中包含多个下划线,推荐将整个公式放在 $...$ 中,或用 \text{} 包裹文字部分。
在 Code 单元格中用 Python 生成 Markdown/LaTeX
有时需要动态生成 Markdown 或 LaTeX 内容(比如根据数据自动填写报告):
from IPython.display import display, Markdown, Latex # 动态生成 Markdown mean = 42.7 std = 3.2 display(Markdown(f"## 统计结果\n均值 = **{mean}**,标准差 = **{std}**")) # 动态生成 LaTeX 公式 display(Latex(r"$$\bar{x} = " + str(mean) + r"$$")) # 生成完整的 HTML 报告片段 from IPython.display import HTML display(HTML(f""" <div style="border-left: 4px solid #f37626; padding: 1rem;"> <strong>分析结论:</strong> 数据均值为 {mean}, 置信区间为 [{mean-2*std:.1f}, {mean+2*std:.1f}] </div> """))
报告型 Notebook 的技巧
对于需要发布为报告的 Notebook,推荐将计算结果存入变量,然后在 Markdown 单元格中用 Python 变量插值({变量名})。但注意:Markdown 单元格本身不执行 Python 代码,只有 Code 单元格配合 display(Markdown(f"...")) 才能实现动态内容。另一个方法是用 papermill 参数化整个 Notebook(见第10章)。
MathJax 的工作原理
MathJax 是什么
MathJax 是一个 JavaScript 库,Jupyter 在浏览器端用它将 LaTeX 数学代码渲染为 SVG 或 HTML。当你输入 $E=mc^2$ 时,MathJax 扫描 Markdown 内容,找到 $ 或 $$ 分隔符,将内部 LaTeX 代码转换为可视化的数学公式。离线环境下(MathJax CDN 不可用时)公式无法渲染,离线使用需要配置本地 MathJax 路径。
$ 与 $$ 的使用场景
行内公式 ($...$) 用于文字中嵌入简短公式,公式与周围文字基线对齐,字体相对较小,适合描述性公式("当 $x > 0$ 时")。独立公式 ($$...$$) 独占一行,居中显示,公式大小正常,适合推导过程和重要公式(便于读者聚焦)。
Markdown 与 LaTeX 的字符冲突
Markdown 用 _ 表示斜体,LaTeX 用 _ 表示下标;两者共存时 Markdown 解析器可能先于 MathJax 处理 _ 符号,导致渲染异常。解决方法:将含有 _ 的公式完整用 $ 包裹;若仍有问题,用 \_ 转义 Markdown 中的下划线,或将整个 Markdown 单元格改用原始 HTML 混合 MathJax 的方式。
高级 Markdown 技巧
任务列表(Task Lists)
用 - [ ] 和 - [x] 创建可勾选的任务列表,适合项目管理型 Notebook。示例:
- [ ] 数据清洗、- [x] 特征工程、- [ ] 模型训练。注意:Jupyter 的 Markdown 渲染任务列表为静态文本(不可交互点击),但导出为 HTML 后可以用 CSS 美化。脚注(Footnotes)
用 [^1] 标记脚注引用,在文档末尾用 [^1]: 内容 定义脚注。示例:
这是一个重要结论[^1],然后在单元格末尾 [^1]: 参考论文 Smith et al. 2023。Jupyter 的 Markdown 解析器对脚注支持有限,复杂脚注建议用 HTML 的 <sup> 标签手动实现。折叠内容(Collapsible Sections)
用 HTML 的 <details> 和 <summary> 标签创建可折叠区域,隐藏次要信息。示例:
<details><summary>点击展开详细推导</summary>...长公式...</details>。这在教学 Notebook 中非常有用,让学生先看结论,需要时再展开细节。本章小结
本章核心要点
- Markdown 语法速查:# 标题、**粗体**、*斜体*、`代码`、```代码块```、- 列表、| 表格、[链接](url)、。Jupyter 的 Markdown 支持完整 CommonMark 规范加上 HTML 扩展。
- LaTeX 公式格式:行内公式 $...$(与文字混排);独立公式 $$...$$(独占一行居中)。MathJax 负责在浏览器端渲染,离线时需要本地 MathJax。
- 常用 LaTeX 符号:x^2 上标、x_i 下标、\frac{a}{b} 分数、\sqrt{x} 根号、\sum 求和、\int 积分、\alpha\beta\gamma 希腊字母。矩阵用 \begin{pmatrix}...\end{pmatrix};分段函数用 \begin{cases}...\end{cases}。
- HTML 嵌入:Markdown 单元格支持直接写 HTML,用于实现 Markdown 语法无法表达的样式(彩色文字、自定义警告框、内嵌 CSS)。滥用 HTML 会降低 Notebook 的可移植性,优先用 Markdown 语法。
- 字符冲突处理:Markdown 的 _ 和 LaTeX 的 _ 可能冲突,将公式内容完整用 $ 包裹可避免解析歧义;公式不渲染时先检查 $ 是否配对,再检查 MathJax 是否加载(查看浏览器控制台)。