Markdown 速查表：完整语法指南
· 12分钟阅读
目录
什么是 Markdown?
Markdown 是由 John Gruber 和 Aaron Swartz 于2004年创建的轻量级标记语言,它彻底改变了我们为网络写作的方式。它让你使用简单、直观的语法来格式化纯文本,这种语法既易于人类阅读,也可被机器解析。
与需要冗长标签和闭合元素的 HTML 不同,Markdown 使用自然符号,如星号、井号和方括号。这使得写作更快,即使不渲染,源文本也具有可读性。Markdown 文档在原始形式下看起来干净且合乎逻辑,这就是为什么它已成为技术文档的通用标准。
Markdown 背后的理念很简单:写作应该简单,语法应该是隐形的。当你阅读 Markdown 文件时,你首先阅读的是内容,其次才是标记。这与传统标记语言有本质区别,在传统标记语言中,标签往往会掩盖实际内容。
Markdown 的使用场景
Markdown 已在技术生态系统及其他领域无处不在:
- 开发平台: GitHub、GitLab、Bitbucket 用于 README 文件、问题、拉取请求和维基
- 文档: 技术文档、API 参考、用户指南和知识库
- 内容管理: 静态站点生成器(Jekyll、Hugo、Gatsby)、博客平台和 CMS
- 通信: Discord、Slack、Reddit、Stack Overflow 和论坛帖子
- 笔记: Obsidian、Notion、Bear、Joplin 和无数其他应用
- 科学计算: Jupyter Notebooks、R Markdown 和学术出版
- 电子邮件: 许多现代电子邮件客户端支持 Markdown 编写
需要将 Markdown 转换为 HTML 用于网络发布?试试我们的 Markdown 转 HTML 转换器,可实现即时、准确的转换。
专业提示: Markdown 文件使用 .md 或 .markdown 扩展名。大多数平台都能识别这两种,但 .md 更常见且更简洁。
标题和文档结构
标题是 Markdown 文档结构的支柱。它们创建层次结构,提高可读性,并帮助人类和搜索引擎理解你的内容组织。
基本标题语法
Markdown 使用井号(#)支持六级标题。井号的数量决定标题级别:
# 一级标题 (H1)
## 二级标题 (H2)
### 三级标题 (H3)
#### 四级标题 (H4)
##### 五级标题 (H5)
###### 六级标题 (H6)每个标题级别都有语义含义。H1 是你的文档标题,H2 是主要章节,H3 是子章节,依此类推。这种层次结构对于可访问性和 SEO 至关重要。
H1 和 H2 的替代语法
Markdown 还支持 H1 和 H2 标题的替代"下划线"语法:
一级标题
=========
二级标题
---------虽然这种语法有效,但井号语法更常见,并支持所有六级标题。大多数开发者更喜欢在整个文档中使用井号的一致性。
标题最佳实践
- 每个文档只使用一个 H1: H1 应该是你的页面标题或主标题
- 不要跳级: 从 H2 到 H3,而不是从 H2 到 H4。这保持了逻辑层次
- 保持标题简洁: 目标是2-8个词,清楚地描述该部分
- 使用句子大小写: "Markdown 入门"而不是"Markdown 入门"
- 添加间距: 在标题前后包含空行以提高可读性
- 使其具有描述性: 标题应该作为独立的导航元素
快速提示: 许多 Markdown 解析器会自动从标题生成锚链接,将"入门"转换为 #入门。这使得可以深度链接到特定部分。
文本格式和强调
Markdown 为常见的文本格式需求提供了直观的语法。这些格式选项在段落内内联工作,可以组合使用以实现更复杂的样式。
粗体和斜体文本
使用星号或下划线创建强调:
**粗体文本** 或 __粗体文本__
*斜体文本* 或 _斜体文本_
***粗体和斜体*** 或 ___粗体和斜体___星号和下划线的工作方式完全相同,但星号更常见。选择一种样式并坚持使用以保持一致性。许多风格指南推荐使用星号,因为它们更容易输入且视觉上更明显。
删除线和其他格式
其他格式选项包括:
~~删除线文本~~
`内联代码`
==高亮文本== (某些解析器)
X^2^ (上标,某些解析器)
H~2~O (下标,某些解析器)请注意,高亮文本、上标和下标是扩展功能,并非所有 Markdown 解析器都支持。GitHub 风格 Markdown (GFM) 默认支持删除线,但不支持高亮。
引用块
使用大于号(>)创建引用块:
> 这是一个引用块。
> 它可以跨越多行。
>> 嵌套引用块也是可能的。
>> 只需添加更多 > 符号。引用块非常适合引用、拉引用或突出显示重要信息。它们可以包含其他 Markdown 格式,包括标题、列表和代码块。
水平线
使用水平线在内容中创建视觉分隔:
---
***
___这三种语法产生相同的结果。在单独一行上使用三个或更多连字符、星号或下划线。大多数开发者更喜欢连字符(---)以保持清晰。
转义特殊字符
要显示字面 Markdown 字符,请使用反斜杠转义它们:
\*不是斜体\*
\# 不是标题
\[不是链接\]当你需要显示 Markdown 语法本身时,这是必不可少的,比如在文档或教程中。
专业提示: 在编写代码或技术主题时,对函数名、变量、文件路径和命令使用内联代码格式(`反引号`)。这提高了可读性,帮助读者区分代码和散文。
链接和图片
链接和图片在 Markdown 中使用类似的语法,使它们易于记忆和使用。两者都支持内联和引用样式格式,适用于不同的用例。
创建链接
基本链接语法很简单:
[链接文本](https://example.com)
[带标题的链接](https://example.com "悬停文本")链接文本出现在方括号中,紧接着是括号中的 URL。可选的标题属性出现在 URL 后的引号中,并在悬停时显示。
引用样式链接
对于有许多重复链接的文档,引用样式链接使你的内容更清晰:
[链接文本][reference-id]
[另一个链接][reference-id]
[reference-id]: https://example.com "可选标题"这种方法将链接定义与内容分离,使源代码更具可读性。它在长文档或同一 URL 多次出现时特别有用。
自动链接
URL 和电子邮件地址可以自动转换为链接:
<https://example.com>
<[email protected]>许多 Markdown 解析器也会自动链接不带尖括号的裸 URL,但这种行为并不通用。使用尖括号可确保跨平台的一致行为。
添加图片
图片语法与链接几乎相同,只是带有感叹号前缀:
![替代文本][image-reference]
[image-reference]: image.jpg "可选标题"替代文本对于可访问性和 SEO 至关重要。它为屏幕阅读器描述图片,并在图片加载失败时显示。始终提供描述图片内容和上下文的有意义的替代文本。
图片大小和对齐
标准 Markdown 不支持图片大小调整或对齐。你需要使用 HTML 来实现这些功能:
<img src="image.jpg" alt="替代文本" width="300">
<img src="image.jpg" alt="替代文本" style="float:right;margin:10px">大多数 Markdown 解析器允许内联 HTML,当你需要更多控制图片展示时,这是一个实用的解决方案。
快速提示: 链接到内部页面时,使用相对 URL(/about/)而不是绝对 URL(https://example.com/about/)。这使你的内容可移植,并在开发环境中正确工作。
列表:有序、无序和任务列表
列表是在 Markdown 中组织信息的基础。它们易于创建,并支持嵌套以实现复杂的层次结构。
无序列表
使用星号、连字符或加号创建项目符号列表:
* 项目一
* 项目二
* 项目三
- 项目一
- 项目二
- 项目三
+ 项目一
+ 项目二
+ 项目三这三个符号的工作方式完全相同。选择一个并在整个文档中一致使用。大多数开发者更喜欢连字符,因为它们视觉上更清晰。
有序列表
编号列表使用数字后跟句点:
1. 第一项
2. 第二项
3. 第三项这里有一个有用的功能:实际数字并不重要。Markdown 在渲染时会自动重新编号你的列表:
1. 第一项
1. 第二项
1. 第三项这使得重新排序项目更容易,因为你不需要手动重新编号所有内容。但是,对每个项目都以 1. 开头在阅读源代码时可能会令人困惑。
嵌套列表
通过使用空格或制表符缩进项目来创建分层列表:
1. 第一项
- 嵌套项目符号
- 另一个嵌套项目符号
2. 第二项
1. 嵌套编号
2. 另一个嵌套编号
- 更深层次的嵌套对每个嵌套级别使用一致的缩进(通常为2-4个空格)。大多数解析器都很灵活,但一致性可以提高可读性。
任务列表
GitHub 风格 Markdown 引入了用于跟踪待办事项的任务列表:
- [ ] 未选中的任务
- [x] 已选中的任务
- [ ] 另一个未选中的任务任务列表在 GitHub 等平台上是交互式的——你可以直接在渲染视图中选中和取消选中项目。它们非常适合项目规划、问题跟踪和协作文档。
列表最佳实践
- 添加空行: 在列表前后包含空行以便更好地解析
- 一致缩进: 在整个文档中使用相同的缩进(2或4个空格)
- 保持项目平行: 每个项目以相同的词性开头(全部动词、全部名词等)
- 限制嵌套: 最多三级以保持可读性
- 对序列使用有序列表: 步骤、排名或任何具有固有顺序的内容
- 对集合使用无序列表: 功能、优点或没有特定顺序的项目
代码和代码块
Markdown 在显示代码方面表现出色,使其成为技术文档和编程教程的首选格式。
内联代码
用单个反引号包裹内联代码:
使用 `console.log()` 函数进行调试。
`<div>` 元素是一个容器。内联代码格式保留间距并防止 Markdown 解释。在句子中提及代码元素时,这是必不可少的。
代码块
使用三个反引号(围栏代码块)创建代码块:
```
function hello() {
console.log("Hello, world!");
}
```这是现代的首选语法。它比旧的缩进方法(4个空格或1个制表符)更清晰、更灵活。
语法高亮
在开头反引号后指定编程语言以实现语法高亮:
```javascript
function hello() {
console.log("Hello, world!");
}
```
```python
def hello():
print("Hello, world!")
```
```css
.container {
max-width: 1200px;
margin: 0 auto;
}
```大多数 Markdown 解析器支持数十种语言。常见标识符包括