7  Markdown

7.1 何谓 Markdown？

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

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

7.2 语法速览

Figure 7.1: Markdown 语法对照

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

7.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) 或 ![](图片网址)

7.3.1 表格

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

7.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\) 为个体效应。

7.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

7.3.4 输出为 PDF 或 HTML 文档

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

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

7.3.5 扩展阅读

7.4 Marp 幻灯片

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

7.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

扩展阅读：

7.4.2 模版 1：最基本的设定

以下是一个简单的 Marp 幻灯片模板，你只需要新建一个 .md 文件，输入如下内容，然后在 VScode 中打开该文件即可：

---
marp: true
---

# 幻灯片标题

---

## 第一页幻灯片

- xxx
- xxx

---

## 第二页幻灯片

- xxx
- xxx

7.4.3 模版 2：更多的设定

该模板的主要功能包括：
  • 幻灯片的标题、作者、页码、脚注
  • 自定义幻灯片的正文字号
  • 标题的颜色和页面背景颜色
---
marp: true
theme: default
size: 16:9
paginate: true
lang: zh-CN
math: mathjax
header: '[lianxh.cn](https://www.lianxh.cn/news/46917f1076104.html)'
footer: '[lianxh.cn](https://www.lianxh.cn) | [Books](https://www.lianxh.cn/Books.html)'
style: |
  section {
    font-family: "Microsoft YaHei", "PingFang SC", sans-serif;
    font-size: 22px;
    line-height: 1.45;
    padding: 48px 56px 40px 56px;
  }
  h1 { color: #222; font-size: 34px; }
  h2 { color: #1f7a1f; font-size: 30px; }
  h3 { color: #1f4e79; font-size: 26px; }
  pre { font-size: 20px; }
  section::after {
    content: attr(data-marpit-pagination) '/' attr(data-marpit-pagination-total);
    font-size: 14px;
  }
---

<!-- _headingDivider: 2 -->

---
<!-- backgroundColor: #FFFFF9 -->
## 第一页幻灯片

- 背景是淡黄色的，可以根据需要修改颜色

---
<!-- backgroundColor:white -->
## 第二页幻灯片

- 背景是纯白色
- 下面的图片在右侧，占页面 60% 的宽度

![bg right:60% w:800](图片网址)

详情参见：

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

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

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

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