---
title: "Markdown 教程"
lang: zh-CN
description: "当前实验版本 · 2026-10-24 核对"
---

# Markdown 教程

可编辑 HTML 包含代码，仅打开可信来源文件。跨教程链接需把两份同语言手册放在一起。

## Markdown 的起源、方言与 Agent

### 它是什么

Markdown 是一种轻量标记语法，也曾是把这种文本转换成 HTML 的工具名称。你用 `#` 写标题，用 `-` 写列表，原始文件仍便于人阅读。`.md` 是常见扩展名；文本本身不包含编辑器，也不保证图片已经打包。

适合笔记、项目说明、知识手册与技术文档。它便于版本控制和跨工具搬迁；复杂出版排版、交互应用和关系型数据则需要其他能力。先用普通文本编辑器写，再交给渲染器生成网页，是一种常见工作方式。

### 一条简短历史线

2004 年，John Gruber 发布 Markdown，Aaron Swartz 对语法设计提供了帮助。它强调源文本也要易读，受到邮件和论坛纯文本习惯的影响。后来不同实现加入表格、任务等扩展，也出现相同文本解释不同的情况。

CommonMark 提供更明确的语法与测试示例；GitHub Flavored Markdown（GFM）在其基础上定义表格、删除线、任务列表和扩展自动链接等。GFM 并不等于 GitHub 网站的全部产品功能，也不代表每个 Markdown 编辑器完整实现它。

