Markdown 缩进:空格为什么会消失,以及能用的写法

Markdown 写作约 7 分钟

Markdown 段落开头的空格会被丢掉,空行后面再有四个空格还会变成代码块,所以普通的缩进怎么敲都留不住。想给段落首行缩进,就让这一行以不是空格的字符开头,比如 &nbsp;、&emsp; 或者全角空格(U+3000);想让整块内容缩进,用引用块或者 HTML 的 <div>;列表项里面则按内容列缩进,不是随手敲几个空格。Markdown 本身没有缩进语法,下面每一种办法都是变通,各有代价。

为什么开头的空格会消失

挡住缩进的有两层,先弄清是哪一层。

第一层是 Markdown 解析器。CommonMark 规范说段落行开头的空格和制表符会被跳过,所以 aaa 后面接一行 bbb,得到的是同一个段落里的 aaa 和 bbb,两行都没有缩进。

第二层是浏览器。HTML 和 CSS 会把连续的空格、制表符和换行合并成一个空格,CSS 的 white-space: normal 就是这样描述的,CSS Text 规范把这条规则限定在空格(U+0020)、制表符(U+0009)和换行上,不间断空格和全角空格不在其中,不会被合并,后面首行缩进的几种写法靠的就是这一点。

开头空格真正起作用的只有四空格规则。连续的几行都以四个或更多空格开头,就是缩进代码块,所以空行之后的 text 是代码,用等宽字体显示,前面四个空格会被去掉。围栏写法见 Markdown 里的代码块。

用空白字符做首行缩进

让这一行以实体或者解析器不当作空格的字符开头:

&nbsp;&nbsp;&nbsp;&nbsp;An English paragraph indented by four non-breaking spaces.

&emsp;&emsp;Two em spaces, each one em wide.

  中文段落的首行缩进,用两个全角空格。

这几行开头是 & 或者 U+3000,规范都不把它们当空格,解析器看到的就是普通文字。规范里的空格只指 U+0020,所以连着四个 &nbsp; 不会变成代码块,敲四个真空格就会。

写法 宽度 说明
&nbsp; 一个空格 不会换行,要写好几个
&emsp; 一个 em(U+2003) 写两个,约等于缩进两个字
U+3000 一个全角字符 直接输入,中文段落最常用

中文的习惯是缩进两个字,两个 U+3000 刚好,因为在中日韩字体里全角空格和一个汉字一样宽。代价是缩进写在了文字里,每个段落都要自己写一遍,复制到别的应用里会带着这些字符,搜索段首的词时也要绕开它们,长文每段都敲一次 U+3000 会很烦。

这样只有段落首行会缩进。段落里的换行是软换行,下一行开头的空格同样会被忽略,想强制换行见 Markdown 换行。

用 CSS 的 text-indent

HTML 里专门干这件事的是 text-indent,它设置块容器第一行前面的空白。渲染器放行原始 HTML 时,可以直接写在段落上:

<p style="text-indent: 2em">这一段缩进两个字宽。</p>

有两处限制。原始 HTML 块里面不会再按 Markdown 解析,<p> 里的 **加粗** 会保留星号,这个块也在第一个空行处结束,所以每个段落都要自己的标签。

妙言 4.9.0 用 cmark-gfm 的 unsafe 模式渲染,原始 HTML 和 style 属性会原样进入预览。妙言没有自定义预览样式表的设置,预览页面也不会加载用户样式表,所以没法用一行 CSS 让所有段落缩进。它自带的排版不给段落缩进,所以在妙言里能用的就是上面的字符,或者每段加一个 style。真要用样式表,就导出成 HTML 再手改文件,见 Markdown 转 HTML。

让整块内容缩进

引用块能让文字往里缩,但它同时改了含义:

> 这一块从左边往里缩。

它渲染出来是引用,在妙言里是淡色文字加一条细竖线,所以引用才用它,不拿它做排版。嵌套引用和提示块见 Markdown 引用块和嵌套列表。

只想缩进、不要引用样式,就用带左边距的 <div> 包起来,里面的 Markdown 前后各留一个空行:

<div style="margin-left: 2em">

里面的 **Markdown** 照常生效,因为前后有空行。

</div>

以 <div> 开头的 HTML 块会一直延续到下一个空行,开标签后面的空行把内容交还给 Markdown 解析器,没有这个空行,里面就是原样的文字。

列表项里的缩进

列表项拥有缩进到它内容列的那些行,内容列就是标记后面文字开始的那一列。按规范的说法,宽度为 W 的标记后面跟 N 个空格,内容列就是 W + N,后面的行要缩进这么多才留在列表项里。- item 是 2 个空格,1. item 是 3 个。

- 第一步

  这是第一步的第二段,缩进两个空格。

1. 第一步

   这是第一步的第二段,缩进三个空格。

缩进不够,这一行就会掉出列表项。空行之后,1. item 下面只缩进两个空格,列表就结束了,这一行变成独立段落,因为内容列是 3;- one 下面只缩进一个空格也一样。反过来,缩进超过内容列四个空格就是代码,- item 下面缩进六个空格(2 加 4)会在列表项里得到一个代码块。规范还补了一条,缩进既能读成代码块又能读成列表内容时,按列表项来。

嵌套列表的写法和各种标记的宽度表见 Markdown 引用块和嵌套列表。

制表符和空格

CommonMark 不会把制表符展开成空格,只在缩进决定结构的地方,让制表符按制表位为 4 的空格来算。所以制表符可以代替四个空格写缩进代码块,一行里面的制表符则保持原样。

- foo 下面用一个制表符续写,和用空格一样是这个列表项的第二段,用两个制表符就是列表项里的代码;1. foo 下面用一个制表符续写也留在列表项里,因为它落在内容列 3 的后面。真正的风险是混用,一个文件里有的行用制表符、有的行用两个空格,在编辑器里看着对齐,解析出来却是两种深度。

妙言里按 Tab 会在行首插入两个空格,上一行是编号列表项时插入三个,Shift+Tab 去掉最多三个空格或一个制表符,格式菜单里对应的是右移(⌘])和左移(⌘[)。这些是给列表用的缩进,在普通段落首行按 Tab 加上的两个空格预览会丢掉,那里要用前面的字符。

缩进代码块和围栏

四空格代码块没法写语言名,不能打断段落,粘贴来的文字带着四个开头空格就会冒出来。围栏代码块把意图写明白了,所以优先用围栏,见 Markdown 里的代码块。

常见出错的地方

意外变成代码块。 从邮件、PDF 或别的编辑器粘贴的文字常常带着开头空格,空行后面有四个就会变成去掉空格的等宽块。删掉缩进,想要缩进就改用实体。

列表项的内容掉出来。 续写的段落缩进不够,列表就结束了,下一项会另起一个新列表。对照上面那个标记的内容列检查,编号到 10. 时标记多了一个字符,内容列也跟着右移一列。

原始 HTML 块把 Markdown 吞了。 **加粗** 显示出星号,说明这段文字在一个前后没留空行的 HTML 块里。

结果以预览为准,不看编辑器里的样子。

常见问题

Markdown 有首行缩进的语法吗?

没有。CommonMark 规范没有定义这样的语法,只能靠字符、原始 HTML 或者样式表。

中文缩进两个字要写几个 &nbsp;?

用两个 U+3000,在中日韩字体里它和汉字一样宽;&nbsp; 只有当前字体里一个空格那么宽,要接近的话用 &emsp;&emsp;。