AI Agent Engineer

AI Agent Engineer

Markdown 完整教程

21 min read

Markdown 完整教程

Markdown 的学习重点不是背诵全部符号，而是掌握“源码简单、纯文本可读、渲染结果清晰”这三个原则。本教程中的示例主要遵循 CommonMark，并补充 GitHub Flavored Markdown（GFM）与 Obsidian 中常见的写法。

如何使用本教程

建议在 Obsidian 中同时打开“编辑视图”和“阅读视图”：先复制“Markdown 源代码”，再切换到阅读视图观察渲染结果。不同平台的 Markdown 解析器可能存在细微差异。

目录

1. Markdown 是什么，以及常见使用场景

功能说明

Markdown 是一种轻量级标记语言。它使用 #、*、-、反引号等普通字符表达文档结构，再由 Obsidian、GitHub、博客系统或其他工具渲染成带格式的内容。

常见使用场景包括：

  • 编写 README、项目文档和 API 文档。
  • 在 Obsidian 中记录知识、日记和研究笔记。
  • 编写博客、静态网站和在线教程。
  • 记录会议纪要、任务清单和实验日志。
  • 撰写能够被 Git 管理和比较差异的纯文本文档。

Markdown 的优势是源码易读、文件轻量、跨平台，并且非常适合版本控制；局限是不同渲染器支持的扩展语法不完全相同，复杂排版通常仍需 HTML、CSS 或专门的排版工具。

Markdown 源代码

# 项目说明
 
这是一个使用 **Python** 编写的数据分析项目。
 
## 快速开始
 
1. 安装依赖。
2. 运行程序。
3. 查看结果。

渲染后的效果说明

渲染器会把 # 开头的文本识别为标题，把空行分隔的文字识别为段落，把 **Python** 显示为粗体，并把数字开头的内容显示为有序列表。即使不渲染，源码本身也保持较好的可读性。

2. 标题

功能说明

在一行开头使用 1～6 个 # 可以创建一至六级标题。# 后应保留一个空格。标题级别用于表达文档结构，而不仅仅是改变字号；通常一篇笔记只使用一个一级标题。

Markdown 源代码

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

渲染后的效果说明

上述六行会依次渲染为从一级到六级的标题。一级标题层级最高、视觉上通常最大，后续标题逐级从属于前一级标题。Obsidian 还会根据这些标题生成大纲，并允许链接到某个标题。

3. 普通段落与换行

功能说明

连续文本会组成一个普通段落。两个段落之间应保留一个空行。仅在源码中按一次 Enter，通常不会产生新的段落；需要在同一段内强制换行时，可在行尾输入两个空格，或在支持 CommonMark 的环境中使用行尾反斜杠 \。

Markdown 源代码

这是第一段。源码中的相邻文本行，
通常仍会被合并到同一个段落中。
 
这是第二段，因为它与上一段之间有一个空行。
 
这一行末尾使用反斜杠\
然后继续下一行。

渲染后的效果说明

这是第一段。源码中的相邻文本行， 通常仍会被合并到同一个段落中。

这是第二段，因为它与上一段之间有一个空行。

这一行末尾使用反斜杠
然后继续下一行。

空行产生新的段落，行尾两个空格或反斜杠产生段内换行。若不确定某个平台是否保留行尾空格，优先使用空行划分段落。

4. 粗体、斜体与删除线

功能说明

粗体用于强调重要内容，斜体用于轻度强调或标记术语，删除线表示内容已作废、被替换或不再适用。常见写法分别是 **粗体**、*斜体* 和 ~~删除线~~。

Markdown 源代码

这是 **粗体文字**。
 
这是 *斜体文字*。
 
这是 ***粗斜体文字***。
 
这是 ~~删除线文字~~。

渲染后的效果说明

这是 粗体文字。

这是 斜体文字。

这是 粗斜体文字。

这是 删除线文字。

成对的星号或波浪线不会显示，而是控制其中内容的样式。删除线不是最早期 Markdown 的核心语法，但 GFM、Obsidian 等常用环境普遍支持。

