Markdown 教学速成：从零到能写

Markdown 是一种「用纯文本标记格式」的写法：用几个符号表示标题、加粗、列表，剩下的交给渲染器。本教程每一节都是先看写法、再看效果——写法放在代码框里，效果紧跟在下面。

一、标题与段落

写法（# 的数量决定层级）：

# 一级标题
## 二级标题
### 三级标题

空一行分段。一行写不完的句子
直接换行写，会被合成同一段。

效果（本页的标题就是这么写的）。段落之间必须空一行，只按回车不会分段。

二、文字样式

写法：

**粗体**  *斜体*  ***粗斜体***
~~删除线~~  ==高亮==  `行内代码`

效果：粗体、斜体、粗斜体、删除线、高亮、行内代码。

三、列表

写法：

- 无序列表用减号
  - 缩进两格是嵌套
    - 还能再嵌

1. 有序列表用数字
2. 顺序号其实随便写
3. 渲染时会自动重排

- [ ] 任务列表：没做完
- [x] 任务列表：已完成

效果：

• 无序列表用减号
  • 缩进两格是嵌套
    • 还能再嵌

1. 有序列表用数字
2. 顺序号其实随便写
3. 渲染时会自动重排

• 任务列表：没做完
• 任务列表：已完成

四、引用与分隔线

写法：

> 一层引用
> > 嵌套引用也支持

---

三个减号是分隔线

效果：

一层引用

嵌套引用也支持

五、链接与图片

写法：

[链接文字](https://example.com)
![图片描述](图片地址.jpg)
<https://example.com>  自动链接

效果：https://www.markdownguide.org 是一份不错的外部参考。

六、代码块与语言标签

写法：三个反引号开头，后面跟语言名（如 ```php），结尾再三个反引号：

```php
function hello(string $name): string {
    return "Hello, {$name}!";
}
```

效果：

function hello(string $name): string {
    return "Hello, {$name}!";
}

带语言名的代码块会自动高亮并显示语言标签；代码很长时默认折叠，点右上角展开。

七、表格

写法（第二行的横线可以加 : 控制对齐）：

| 语法 | 记号 | 难度 |
|:-----|-----:|:----:|
| 加粗 | `**` | 易 |
| 表格 | `\|` | 中 |

效果：

八、脚注

写法：

这句话有个注脚[^1]，还有个长注脚[^long]。

[^1]: 注脚内容会沉到页尾，点编号可跳。
[^long]: 注脚支持多行，正文里只显示序号。

效果：Markdown 由 John Gruber 发布¹，如今已是技术写作的事实标准²。

九、数学公式

写法：行内用 $...$，独立成块用 $$...$$：

质能方程 $E = mc^2$ 是行内的。

$$
\int_{a}^{b} f(x)\,dx = F(b) - F(a)
$$

效果：质能方程 $E = mc^2$ 是行内的。

十、Mermaid 图

写法：代码块的语言写 mermaid：

```mermaid
graph LR
    A[写 Markdown] --> B{有图?}
    B -->|有| C[mermaid 渲染]
    B -->|无| D[纯文字也很好]
```

效果：

十一、原生 HTML / SVG

Markdown 渲染不完的，直接写 HTML——SVG 原样直通：

<svg width="200" height="40" xmlns="http://www.w3.org/2000/svg">
  <rect width="200" height="40" rx="20" fill="#9a6b3f"/>
  <text x="100" y="26" text-anchor="middle" fill="#fff" font-size="16">原生 SVG</text>
</svg>

十二、站内链接（本站特性）

写法：双中括号里写目标页面的 slug（URL 名，即 front matter 里的 slug: 或文件名去掉扩展名），不是页面标题——标题会重名，slug 全站唯一：

演示页见 [[markdown-syntax-demo]]。
自定义文字用竖线：[[markdown-syntax-demo|看这份语法演示]]。
指向书里的某一章：[[book的slug:章节slug]]。

效果：演示页见 Markdown 新语法全览，也可以 看这份语法演示。

链接目标没写对时会渲染成灰色的 [[目标]] 并提示「找不到目标」，发布前扫一眼就能发现。

速查表

记不住就收藏这页——写作时照着抄即可。