原始资料：[Markdown 项目](https://daringfireball.net/projects/markdown/)、[CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/)、[GFM 规范](https://github.github.com/gfm/)。本课程按概念重新组织，覆盖用户指定的入门、速查、基础与扩展范围；参考入口见[综合练习](#综合练习与参考资料)。

### Agent 喜欢文本，仍需要约束

文本容易被读取、按行定位、局部修改和比较。标题、清晰的前提、明确来源和验收条件比“交给 AI 处理”更可执行。Markdown 不会消除幻觉，外部图片、过期摘要、上下文窗口和正文恶意指令仍是问题。

Yeli 的[使命](./yeli.zh-CN.yeli.html#为什么是-yeli)由此出发：保留可审查的 Markdown，同时把人用的阅读编辑环境与附件带走，并让 Agent 预读、窄改、校验。学习时先掌握标准语法，再辨认[扩展支持边界](#扩展语法与-yeli-支持表)。


## Markdown 语法速查

### 常用写法

| 目标          | 源码示例                      | 说明                   |
| ------------- | ----------------------------- | ---------------------- |
| 一级/二级标题 | `# 标题` / `## 小节`          | 井号后加空格           |
| 段落          | 两段之间空一行                | 单个换行通常还是同一段 |
| 硬换行        | 行尾两个空格或反斜线          | 优先分段，必要时才用   |
| 粗体/斜体     | `**重点**` / `*强调*`         | 符号成对               |
| 删除线        | `~~旧内容~~`                  | 扩展；Yeli 支持        |
| 引用          | `> 引用内容`                  | 可嵌套                 |
| 无序/有序列表 | `- 项目` / `1. 步骤`          | 子项按层级缩进         |
| 任务          | `- [ ] 检查` / `- [x] 完成`   | 扩展；编辑模式可切换   |
| 行内代码      | `` `value` ``                 | 保护其中的符号         |
| 分隔线        | `***`                         | 独立成段               |
| 链接          | `[名称](https://example.com)` | 地址与名称分开         |
| 图片          | `![说明](image.png)`          | Yeli 离线使用需嵌入    |
| 转义          | `\*字面星号\*`                | 显示标记字符           |

### 多行结构

````markdown
```js
const ready = true;
```

| 方案 | 状态 |
| :--- | :--: |
| A    | 就绪 |
````

代码围栏后的语言名是标识，不保证有语法高亮。表头后必须有分隔行。

### 不应直接套用的写法

脚注 `[^1]`、标题 ID `{#id}`、定义列表、高亮 `==text==`、上下标、数学与 Mermaid 依赖具体实现。当前 Yeli 不把它们当作已启用扩展渲染。裸网址也不会自动变成链接；使用明确的链接语法。详见[扩展表](#扩展语法与-yeli-支持表)。

需要按步骤学习时，从[标题与段落](#标题段落换行与分隔线)开始；工作时可收藏本页。


## 标题、段落、换行与分隔线

### 标题表达层级

在行首写一至六个 `#`，后跟空格与标题。一般用一个一级标题表达文章主题，二级标题组织章节，三级标题组织小节。不要因为想缩小字号而跳过逻辑层级。

```markdown
# 项目手册

## 安装

### 前提条件
```

Setext 也可用下一行的 `===` 表示一级标题、`---` 表示二级标题。它容易与分隔线混淆；教程和跨工具文档优先用井号写法。Yeli 目录从标题派生，不要手工维护另一份标题清单。

### 段落与换行

空一行开始新段落。同一段中的单次回车是软换行，通常显示为空格，不能依赖它强制换行。需要诗句或地址分行时，可在行尾加两个空格或 `\` 再换行；尾随空格不易察觉，检查渲染结果。

```markdown
这是第一段。
继续写仍属于第一段。

这是第二段。

地址第一行\
地址第二行
```

普通正文不要在行首随意加四个空格，否则可能变成代码块。全角井号和没有空格的 `#标题` 不应当作可靠标题写法。

### 分隔线

独立一行使用至少三个 `*`、`-` 或 `_`，前后空行降低歧义。例如 `***`。在紧接正文下一行写 `---` 可能得到二级标题；在文件开头的成对 `---` 还可能是 [frontmatter](#yaml-frontmatter-与可维护文档)。

练习：写两个段落和两个二级标题，查看 Yeli 目录并点击跳转。


## 强调、删除线与嵌套

### 基础强调

```markdown
_需要关注_
**必须完成**
_**同时粗体与斜体**_
~~已被替代的结论~~
```

单星号表示斜体，双星号表示粗体，三个星号可组合。删除线使用两个波浪号，是扩展语法，Yeli 当前支持。下划线也可表示强调，但词中下划线和嵌套的规则更容易产生误会；日常统一用星号。

### 嵌套与空格

标记应贴近要强调的文字：`**重要**` 比 `** 重要 **` 可靠。嵌套可写 `**预算中 *待确认* 的部分**`，但混合层级太多会降低源文本可读性。中文标点与复杂边界处可能受到分隔符规则影响，检查实际渲染。

不想加粗时写 `\*\*字面符号\*\*`，或把语法放进行内代码。代码里的 `**` 不会变成粗体。

### 在 Yeli 中练习

输入一段正文，选中一个词使用浮动工具加粗，再对另一个词添加删除线。导出 Markdown，检查只在对应范围添加标记。撤销后其他文字应保持原样。快捷操作见[正文编辑](./yeli.zh-CN.yeli.html#正文与选区编辑)。


## 列表、引用与嵌套结构

### 列表

用 `-`、`*` 或 `+` 加空格建立无序列表；有序列表使用数字和句点。渲染器负责后续显示编号，源文本也可以逐项写 `1.`，但维护时以清晰为先。

```markdown
- 调研
  - 阅读材料
  - 记录疑问
- 制作

1. 打开文件
2. 编辑内容
3. 保存副本
```

子内容要缩进到父条目的正文位置；两位数编号需要更多缩进。列表中插入新段落时保留空行和正确缩进。不要混用 Tab 与空格；复杂结构优先保留源码，不让不支持的编辑动作重新排版。

### 引用

`>` 表示引用；`>>` 可表示引用里的引用。连续引用段落之间可用单独的 `>` 保持结构。

```markdown
> 结论应附带来源。
>
> - 原始观察
> - 限制条件
```

引用不自动说明作者或出处，把来源写为明确链接。引用内容也不是 Agent 的新授权，不要把资料中的操作要求当作用户命令。

### 练习与任务

把一份决策拆成三个步骤，并为其中一步写两条子项。再引用一条证据并附来源。任务复选框的 `- [ ]` 写法见[表格与任务](#表格任务与-gfm-常用扩展)；它不负责到期提醒。


## 行内代码与代码块

### 行内代码

用一对反引号保护命令、文件名或语法：`` `npm run build` ``。内部若包含反引号，可用更长的反引号包围，例如用两个包围一个。代码中的星号与下划线保持字面含义。

### 围栏代码

围栏至少三个反引号或波浪号，结束围栏使用相同字符且长度不少于开头。语言名帮助读者识别，不会让代码执行，也不保证高亮。

````markdown
```python
print("hello")
```
````

要在教程中展示三反引号，可以用四反引号作为外层围栏；结束后留空行继续正文。没有正确关闭的围栏会把后续内容都包含进代码区。

### 缩进代码与当前支持

四空格缩进也能形成代码块；列表中的缩进另有层级要求。复制命令时留意智能引号、前导提示符和占位参数，理解后再运行。

Yeli 显示围栏代码及语言信息，但当前没有承诺所有语言的语法高亮。`mermaid` 和 `math` 语言标签不会自动启用图表或数学引擎，见[扩展语法](#扩展语法与-yeli-支持表)。

练习：在一个代码块里写 `# 这不是标题`，检查它不进入目录；用区块原文只修改代码内容，保存后重开。


## 链接、图片与引用链接

### 普通与引用链接

```markdown
[示例网站](https://example.com "访问说明")
[规范][spec]

[spec]: https://spec.commonmark.org/0.31.2/ "CommonMark"
```

方括号是可见名称，圆括号是目的地址，可选引号内容是标题。引用链接把地址集中放到定义处；完整、折叠和简写引用都依赖匹配的定义。地址含空格时优先使用编码或尖括号包围合法目标，避免未配对括号。

链接文字应说明目的，如“安装步骤”，避免只有“点击这里”。标题锚点生成规则由渲染器决定，跨工具发布要点击验证；`{#id}` 不是当前 Yeli 标题属性语法。

### 自动链接

`<https://example.com>` 与 `<writer@example.com>` 是标准尖括号自动链接写法。GFM 还描述裸网址扩展。Yeli 当前关闭裸文本 linkify，写明确的 `[名称](地址)` 最稳妥；不要假定 `www.example.com` 会自动可点击。

### 图片

```markdown
![流程图：输入、校验、输出](diagram.png "文档流程")
[![预览图](thumb.png)](https://example.com)
```

感叹号让链接结构变成图片。替代文字说明图片信息；相对路径依赖所在目录，移动 `.md` 时要同时搬迁资源。Yeli 不自动加载这些外部图片，要离线携带请[嵌入本地图片](./yeli.zh-CN.yeli.html#图片与离线资源)。

只使用你愿意打开的协议与来源；渲染器可能禁用不安全协议。练习：写一条有意义名称的链接，并用引用定义复用同一个地址。


## 表格、任务与 GFM 常用扩展

### 表格

```markdown
| 任务 | 负责人 | 工时 |
| :--- | :----: | ---: |
| 规划 |  Lin   |    2 |
| 制作 |  Sam   |    4 |
```

表头和分隔行的列数应相同，分隔行用短横线，可用冒号控制左、中、右对齐。单元格内部可写粗体、行内代码和链接；换行、嵌套列表和合并单元格不是可靠的管道表格能力。单元格中显示管道字符请转义为 `\|`。

Yeli 支持表格渲染与行列编辑。它不计算工时总和；需要数据计算时先用表格工具算好再写入。宽表在自己的滚动区域阅读。

### 任务列表

```markdown
- [ ] 检查来源
- [x] 完成初稿
- [ ] 保存并重新打开
```

方括号中空格表示未完成，`x` 表示已完成，后面要有空格再写文字。Yeli 编辑模式可以切换任务状态；预览中的任务不用于直接写入。复选框只是文档内容，不提供人员指派、提醒或后台工作流。

### 删除线与兼容

`~~旧结论~~` 可标记废弃内容。表格、任务与删除线不是 2004 年原始 Markdown 的全部通用基础；发到另一个工具前，检查它是否支持这些扩展。GFM 还定义其他规则，当前 Yeli 并非完整 GitHub 网站模拟器。

练习：把三项计划写成任务列表，再用三列表格记录每项负责人和工时。


## 扩展语法与 Yeli 支持表

### 按实现判断，不按文件名猜测

Markdown 方言和插件各不相同。下表依据当前默认 Yeli 渲染器：支持表格、删除线与自定义任务渲染；未启用脚注等插件，`html`、裸文本 `linkify` 关闭。官方高级源码构建也不自动开启这些扩展。

| 语法           | 常见写法                 | 当前 Yeli                       |
| -------------- | ------------------------ | ------------------------------- |
| 表格与对齐     | 管道、短横线与冒号       | 支持                            |
| 围栏代码/语言  | 三反引号后写 `js`        | 显示代码，不保证高亮            |
| 删除线         | `~~text~~`               | 支持                            |
| 任务           | `- [ ] task`             | 支持，编辑模式可切换            |
| 尖括号自动链接 | `<https://example.com>`  | 支持安全地址                    |
| 裸网址自动链接 | `https://example.com`    | 不自动链接                      |
| 脚注           | `text[^1]`、`[^1]: note` | 未启用脚注渲染                  |
| 指定标题 ID    | `## Title {#id}`         | 未启用属性语法                  |
| 定义列表       | 词后下一行 `: 解释`      | 未启用                          |
| emoji 简码     | `:smile:`                | 不转换；直接 Unicode 表情可显示 |
| 高亮           | `==text==`               | 未启用                          |
| 下标/上标      | `H~2~O` / `x^2^`         | 未启用                          |
| 数学           | `$x^2$` / `$$...$$`      | 未启用 KaTeX 等引擎             |
| 图表           | `mermaid` 围栏           | 作为代码，不生成图表            |
| 原始 HTML      | `<div>...</div>`         | 不执行，不作为作者 HTML 渲染    |

### 看懂未启用语法

```markdown
结论来自证据[^evidence]。

[^evidence]: 原始记录。

术语
: 简短解释

## 结果 {#result}
```

在支持相应插件的工具里，上述内容可能生成脚注、定义列表和自定义锚点。在当前 Yeli 中它可能按普通文本或原文区块保留；“原文没丢”不代表目标语义已渲染。

### 跨工具交付策略

优先使用标准链接代替脚注跳转、普通列表代替定义列表、文字说明代替数学与图表。必要图表可用外部工具生成 PNG/WebP 后嵌入，并保留原始图表源码。文字中的 Unicode 表情可能因字体不同而外观变化。

遇到扩展显示差异，先识别方言和引擎，不要反复保存试图“修复”语法，也不要承诺无损转换所有渲染效果。


## HTML、转义与安全边界

### 需要显示符号时

在有语法含义的标点前加反斜线，例如 `\# 不是标题`、`\*不是斜体\*`、`\[不是链接\]`。代码示例优先放入代码围栏，避免大量手动转义。字母前加反斜线不一定产生转义。

HTML 实体如 `&amp;`、`&lt;` 可表示 `&` 与 `<`；在代码区域通常希望保留字面实体而非解码。编辑后检查实际可见结果，而不是只看源码字符。

### Markdown 与原始 HTML

原始 Markdown 和 CommonMark 描述了嵌入 HTML 的处理，但具体应用可以选择禁用或过滤。语法规范不是执行权限许可。当前 Yeli 关闭作者原始 HTML 渲染，并通过最终清理边界处理输出。

```html
<script>
  alert("example");
</script>
```

这是展示用代码，不应执行。HTML、SVG、iframe、事件属性或 `javascript:` 链接不能当作跨平台排版方案；当前 Yeli 不允许文档提供可执行插件。

### 文件本身的信任

Yeli 会保护 Markdown 渲染边界，但 `.yeli.html` 自身携带运行时代码。因此只打开可信源的可编辑文件；文件里显示的“安全”字样不能证明这个文件安全。向不可信来源读者发布时，使用[只读导出](./yeli.zh-CN.yeli.html#导入导出与分享)。

练习：写出字面 `**important**`、一个代码中的 HTML 标签，再检查预览不会执行或错误格式化。


## YAML frontmatter 与可维护文档

### 写在正文之前

frontmatter 是许多文档工具约定的文件头，不是 CommonMark 基础语法。文件开头使用一对独立的 `---`，中间写 YAML，然后开始正文。不同工具可能识别、忽略或显示这段信息。

```yaml
---
title: 项目指南
description: 给新成员的本地文档
lang: zh-CN
tags: [入门, 文档]
authors: [Lin]
review_date: "2026-10-24"
---
```

标题、语言与标签都是内容的一部分。切换 Yeli 界面语言不会自动把 `lang` 改成英文；日期也不会自动更新。

### YAML 容易踩的地方

冒号后有空格，层级使用空格而非 Tab；包含 `: `、`#` 或易被解释为布尔/数字的文本时加引号。字段名不要重复。字符串列表和对象列表不是一回事；需要嵌套对象时先确认下游支持。

Yeli 属性表单能处理根级文本、有限数字、开关、日期字符串和字符串列表；复杂值保留只读，歧义 YAML 停用表单。未知安全字段不会因为没有专门界面就被丢弃。见[文档属性](./yeli.zh-CN.yeli.html#文档属性与-frontmatter)。

### 给人和 Agent 的文档契约

在正文写目标、范围、来源、验收与下一步；元数据承载简短索引信息，不要把所有要求藏到字段中。稳定字段与清晰小节让工具容易定位，但敏感资料不会因写成 YAML 就安全，也不应把密钥放进公开手册。


## 综合练习与参考资料

### 任务：一份可继续工作的项目简报

先在 `.md` 中写下面的骨架，补充真实但不敏感的内容：

````markdown
---
title: 本地文档试验
lang: zh-CN
tags: [练习]
---

# 背景

说明读者、问题与来源。

# 决策

**验收目标：** 保存后重新打开，内容和图片完整。

- [ ] 完成初稿
- [ ] 检查来源

| 方案     | 限制                     |
| -------- | ------------------------ |
| Markdown | 图片需另带               |
| Yeli     | 可编辑 HTML 需要可信来源 |

```text
这里是展示内容，不会执行。
```
````

### 人来验收

1. 核对标题层级、段落、列表、链接与表格；在 Yeli 中导入 `.md`。
2. 嵌入一张本地图片并写说明，保存为练习 `.yeli.html`，关闭后重开。
3. 试一次撤销和一次历史预览。只恢复内容不同的版本，并确认后再执行。
4. 导出 `.md` 与只读 HTML，对比正文；检查 Markdown 图片边界与只读输出资源。

### 再交给 Agent

要求 Agent：“先预读和提取，只修改‘决策’小节中的一句话；用原 hash 防止过期修改，输出新副本并验证，报告 diff 与 shell 是否变化。”按[Agent 教程](./yeli.zh-CN.yeli.html#与-agent-一起工作)执行。验收时同时检查事实与格式，不能只看 `ok: true`。

### 参考入口与继续学习

本课程使用原创组织与示例，覆盖以下用户指定范围；它们不是 Yeli 功能的支持声明：

- [Markdown 入门](https://markdown.com.cn/intro.html)：用途、工作方式与方言。
- [语法速查](https://markdown.com.cn/cheat-sheet.html)：基础与扩展速览。
- [基础语法](https://markdown.com.cn/basic-syntax/)：标题、段落、强调、引用、列表、代码、链接、图片、转义与 HTML。
- [扩展语法](https://markdown.com.cn/extended-syntax/)：表格、围栏代码、脚注、标题 ID、定义列表、删除线、任务、emoji、高亮、上下标与自动链接等。

历史与语义以 [Gruber 原始项目](https://daringfireball.net/projects/markdown/)、[CommonMark](https://spec.commonmark.org/0.31.2/) 和 [GFM](https://github.github.com/gfm/) 为主要资料。回到[速查](#markdown-语法速查)，或阅读 [Yeli 使命](./yeli.zh-CN.yeli.html#为什么是-yeli)理解单文件选择。