Markdown 标题怎么写:# 语法、层级和锚点

Markdown 写作约 7 分钟

Markdown 标题就是一到六个 #,后面跟一个空格,再跟标题文字,比如 # 标题、## 章节、### 小节。这个空格不能省,#标题 只是一段普通文字。另外还有一种更老的下划线写法(setext),只能写到两级,而且有个陷阱,一段文字正下方的 --- 会把这段文字变成标题。剩下的功夫都在结构上,因为大纲面板、目录和读屏软件读的都是标题。

ATX 标题,也就是 # 写法

CommonMark 规范把 # 写法叫 ATX 标题,规则不多:

# 一级标题
## 二级标题
###### 六级标题
####### 七个就太多了,这是一段普通文字

开头是一到六个 #,后面必须跟空格或制表符(或者直接换行)。规范自己的例子里,#5 bolt 和 #hashtag 都是段落,写一条以话题标签开头的笔记时用得上。一行确实要以 # 开头,就在第一个 # 前加反斜杠,\## foo,其他需要转义的字符见 Markdown 转义字符。

标题前面最多可以缩进三个空格,四个就成了代码块。文字两边的空格和制表符会被去掉,内容按普通行内 Markdown 解析,所以强调、行内代码和链接在标题里都能用。

标题末尾也可以再写一串 # 收尾,有人喜欢这样让源码看着对称:

## 在 Mac 上安装 ##

收尾的 # 前面必须有空格或制表符,后面只能是空格或制表符,数量不必和开头一致。## Install #on Mac 里的 # 会保留,因为 #on Mac 是文字,不是收尾。大多数笔记不写收尾这一串。

ATX 标题前后不需要空行,规范的例子是 Foo bar、# baz、Bar foo 连着三行,结果是一个段落、一个 <h1>、一个段落,不过还是留着空行,源码读起来舒服。

setext 标题,也就是下划线写法

一级标题
===============

二级标题
---------------

一行文字下面跟一行 = 是一级标题,跟一行 - 是二级标题,仅此而已,没有三级。下划线长度不限,可以缩进最多三个空格,字符之间不能有空格(= = 不是下划线)。文字可以占好几行,几行合起来是同一个标题。setext 在纯文本里读着顺,但只到两级,所以大多数笔记还是用 #。

--- 陷阱

我的购物清单
---

作者多半想画一条横线,CommonMark 却把它读成二级标题,因为 setext 的读法优先于分隔线的读法。多行段落更糟,规范的例子是 Foo、Bar 两行下面跟 ---,结果是一个同时包含两行的 <h2>。解决办法是在短横线上面空一行,或者用 ***,它不会被读错。三种横线的写法和妙言对 --- 的处理见 Markdown 横线。

=== 同理,会把上一段变成一级标题,单独占一行时它只是普通文字。

层级和文档大纲

标题层级说的是结构,不是字号。W3C 的无障碍教程讲标题时说,最重要的标题是 1 级,最不重要的是 6 级,同级或更高级的标题开启新章节,更低一级的开启子章节。教程也建议尽量避免跳级,比如 h2 后面直接跟 h4,原文是这样会让人困惑,不过收起子章节再回到上层时跳级没有问题。W3C 这页并没有要求只能有一个 h1,它的例子只是各用了一个。

笔记和文档里比较好用的约定:

  • 一个 # 标题作为笔记标题,## 写主要章节,### 写小节,文字确实还有嵌套时再往下。
  • 不要因为 ### 看着小就去选它,层级是结构,不是字号。

大纲面板和读屏软件的标题导航都是按层级建出来的,跳一级就会在每一处留下一个缺口。

标题 ID 和锚点

链接到标题需要它的 ID,而 Markdown 没有定义这个东西。CommonMark 没有标题 ID 的语法,也没说 ID 怎么生成,每个工具各自决定。GitHub 公开了它的规则,字母转成小写,空格变成连字符,其他空白和标点去掉,格式标记剥掉只留文字,重复的标题依次加上 -1、-2。GitHub 还提醒,改了标题,或者调整锚点相同的几个标题的顺序,锚点都会变,指向它们的链接要跟着更新。

## 安装 {#install} 这种属性写法来自 Pandoc 的 header_attributes 扩展,Pandoc 手册说它和 PHP Markdown Extra 兼容,不属于 CommonMark,在 GitHub 和妙言里 {#install} 会原样显示出来。笔记要在多个地方都能用,就在标题上面放一个 HTML 锚点 <a id="install" name="install"></a>,妙言的预览按 id 找目标,GitHub 文档里的自定义锚点用的是 name,两个属性都写就两边都能跳。

各家 ID 规则不同,同一个锚点链接可能在一个应用里能用、换一个就失效。差异和测试办法在 Markdown 链接和锚点 里讲过,这里不重复。

标题里的强调、链接和代码

标题接受行内 Markdown,## 更*快*的路径、## `--force` 参数 和 ## 参见 [规范](https://spec.commonmark.org/) 都能正常渲染。锚点是按可见文字生成的,所以带链接或代码的标题生成的仍是纯文字锚点,改了标题文字,指向它的链接就断了,标题尽量写成朴素的标签。

妙言怎么用标题

妙言用 cmark-gfm 渲染,# 和下划线两种标题都遵循 CommonMark。下面这些来自 V4.9.0 的源码。

  • 编辑器。 编辑器给 # 标题行上色,并把 # 标记当作语法符号处理,下划线写法则把 === 或 --- 那一行标成语法符号。
  • 大纲面板。 预览里有一个目录面板,只列 h1、h2、h3,用 tocbot 生成。笔记里至少有两个这样的标题才会出现,预览窄于 600 像素时,用来呼出它的悬停入口会隐藏。在显示预览或分栏时,用「视图」菜单里的「切换目录」或 ⌘5 打开,这样打开会固定住,再按一次关闭。所以只有标题加一堆 #### 的笔记没有大纲,这也是层级要连续的又一个理由。
  • 预览字号。 预览样式表里 h1 是 1.76em,h2 是 1.41em,h3 是 1.18em,h4 到 h6 和正文一样大,所以 h4、h5、h6 看起来完全一样,都是正文大小的粗体。
  • 锚点。 每个标题的 ID 就是它的文字,重复的加 -1、-2,预览里鼠标悬停会在旁边出现一个链接图标,指向这个标题。这和 GitHub 的小写 slug 不同,链接那篇里讲过。

妙言 V4.9.0 没有标题折叠,也没有设置标题级别的快捷键,# 要自己敲。其他语法见 Markdown 速查表。

检查标题

打开大纲(妙言里 ⌘5,GitHub 上是 Outline 按钮)当列表读一遍,不看正文也读得通,结构就没问题。再找 ## 直接跳到 ####、行首 # 后面没有空格、段落下面多出来的 ---,最后在笔记会被阅读的每个地方点一遍页内链接。

常见问题

一个 Markdown 文件该有几个一级标题?

一个最稳,作为笔记标题。CommonMark 允许多个,W3C 的标题教程也没有要求只能一个,但只留一个 # 大纲更好读。

为什么 #标题 没有变成标题?

# 后面没有空格。CommonMark 要求空格或制表符,#标题 是段落,写成 # 标题。

为什么我的段落变成了大标题?

段落正下方写了 --- 或 ===,被当成了 setext 下划线,在短横线上面加一个空行就好。

能在 Markdown 里自定义标题 ID 吗?

CommonMark 不行,{#id} 在 Pandoc 和 PHP Markdown Extra 里有效。要让笔记通用,就在标题上面放 <a id="name" name="name"></a>。