5. 有序列表和无序列表

功能说明

无序列表适合表达没有先后关系的项目，常用 -、* 或 + 开头；有序列表适合表达步骤或优先级，使用“数字 + 英文句点”开头。标记后需要保留一个空格。缩进可以创建子列表，同一文档中应保持缩进风格一致。

Markdown 源代码

- 水果
  - 苹果
  - 香蕉
- 蔬菜
 
1. 打开编辑器
2. 创建 Markdown 文件
3. 输入内容
   1. 添加标题
   2. 添加段落
4. 保存文件

渲染后的效果说明

  • 水果
    • 苹果
    • 香蕉
  • 蔬菜
  1. 打开编辑器
  2. 创建 Markdown 文件
  3. 输入内容
    1. 添加标题
    2. 添加段落
  4. 保存文件

无序列表显示项目符号，有序列表显示序号，缩进项目显示为嵌套层级。多数渲染器会自动校正有序列表的显示编号，但源码仍建议按真实顺序编号，便于阅读和维护。

6. 任务列表

功能说明

任务列表是在无序列表标记后添加 [ ] 或 [x]。[ ] 表示未完成，[x] 表示已完成。它适合待办事项、学习计划、检查清单和项目进度记录，属于 GFM 常用扩展语法。

Markdown 源代码

- [x] 了解 Markdown 是什么
- [x] 学习基础语法
- [ ] 完成综合练习
- [ ] 整理自己的速查表

渲染后的效果说明

  • 了解 Markdown 是什么
  • 学习基础语法
  • 完成综合练习
  • 整理自己的速查表

渲染后，每个项目会显示为复选框。Obsidian 中通常可以直接单击复选框切换状态；其他平台是否允许交互取决于具体实现。

7. 链接

功能说明

标准 Markdown 链接由方括号中的显示文字和圆括号中的目标地址组成：[显示文字](URL)。还可以添加可选标题：[显示文字](URL "标题")。链接目标既可以是网页地址，也可以是相对文件路径或同一页面中的标题锚点。

Markdown 源代码

