Markdown基础语法指南
Markdown基础语法由John Gruber在2004年原始设计文档中定义的11个格式化元素组成，到2026年，几乎所有Markdown应用仍然完整支持这套元素。 这11个元素分别是：标题、段落、换行、强调、引用、列表、代码、分隔线、链接、图片和字符转义。每个元素使用的都是键盘上现成的标点符号，并且各自对应一个特定的HTML标签。不同解析器之间存在细微差异，因此本指南会标注在任何环境下渲染效果都完全一致的写法。下面的每个示例都可以直接粘贴到带实时预览的Markdown编辑器中，输入的同时即可看到渲染结果。
标题
Markdown标题以1到6个井号（#）开头，后跟一个空格，井号的数量决定标题级别，从H1到H6。
# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
每一行都会转换为对应的HTML标签，因此# Page Title渲染为h1元素，###### Fine Print渲染为h6。Markdown还为前2个级别提供了另一种写法：在文本下一行放置任意数量的等号表示H1，任意数量的短横线表示H2。井号写法称为ATX风格，下划线式写法称为Setext风格。
Heading level 1
===============
Heading level 2
---------------
最佳实践：在每个标题前后各留一个空行，并在井号与文本之间保留1个空格，这样标题在所有应用中都能正确渲染。
段落
段落是一行或连续多行文本，上下各有一个空行，不需要任何标记符号。
The first paragraph ends here.
A blank line above this sentence starts a second paragraph.
渲染器会把每个文本块包在p标签里，所以上面的2个文本块会变成2个独立的HTML段落。块内的单次回车会合并为连续文本，这意味着你可以在源文件中按80个字符换行，输出仍然是一个完整不断开的段落。
最佳实践：让每个段落都顶格左对齐，因为行首出现4个及以上空格会把段落变成代码块。
换行
要在段落内换行，需要在行尾添加2个或更多空格，或者使用HTML标签<br>。
This line ends with 2 trailing spaces.
This line appears directly below it.
This line ends with a br tag.<br>
This line also sits inside the same paragraph.
两种方法都渲染为br元素，第二行会紧贴在第一行下方，没有段落间距。行尾没有任何内容的普通回车会把2行合并成一行。CommonMark也接受行尾反斜杠作为换行，但较旧的解析器会忽略它，所以真正通用的2种方案仍然是行尾空格和<br>标签。
最佳实践：当换行需要经受复制粘贴和代码审查时，选择<br>标签，因为行尾空格在大多数编辑器的屏幕上是不可见的。
强调
Markdown加粗在文本两侧各加2个星号，斜体加1个，加粗斜体加3个；下划线可以作为等效替代，用于包裹完整的单词。
This word is **bold** and so is this __word__.
This word is *italic* and so is this _word_.
This phrase is ***bold and italic***.
渲染器把这些标记转换为strong和em标签：**bold**变成<strong>bold</strong>，*italic*变成<em>italic</em>，三重标记则把一个标签嵌套在另一个里面。强调也可以用在单词内部，例如un*believ*able只会把中间的6个字母变成斜体。
最佳实践：单词内部的强调请使用星号而不是下划线，因为所有主流解析器对词内星号的处理方式一致，而词内下划线的表现各不相同。
引用
引用以行首的大于号（>）开始，每一行被引用的内容都要带上自己的标记。
> A single-paragraph quote needs 1 marker per line.
>
> A marked blank line continues the quote into a second paragraph.
>
>> Two markers push this paragraph 1 level deeper as a nested quote.
输出是一个blockquote元素，双重标记会在第一层引用内部嵌套第二层引用。引用中还可以包含其他Markdown元素：只要每一行都以>标记开头，标题、列表或加粗文本都能在引用内正常渲染，非常适合引用邮件和带有自身结构的引文。
最佳实践：在每个引用前后都加上空行，让各个解析器都能准确判断引用的起止位置。
列表
Markdown列表中，有序列表在每一项前放一个数字和一个句点，无序列表在每一项前放一个短横线、星号或加号。
1. First step
2. Second step
3. Third step
1. Indented sub-step
- Bullet item
- Bullet item
- Nested bullet
有序列表渲染为ol元素，并从你输入的第一个数字开始计数，所以写成1、8、3的列表输出仍然是1、2、3。无序列表渲染为ul元素，3种分隔符都可以使用。缩进4个空格或1个Tab可以嵌套子列表，同样的缩进也能把其他元素保留在列表项内：段落或引用需要4个空格，而列表内的代码块需要8个空格，因为标准的4空格代码缩进要叠加在列表缩进之上。
最佳实践：每个列表只使用1种分隔符风格，有序列表的数字后使用句点而不是括号，因为句点写法在所有Markdown应用中都有效。
代码
行内代码放在一对单反引号之间，代码块则是至少缩进4个空格或1个Tab的连续多行。
Type `git status` to check the working tree.
<html>
<head></head>
</html>
这对反引号会渲染出等宽字体的code元素，缩进的代码块则渲染在pre和code标签内，每个空格都原样保留。如果代码片段本身包含反引号，就需要用双反引号包裹，例如the outer pair displays `code` literally。使用三反引号的围栏代码块属于扩展语法，4空格缩进才是最初的写法。
最佳实践：用双反引号包裹字面反引号，让内部字符正常显示，而不是提前结束代码片段。
分隔线
分隔线需要单独一行上的3个或更多星号、短横线或下划线。
***
---
___
3种写法渲染出的hr元素完全相同，是一条通栏分割线。字符数量超过3个也不会改变输出，所以20个短横线和3个短横线产生的分隔线一模一样。写作者常用分隔线来标记场景转换和章节边界，在这些地方使用标题会显得过重。
最佳实践：在每条分隔线上下各留一个空行，因为紧贴在文本下方的纯短横线行会把那段文本变成H2标题。
链接
行内链接把链接文本放在方括号里，后面紧跟放在圆括号里的URL，还可以附加一个带引号的可选标题。
Read the [original spec](https://daringfireball.net/projects/markdown/ "Gruber's 2004 spec").
Reference style keeps prose clean: read the [original spec][1].
[1]: https://daringfireball.net/projects/markdown/
Bare addresses work in angle brackets: <https://example.com> and <mail@example.com>
每种形式都渲染为a元素，鼠标悬停时标题文本会以提示框形式出现。引用式链接把URL从句子中分离出来：[1]标签指向一个可以放在文件任意位置的定义，这样即使段落里满是长URL，源文本也保持易读。尖括号能把裸URL或电子邮箱地址直接变成可点击的链接，无需任何额外文字。链接同样支持格式化：在整个链接结构外加星号可以加粗链接，在方括号内加反引号则把链接文本渲染为代码。
最佳实践：把URL中的所有空格编码为%20，确保完整地址在所有解析器中都能保留。
图片
图片语法依次是一个感叹号、方括号里的替代文本，以及圆括号里的图片路径或URL。
[](https://example.com/report)
第一行渲染为img元素，替代文本作为无障碍标签，引号中的标题作为悬停文字。这个语法与链接完全一致，只是前面多了1个字符。第二行把整个图片结构嵌套在链接内，点击图片就会打开目标URL。
最佳实践：撰写能描述图片内容的替代文本，因为屏幕阅读器和搜索引擎会用它来代替图片本身。
字符转义
在格式化字符前放一个反斜杠（\），可以让该字符按字面显示，而不是触发它的Markdown功能。
\* This line shows a literal asterisk, not a bullet point.
1968\. The escaped period stops this year from starting an ordered list.
反斜杠本身不会出现在输出中，只有它后面的字符会被显示。Markdown支持对12个字符进行反斜杠转义：反斜杠、反引号、星号、下划线、花括号、方括号、圆括号、井号、加号、减号、句点和感叹号。上面第二个例子解决了一个常见陷阱：如果不转义，任何以数字加句点开头的行都会变成列表项。
最佳实践：只转义这份12个字符清单中的字符，因为在其他字符前加反斜杠会显示出一个可见的反斜杠。
常见问题
什么是Markdown基础语法？
基础语法是John Gruber在2004年Markdown设计文档中定义的11个元素的功能集，几乎所有Markdown应用都完整支持。 这11个元素在各种解析器中表现一致，因此对于需要在多个平台之间流转的文档来说，基础语法集是最安全的选择。
Markdown支持多少级标题？
Markdown支持6级标题，用1到6个井号书写，直接对应HTML标签h1到h6。 下划线式的替代语法只覆盖前2个级别：等号表示H1，短横线表示H2。
如何在不开启新段落的情况下换行？
在行尾加2个空格，或使用HTML标签<br>。 两种方式都会在当前段落内渲染一个br元素。空行的效果不同：它会结束当前段落并开启一个新段落。
基础语法够用吗，还是需要扩展语法？
基础语法足以应对标准文档，而扩展语法增加了表格、围栏代码块、脚注等来自后续规范（如GFM）的元素。 先从基础语法集入手以获得最大兼容性，确认目标平台支持后，再逐步加入扩展元素。