Markdown 使用指南 - 基础语法

本文主要介绍 Markdown 的基础语法,Markdown 扩展语法请参考这里
简洁版语法可浏览速查手册

总览

几乎所有的 Markdown 引擎都支持 Markdown 发明者 John Gruber 所设计的基本语法,但不同的 Markdown 处理引擎在细节表现方面略有不同,下面逐一介绍。

标题

要创建标题的话只需使用井号 # 开头,井号的数量对应标题的级别。比如如果你想要创建一个 <h3> 则可以通过用三个 # 开头:### 三级标题 。使用井号的标题语法在 CommonMark 规范中称之为“ATX 标题”。

Markdown HTML 渲染结果
# 一级标题 <h1>一级标题</h1>

一级标题

## 二级标题 <h2>二级标题</h2>

二级标题

### 三级标题 <h3>三级标题</h3>

三级标题

#### 四级标题 <h4>四级标题</h4>

四级标题

###### 五级标题 <h5>五级标题</h5>
五级标题
####### 六级标题 <h6>六级标题</h6>
六级标题

标题可选语法

除了使用 ATX 标题外,我们还可以用 Setext 标题:在文本下一行用一个或多个等号 = 表示一级标题,一个或多个短横线 - 表示二级标题。

Markdown HTML 渲染结果
一级标题
======
<h1>一级标题</h1>

一级标题

二级标题
------------
<h2>二级标题</h2>

二级标题

标题最佳实践

  1. 段落之间的 ATX 标题最好使用空行分隔。因为有的 Markdown 引擎不识别缺少前后空行的标题语法。

    ✅ 稳妥 ❌ 不稳妥
    这是一个段落。

    # 一级标题

    另一个段落。
    这是一个段落。
    # 一级标题
    另一个段落
  2. ATX 标题的井号后务必加上一个空格

    ✅ 稳妥 ❌ 不稳妥
    # 一级标题 # 一级标题
  3. 尽量不要使用 Setext 语法来写标题,因为 Setext 语法只能写到二级标题

段落

使用空行分隔文本即可。

Markdown HTML 渲染结果
我很喜欢使用 Markdown。

我将使用 Markdown 来排版我所有的文档。
<p>我很喜欢使用 Markdown。
<p>我将使用 Markdown 来排版我所有的文档。</p>

我很喜欢使用 Markdown。

我将使用 Markdown 来排版我所有的文档。

段落最佳实践

  1. 段落开头不要使用空格或者制表符(\t 即 Tab 键)来缩进,否则可能会被当做代码块渲染。

    ✅ 稳妥 ❌ 不稳妥
    开头不要缩进。

    像这样保持左对齐就好。
    开头缩进可能会被渲染为代码块。
  2. 中文传统排版上段落开头有着“空两格”的习惯,可以使用全角空格   或者 HTML 实体 &emsp;。科技领域的文章排版建议不要空两格,段落居左对齐较好

折行

如果需要文本折行 <br>,可在文本结尾加上两个或更多的空格然后回车。

Markdown HTML 渲染结果
这是第一行。
这是第二行。
<p>这是第一行。<br>这是第二行。</p> 这是第一行。
这是第二行。

折行最佳实践

目前大部分 Markdown 引擎会自动将换行符 \n 转换为 <br>,即软换行转硬换行。所以结尾用两个或更多空格的写法虽然稳妥,但是可能也会造成一些小问题:结尾空格在一些编辑器中并不可视;不小心按到或者习惯性按到会造成错误排版。介于这些小问题,可能用 <br> 来折行是最稳妥的做法,但这又不太优雅。另外,在 CommonMark 规范中可以在文本结尾使用反斜杠 \ 来折行,但我也不太推荐这种写法。

综上,我的建议是不要使用结尾空格、\ 或者 <br>,因为现在几乎所有的 Markdown 引擎基本都已经支持软换行转硬换行了。

加粗和强调

加粗对应粗体,强调对应斜体。

加粗

要加粗文本,可以使用两个星号 ** 或者两个下划线 __ 包裹待加粗的文本。

Markdown HTML 渲染结果
把文本**加粗**一下 把文本<strong>加粗</strong>一下 把文本加粗一下
把文本 __加粗__ 一下 把文本 <strong>加粗</strong> 一下 把文本 加粗 一下

加粗最佳实践

加粗用星号和用下划线的不同之处在于星号用法前后可以不加空格,但下划线必须要加。

✅ 稳妥 ❌ 不稳妥
星号**加粗**无需空格 没有空格下划线__加粗__无效

强调

要强调文本,可以使用一个星号 * 或者一个下划线 _ 包裹待强调的文本。