[访问示例网站](https://example.com)
 
[带标题的链接](https://example.com "鼠标悬停时可能显示此标题")
 
[跳转到本文的表格部分](#11-表格)
 
<https://example.com>

渲染后的效果说明

访问示例网站

带标题的链接

跳转到本文的表格部分

https://example.com

渲染后，方括号中的文字成为可单击链接；尖括号包围的完整 URL 会显示为可单击的自动链接。标题锚点的具体生成规则可能因平台而异，在 Obsidian 内部链接笔记时通常优先使用 [[笔记名]]。

8. 图片

功能说明

图片语法是在普通链接前加一个感叹号：![替代文字](图片地址)。替代文字会在图片无法加载时显示，也能帮助屏幕阅读器理解图片内容。地址可以是网络 URL 或相对路径，还可在地址后添加可选标题。

Markdown 源代码

![Markdown 标志](https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg "Markdown 标志")
 
![实验流程图](attachments/experiment-flow.png)

渲染后的效果说明

Markdown 标志

第一行会尝试加载并显示网络图片；第二行表示加载当前笔记所在目录下 attachments 文件夹中的本地图片。若目标不存在或网络不可用，渲染器通常显示替代文字或破损图片提示。Obsidian 也支持 ![[图片名.png]] 形式的内部嵌入。

9. 引用

功能说明

在行首添加 > 可以创建块引用，适合引用他人原话、突出定义或展示补充说明。连续多行都可以添加 >；使用多个 > 可以创建嵌套引用。

Markdown 源代码

> Markdown 的目标之一，是让纯文本本身也容易阅读。
>
> 引用块中可以包含多个段落。
 
> 第一层引用
>> 第二层引用

渲染后的效果说明

Markdown 的目标之一，是让纯文本本身也容易阅读。

引用块中可以包含多个段落。

第一层引用

第二层引用

渲染后，引用内容通常带有左侧竖线、缩进和不同的文字颜色。空引用行 > 用于在同一个引用块内分隔段落。

10. 行内代码和代码块

功能说明

行内代码使用一对反引号包围，适合命令、变量名、文件名或短代码。多行代码使用三个反引号围成的代码块；在开头反引号后写语言名称，可以启用语法高亮。代码中的 Markdown 符号不会继续被解释为格式。

Markdown 源代码

使用 `git status` 查看仓库状态。
 
```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
 
print(greet("Markdown"))
```

渲染后的效果说明

使用 git status 查看仓库状态。

def greet(name: str) -> str:
    return f"Hello, {name}!"
 
print(greet("Markdown"))

行内代码会嵌在段落中并使用等宽字体；代码块会独占区域并保留空格、缩进和换行。标注 python 后，支持语法高亮的渲染器会为关键字、字符串等添加颜色。

11. 表格

功能说明

GFM 表格使用竖线 | 分隔列，并在表头下方使用连字符创建分隔行。分隔行中的冒号控制对齐：左侧冒号表示左对齐，两侧冒号表示居中，右侧冒号表示右对齐。源码中的竖线不必严格纵向对齐，但对齐后更易阅读。

Markdown 源代码

| 语法 | 用途 | 掌握程度 |
| :--- | :---: | ---: |
| `#` | 标题 | 100% |
| `**` | 粗体 | 80% |
| `` ` `` | 行内代码 | 60% |

渲染后的效果说明

语法用途掌握程度
#标题100%
**粗体80%
`行内代码60%

渲染后会形成三列表格：第一列左对齐，第二列居中，第三列右对齐。如果单元格内容本身需要显示竖线，通常要写成 \|。

12. 分隔线

功能说明

在单独一行输入至少三个连字符、星号或下划线，可以创建水平分隔线。为了避免它与标题或列表产生歧义，建议在分隔线前后各保留一个空行，并统一使用 ---。

Markdown 源代码

第一部分内容。
 
---
 
第二部分内容。

渲染后的效果说明

第一部分内容。

第二部分内容。

三个连字符会渲染为横向分隔线，用于划分内容区域。注意：文档最顶部成对出现的 --- 可能被识别为 YAML frontmatter，而不是普通分隔线。

13. 转义字符

功能说明

当需要显示 Markdown 本身使用的特殊符号，而不希望它触发格式时，可在符号前添加反斜杠 \。常见可转义字符包括 \、反引号、*、_、{}、[]、()、#、+、-、.、!、| 和 > 等 ASCII 标点。

Markdown 源代码

\# 这不是标题
 
\*这不是斜体\*
 
\[这不是链接文字\]
 
反斜杠本身写成：\\

渲染后的效果说明

# 这不是标题

*这不是斜体*

[这不是链接文字]

反斜杠本身写成：\

渲染时，转义用的第一个反斜杠通常不会显示，其后的特殊字符会按普通文本显示。代码跨度和代码块中的符号本来就不会被解析为 Markdown，一般无需再转义。

14. HTML 与 Markdown 混合使用

功能说明

许多 Markdown 渲染器允许直接嵌入部分 HTML，用于补充 Markdown 不擅长的细节，例如键盘按键、折叠区域、上标、下标或更精细的布局。HTML 的可用范围取决于平台；出于安全原因，某些网站会过滤标签、属性、脚本和样式。

Markdown 源代码

按 <kbd>Ctrl</kbd> + <kbd>S</kbd> 保存文件。
 
水的化学式是 H<sub>2</sub>O，平方可以写成 x<sup>2</sup>。
 
<mark>这段文字使用 HTML 高亮。</mark>
 
<details>
<summary>点击展开答案</summary>
 
答案内容仍然可以包含 **Markdown 粗体**。
 
</details>

渲染后的效果说明

按 Ctrl + S 保存文件。

水的化学式是 H2O，平方可以写成 x2。

这段文字使用 HTML 高亮。

点击展开答案

答案内容仍然可以包含 Markdown 粗体。

支持这些标签时，kbd 显示为键帽，sub 和 sup 显示上下标，mark 显示高亮，details 创建可折叠区域。如果某个平台禁用原始 HTML，标签可能被移除、转义或直接显示为文本。

15. GitHub Flavored Markdown 常用语法

功能说明

GitHub Flavored Markdown（GFM）是在基础 Markdown 上增加常用扩展的一种方言。最具代表性的扩展包括表格、任务列表、删除线和自动链接；围栏代码块来自 CommonMark，也是 GitHub 上最常用的基础语法之一。GitHub 页面还会识别 @用户名、议题编号和提交哈希等平台相关内容，但这些功能不一定能在其他 Markdown 工具中使用。

Markdown 源代码

~~已废弃的方案~~
 
- [x] 已完成
- [ ] 待完成
 
| 项目 | 状态 |
| --- | --- |
| 文档 | 完成 |
 
访问 https://github.com 可以看到自动链接。
 
```javascript
console.log("GFM fenced code block");
```

渲染后的效果说明

已废弃的方案

  • 已完成
  • 待完成
项目状态
文档完成

访问 https://github.com 可以看到自动链接。

console.log("GFM fenced code block");

支持 GFM 时，上述内容会分别渲染为删除线、任务复选框、表格、可单击的裸 URL 和带语法高亮的代码块。Obsidian 支持其中大多数常用写法，但它与 GitHub 的平台专属行为并不完全相同。

16. Obsidian 中常见的 Markdown 扩展

功能说明

Obsidian 在标准 Markdown 和 GFM 之外还提供双向链接、嵌入、callout、高亮等扩展。这些语法很适合构建个人知识库，但离开 Obsidian 后不一定能够得到相同的渲染结果。

Markdown 源代码

[[Markdown 完整教程]]
 
[[Markdown 完整教程#11. 表格|跳转到表格部分]]
 
==这是一段高亮文字==
 
> [!note] Obsidian 提示框
> 
> 这是一个 callout。

渲染后的效果说明

Markdown 教程

跳转到表格部分

这是一段高亮文字

Obsidian 提示框

这是一个 callout。

双中括号会创建 vault 内部链接，| 后可以设置显示文字；双等号创建高亮；带 [!note] 的引用块会显示为 Obsidian callout。内部链接会被 Obsidian 跟踪，目标笔记重命名时可以自动更新。

17. 综合练习

功能说明

下面的练习把标题、段落、强调、列表、任务、链接、引用、代码和表格组合到一篇短笔记中。先手动输入源码，再切换到阅读视图核对结果，比单纯阅读语法更容易形成记忆。

Markdown 源代码

# Markdown 学习记录
 
今天我学习了 **Markdown**，并完成了以下内容：
 
- [x] 标题与段落
- [x] 列表与任务
- [ ] 表格与代码块
 
> 每天练习十分钟，比一次背完所有语法更有效。
 
常用命令是 `git status`：
 
```powershell
git status --short
```
 
| 主题 | 状态 |
| --- | --- |
| 基础语法 | 已掌握 |
| GFM | 练习中 |
 
参考：[CommonMark](https://commonmark.org/)
```

渲染后的效果说明

渲染后，这篇练习会形成结构清晰的学习记录：顶部是一级标题，中间包含任务清单和引用，命令以行内代码及代码块展示，学习进度用表格汇总，末尾提供可单击的外部链接。

完成标准

如果你能不查看教程，独立写出综合练习中的大部分结构，就已经掌握了日常写作所需的 Markdown 基础。

速查表

目标常用源码
一级标题# 标题
粗体**文字**
斜体*文字*
删除线~~文字~~
无序列表- 项目
有序列表1. 项目
任务列表- [ ] 任务
链接[文字](URL)
图片![替代文字](图片地址)
引用> 引用
行内代码`code`
代码块三个反引号包围代码
表格使用 | 分隔列（在单元格中显示竖线时写作 \|）
分隔线---
转义\*不作为斜体*

Backlinks