5  Markdown

5.1 何谓 Markdown？

Markdown 是一种轻量级的标记语言，允许你使用易读易写的纯文本格式编写文档，然后转换成结构化的 HTML, PDF, Word 等多种格式的文档。Markdown 语法简单易学，适合用来撰写笔记、文档、幻灯片等。

大家在网上看到的很多博客文章，程序说明文档，甚至是在线书籍 (Python for Data Analysis, 3E)，都是用 Markdown 写的。

5.2 语法速览

Figure 5.1: Markdown 语法对照

你可以在如下网站按部就班地学习 Markdown 的基本用法，大概五分钟后你就可以掌握常用 Markdown 语法规则了：

5.3 Markdown 基本语法

Source: markdownguide.org/cheat-sheet/

这份 Markdown 备忘单介绍了常用的 Markdown 语法。为了便于您快速了解基本的语法规则，这里略去了很多细节信息，详情参见：基础语法 和 扩展语法。

以下是 John Gruber 原始设计文档中列出的基本元素，所有 Markdown 应用程序都支持这些元素。

元素 Markdown 语法
标题 # 一级标题
## 二级标题
### 三级标题
粗体 **粗体文本**
斜体 *斜体文本*
引用块 > 引用内容
有序列表 1. 第一项
2. 第二项
3. 第三项
无序列表 - 第一项
  - 第一条
- 第二项
- 第三项
代码高亮显示 `代码` (`xtreg` → xtreg)
水平线 ---
链接 [连享会主页](https://www.lianxh.cn)
图片 ![图片标题](/Fig/image.jpg) 或 ![](图片网址)

5.3.1 表格

| 命令    | 范例                 |
| :------ | :------------------- |
| xtreg   | `xtreg y x, fe`      |
| reghdfe | `reghdfe y x, a(id)` |
命令 范例
xtreg xtreg y x, fe
reghdfe reghdfe y x, a(id)

5.3.2 数学公式

  • 单行数学公式用 $$ 符号包围起来；
  • 行内数学公式用 $ 符号包围起来；
  • 包围符号内侧不要有空格，否则在有些 Markdown 编辑器中无法正常显示公式
    • 正确：$y = f(x)$
    • 错误：$ y = f(x) $ 或 $y = f(x) $
  • 有关 LaTeX 数学公式的语法和工具，参见： 
模型设定为：

$$y_{it} = \alpha_i + x_{it}\beta + u_{it}$$

其中，$y_{it}$ 为被解释变量，$\alpha_i$ 为个体效应。

模型设定为：

\[y_{it} = \alpha_i + x_{it}\beta + u_{it}\]

其中，\(y_{it}\) 为被解释变量，\(\alpha_i\) 为个体效应。

5.3.3 代码块

```python
import pandas as pd

df = pd.DataFrame({
    'A': [1, 2, 3],
    'B': [4, 5, 6]
})
```

```stata
sysuse "auto.dta", clear
regress mpg weight
display "Results: " 2 + 3
```

渲染效果：

import pandas as pd

df = pd.DataFrame({
    'A': [1, 2, 3],
    'B': [4, 5, 6]
})
sysuse "auto.dta", clear
regress mpg weight
display "Results: " 2 + 3

5.3.4 输出为 PDF 或 HTML 文档

虽然 VScode 中有些插件 (如 Markdown PDF) 可以将 Markdown 文档直接导出为 PDF 或 HTML，但不够美观。我建议两种方法：

  • 使用 https://md.doocs.org/：你只需把 Markdown 文档复制粘贴到该网站的编辑器中，就可以一键导出 PDF 或 HTML 文档了。点击右上角的「样式」按钮，你还可以选择不同的文档样式，满足不同的需求。
  • 对于排版要求较高的用户，可以考虑使用 Quarto，它是一个功能强大的文档编译工具，支持将 Markdown 文档转换为多种格式，包括 PDF、HTML、Word 等。使用 Quarto，你可以轻松地将 Markdown 文档编译成专业的报告、论文或幻灯片。

5.3.5 扩展阅读

5.4 Marp 幻灯片

有关 Marp 幻灯片的详情可以参考： 连玉君，2026. Marp 幻灯片指南. 在线版, PDF, GitHub

在 VScode 中安装 Marp 插件后，你可以使用 Markdown 语法来创建幻灯片。使用 Marp 最大的好处是你可以专注于内容，而不必担心幻灯片的格式和样式。Marp 会自动将你的 Markdown 文档转换为美观的幻灯片。

5.4.1 安装

1. VScode 编辑器

2. Marp 插件 - 在 VScode 中打开扩展市场，搜索 Marp for VS Code，点击安装。

3. 如需使用 PDF 导出功能，还需要安装 Marp CLI： - 打开终端 (TERMINAL)：在 VScode 中，点击左侧活动栏的终端图标，或使用快捷键 Ctrl + ~（反引号）打开终端。 - 在终端中运行以下命令安装 Marp CLI： bash npm install -g @marp-team/marp-cli

扩展阅读：

5.5 用 Markdown 编写个人网站和简历

使用 Markdown 语法，你可以轻松地创建个人网站和简历。

你可以参考如下推文，轻松创建个人主页 (无需购买域名，也无需学习 HTML 和 CSS)：

Markdown 也可以用来制作简历，参见：