Markdown HTML 渲染结果
把文本*强调*一下 把文本<em>强调</em>一下 把文本强调一下
把文本 _强调_ 一下 把文本 <em>强调</em> 一下 把文本 强调 一下

强调最佳实践

和加粗类似,星号用法前后可以不加空格,但下划线必须要加。

✅ 稳妥 ❌ 不稳妥
星号*强调*无需空格 没有空格下划线_强调_无效

加粗并强调

如果你需要加粗的同时强调文本,可以使用三个星号 *** 或者三个下划线 ___ 包裹待强调的文本。

Markdown HTML 渲染结果
同时 加粗并强调 的示例 同时 <strong><em>加粗并强调</em></strong> 的示例 同时 加粗并强调 的示例
同时 加粗并强调 的示例 同时 <strong><em>加粗并强调</em></strong> 的示例 同时 加粗并强调 的示例
同时 加粗并强调 的示例 同时 <strong><em>加粗并强调</em></strong> 的示例 同时 加粗并强调 的示例
同时 加粗并强调 的示例 同时 <strong><em>加粗并强调</em></strong> 的示例 同时 加粗并强调 的示例
星号可以不用加空格 星号<strong><em>可以不用</em></strong>加空格 星号可以不用加空格

块引用

要创建块引用 <blockquote> 的话仅需在段落前加上大于号 >

> 原谅我这一生不羁放纵爱自由,也会怕有一天会跌倒
> 背弃了理想 ,谁人都可以
> 哪会怕有一天只你共我

渲染结果

原谅我这一生不羁放纵爱自由,也会怕有一天会跌倒
背弃了理想 ,谁人都可以
哪会怕有一天只你共我

块引用内分段

如果需要分段的话需要可以在分段空行前加上一个 >

> 今天我, 寒夜里看雪飘过
> 怀着冷却了的心窝漂远方
>
> 风雨里追赶, 雾里分不清影踪
> 天空海阔你与我

渲染结果:

今天我, 寒夜里看雪飘过
怀着冷却了的心窝漂远方

风雨里追赶, 雾里分不清影踪
天空海阔你与我

嵌套块引用

块引用可以嵌套使用,在段落前添加两个大于号 >> 表示两层嵌套。

> 块引用段落
>
>> 嵌套的块引用段落

块引用包含其他元素

块引用能够包含其他大部分语法元素。CommonMark 规范将块引用定义为容器块,容器块可以包含任意块级元素和行级元素,也就是说块引用可以包含其他任意元素。

> ### 标题是叶子块元素
>
> * 列表项一是容器块元素
> * 列表项二也是容器块元素
>
> **加粗**和*强调*是行级元素。

渲染结果:

标题是叶子块元素

  • 列表项一是容器块元素
  • 列表项二也是容器块元素

加粗强调是行级元素。

列表

列表分为有序列表和无序列表。Markdown 中的列表只能包含列表项元素,列表项和块引用一样,都是容器块。也就是说列表项可以包含其他任意元素。

有序列表

有序列表可以通过阿拉伯数字后跟 . 或者 ) 来创建,数字不必递增连续。

Markdown HTML 渲染结果
1. 列表项一
2. 列表项二
<ol><li>列表项一</li><li>列表项二</li></ol>
  1. 列表项一
  2. 列表项二
1. 列表项一
1. 列表项二
<ol><li>列表项一</li><li>列表项二</li></ol>
  1. 列表项一
  2. 列表项二
1. 列表项一
3. 列表项二
<ol><li>列表项一</li><li>列表项二</li></ol>
  1. 列表项一
  2. 列表项二

无序列表

无序列表可以通过短横线 -、星号 * 或者加号 + 来开头,后面需要跟一个空格来分隔文本内容。

Markdown HTML 渲染结果
- 列表项一
- 列表项二
<ul><li>列表项一</li><li>列表项二</li></ul>
  • 列表项一
  • 列表项二
* 列表项一
* 列表项二
<ul><li>列表项一</li><li>列表项二</li></ul>
  • 列表项一
  • 列表项二
+ 列表项一
+ 列表项二
<ul><li>列表项一</li><li>列表项二</li></ul>
  • 列表项一
  • 列表项二

列表项包含其他元素

列表项可以包含其他任意元素,比如段落、块引用、代码块、图片等。使用要点是待包含元素的起始字符要和列表项起始内容“对齐”。

列表项包含段落

* 列表项一
* 列表项二第一段
  
  这是第二段
* 列表项三

渲染结果:

列表项包含块引用

* 列表项一
* 列表项二第一段
  
  > 第二段是块引用
* 列表项三

渲染结果:

列表项包含代码块

* 列表项一
* 列表项二第一段
  
   ```
  这里是代码块
  echo 你好,世界!
   ```
* 列表项三

渲染结果:

列表项包含图片

* 列表项一
* 列表项二第一段
  
  ![B3log](https://static.b3log.org/images/brand/b3log-128.png "B3log 开源社区")
* 列表项三

渲染结果:

代码

代码可以通过反引号 ` 包裹。

Markdown HTML 渲染结果
列出文件命令是 `ls` 列出文件命令是 <code>ls</code> 列出文件命令是 ls

转义反引号

如果你需要显示反引号,可以用转义符 \ 来对反引号进行转义。

Markdown HTML 渲染结果
打个反引号 ` 打个反引号 ` 打个反引号 `

代码块

代码块可以使用四个空格缩进或者制表符 \t 缩进。

    <html>
      <head>
      </head>
    </html>

渲染结果:

<html>
  <head>
  </head>
</html>

推荐使用围栏代码块语法来排版代码块,即使用 ``` 来包裹代码块,并且指定语法高亮语言:

```html
<html>
  <head>
  </head>
</html>
```

分隔线

通过大于等于三个星号 ***、短横线 --- 或者下划线 ___ 来创建分隔线。

***
---
___

渲染结果:


超链接

通过 [链接文本](URL) 来创建超链接。

我们来自小众开源社区 [B3log](https://b3log.org)。

渲染结果:

我们来自小众开源社区 B3log

添加超链接标题

链接标题是可选的,在圆括号中的 URL 后用双引号包裹。鼠标移到超链接上会浮出显示标题内容。

我们来自小众开源社区 [B3log](https://b3log.org "B3log 开源")。

渲染结果:

我们来自小众开源社区 B3log

URL 和邮件地址

如果要直接显示 URL 或者邮件地址,可以通过 <> 来包裹 URL 或者邮件地址。

<https://b3log.org>

<os@b3log.org>

大部分 Markdown 引擎也支持自动转换,这样可以省去 <>

https://b3log.org

os@b3log.org

超链接格式排版

超链接可以和加粗强调、代码等元素结构一同使用。

我们来自小众开源社区 **[B3log](https://b3log.org)**。
我们来自小众开源社区 [`B3log`](https://b3log.org)。

渲染结果:

我们来自小众开源社区 B3log
我们来自小众开源社区 B3log

引用风格的超链接

使用引用风格的超链接可以让 Markdown 原文更容易阅读。引用风格的超链接分为两部分:链接引用和链接定义。

链接引用

链接引用用于在需要插入超链接的地方,它由两组方括号构成,第一组方括号用于指定链接文本,第二组方括号用于指定链接标识,链接标识指向链接定义。

[链接文本][链接标识]

[链接标识]: https://b3log.org

渲染结果:

链接文本

链接引用也可以只由一组方括号构成,这种情况下链接标识将用于链接文本。

[链接标识]

[链接标识]: https://b3log.org

渲染结果:

链接标识

链接定义

链接定义由三部分构成:

  1. 方括号包裹定义链接标识,后跟冒号 :
  2. URL,可以直接写也可以用尖括号 <> 包裹
  3. 链接标题,这部分是可选的,可以用双引号、单引号或者圆括号包裹
[链接标识]: https://b3log.org
[链接标识]: <https://b3log.org>
[链接标识]: https://b3log.org "B3log 开源"
[链接标识]: https://b3log.org 'B3log 开源'
[链接标识]: https://b3log.org (B3log 开源)

链接定义可以放在整个 Markdown 文本的任何位置。有的人习惯将其放于引用所在段落之后,有的人习惯将其放于文末位置。

超链接最佳实践

英文内容天然使用空格分隔,所以在使用自动超链接时不存在分隔问题。但中文会存在该问题,比如:

我们的网址是https://b3log.org欢迎开源爱好者加入!

这段内容在很多 Markdown 引擎上会渲染不正确。为了尽量保证兼容性,可以考虑使用空格进行分隔:

我们的网址是 https://b3log.org 欢迎开源爱好者加入!

或者使用尖括号 <> 包裹:

我们的网址是<https://b3log.org>欢迎开源爱好者加入!

这样就能得到预期的渲染结果了:

我们的网址是 https://b3log.org 欢迎开源爱好者加入!

图片

使用感叹号 ! 后跟超链接就可以渲染图片了。

![B3log Logo](https://static.b3log.org/images/brand/b3log-128.png)

渲染结果:

B3log Logo

超链接嵌套图片

如果你需要图片点击可以跳转超链接,只需要在链接文本部分包含图片即可。

[![黑客派](https://static.b3log.org/images/brand/hacpai-128.png)](https://hacpai.com)

渲染结果:

黑客派

转义字符

可使用反斜杠 \ 来转义如下字符:

字符 中文名称
\ 反斜杠
` 反引号
* 星号
_ 下划线
{} 花括号
[] 方括号
() 圆括号
# 井号
+ 加号
- 短横线(减号)
.
! 感叹号
| 竖线(管道符号)

几乎所有 ASCII 标点符号都可以使用反斜杠进行转义。

嵌入 HTML

Markdown 天然支持嵌入 HTML 代码。

**Markdown** 和 <em>HTML</em> 混合排版。

渲染结果:

MarkdownHTML 混合排版。

嵌入 HTML 最佳实践

这在需要设置图片大小、字体颜色时会比较有用,但我们并不建议过多使用 HTML 来进行排版,一来是因为这样做实际上并不通用,因为有的 Markdown 引擎因为安全原因会过滤部分标签或者属性;二来是因为这样做太不 Markdown 了!

另外,请勿在 HTML 中嵌入 Markdown,这样并不工作:

<p>**粗体**不会生效。</p>

渲染结果:

**粗体**不会生效。

总结

使用好空行和空格是 Markdown 排版的关键,很多时候就是因为少了个空行或者空格导致产生了非预期的渲染结果。

随着 CommonMark/GFM 规范日趋完善并逐渐成为业界统一的 Markdown 标准,已经有越来越多的 Markdown 引擎实现了该规范。建议 Markdown 使用者尽量该遵循规范来进行排版,这样才能最大程度地避免细节渲染问题。

参考

赞助商 我要投放

10 回帖
请输入回帖内容 ...
  • 88250

    标准的 Markdown 语法不支持链接打开新窗口,但有些扩展语法支持,写法不一,目前大部分 Markdown 处理器不支持这些扩展,所以就不介绍了。如果这需求,可以试试直接写 <a target="_blank"> 但有些平台是会过滤标签属性的,为了解决安全问题。

    插入 JS 代码到 Markdown 中本质上和上面的问题是一个,要看平台是否支持。

    1 回复
  • 其他回帖
  • PeterChu 1
    1. D 你是通过“分屏预览”模式编辑这段回复的吗

    2. 我发现了,“即时渲染”和“所见即所得”2 种模式下才有 缩进 功能按钮。

      另外,如果不是“分屏预览”模式,则不能在列表下已有文本或内容的段落前手动输入空格达到缩进的目的,敲空格不起作用。
      (这个 🤔 好吧总结一下,

      1. 列表项行单次回车后,光标所在行的下一行没有列表项内段落内容情况下,光标所在行会生成下一列表项,本行成为列表项行。
      2. 列表项行单次回车后,光标所在行的下一行为列表项行的情况下,则光标所在行会变为列表项行,列表项会顺延上一列表项,本行下的所有列表项则会 +1 或顺移一位。
      3. 列表项行单次回车后,光标所在行的下一行为列表项中的段落行,此时本行也会成为列表项中的段落行,而不是列表项行,且会自动缩进,与列表项行内容左对齐。
      4. 若想在 2 个列表项行中间插入列表项内段落行,则需要 shift + 回车 ,此时光标所在行会自动缩进,且后续列表项符号不会改变。
      5. 若想结束当前列表,则需要在最后一项列表项行/段落后 2 次回车才可以。)
    3. 除“分屏预览”模式外的 2 中模式中,对列表项中的已经存在的段落、内容的编辑有问题啊。
      比如先将 2 段落输入完后,再为后一段落换行分段落时,该段落会变成下一列表项了。

      😲 好吧我发现了,原来此时的换行需要 shift+ 回车。


    看来还是自己 MD 用的不熟悉啊,这个 MD 列表嵌套缩进好麻烦哇,好怀念 word 的编辑形式 wulian

    还有个小问题就是,嵌套有序列表如果不从字号上区分的话,至少应该将列表项,1、2、3 的样式区分一下更好点~~,比如最外层的列表项 123 支持加粗,若加粗,则第二层列表项为不加粗 123,第三层列表项则变为 带 1 个括号 1) 或者 (1) 或者 大/小写字母 abc,若第一层不加粗,则从上面的第三层开始排样式~~。(看了下语雀,只支持到 3 层有序列表的嵌套。多层第三层嵌套还挺麻烦。看来多层确实是不太常用到的特性。
    image.png

    )

  • ferried

    mark

  • iTanken 1 1 评论
    • 纠错 huaji

      • 加粗 HTML 示例空格位置:
        image.png

      • 加粗并强调 Markdown 示例被渲染:
        image.png

    感谢,已做修正。
    88250
  • 查看更多回帖