一组你值得拥有的 Markdown 中混用 HTML 案例

2019-08-23 by Dron

前言

Markdown 基础语法(见附录)已经无法满足日益丰富的信息内容，好在 Markdown 支持直接写 HTML，让扩展成为可能。

本文罗列一些常见的、实用的扩展案例，尝试设定规约，通过用少量的 HTML 代码作为 Markdown 的补充来辅助排版，并且保持简明直观的语义。

如果你是一个完美 Markdown 控，对于混用 HTML 的情况实在无法接受的话，可以不用往后阅读了。

适用情况

由于是在 Markdown 中补充 HTML，而不是新的自定义语法，所以不必再额外实现 转换工具1，可以直接在任何现成支持 Markdown 的平台中使用，它们包括不限于：博客文章、评论

Github 的文档

ATA 文章

邮件内容

扩展案例

文章摘要/导读

通常文章的第一段作为全文的内容摘要/导读，字数不要太多，在第一段之后加一行仅有一个单词 More 的注释，用于分隔摘要/导读，多数支持 Markdown 的博客系统也都能识别此注释，在点击「」链接之后展示全文。

代码

说明HTML 注释不会被渲染到页面中。

More 左右各留一个英文空格。

分页

用 Markdown 撰写各种文档的草稿非常适合(比如 PDF 讲义稿)，此时有必要补充一个符号用于标识分页，以更好的组织页面内容。

代码

说明HTML 注释不会被渲染到页面中。

脚注

Markdown 规定了脚注的语法，但很多转换工具并不支持，保险起见，可以写 HTML 实现。

代码如果你跳进一个 黑洞¹ ，你的物质和 能量² 将以一种被撕裂的形式返回到我们的宇宙中。

## 注释

1. 黑洞是广义相对论中宇宙空间内存在的一种天体。黑洞的引力很大，使得视界内的逃逸速度大于光速。

2. 能量是质量的时空分布可能变化程度的度量，用来表征物理系统做功的本领。

效果如果你跳进一个 黑洞1 ，你的物质和 能量2 将以一种被撕裂的形式返回到我们的宇宙中。

注释黑洞是广义相对论中宇宙空间内存在的一种天体。黑洞的引力很大，使得视界内的逃逸速度大于光速。

能量是质量的时空分布可能变化程度的度量，用来表征物理系统做功的本领。

说明关键词左边和 右边，各留一个英文空格。

页底的脚注信息，用 Markdown 的有序列表语法即可。

这个方法的缺点是需要人肉维护脚注的序号，应尽量少用，建议每页条目最多不超过 5 个。

文本高亮

文本高亮在标识搜索关键词的场景下用到，通常用于提示用户关键词的位置，以便用户更快的找到。如果需要，也可以针对一句话甚至一个段落高亮。

代码…… 海森堡在 1927 年首先提出 ……

效果不确定性原理表明：一个微观粒子的某些物理量(如位置和动量，或方位角与动量矩，还有时间和能量等)，不可能同时具有确定的数值，其中一个量越确定，另一个量的不确定程度就越大。测量一对共轭量的误差(标准差)的乘积必然大于常数 h/4π(h是普朗克常数)是 海森堡在 1927 年首先提出 的，它反映了微观粒子运动的基本规律——以共轭量为自变量的概率幅函数(波函数)构成傅立叶变换对，以及量子力学的基本关系，是物理学中又一条重要原理。

说明‌ ‌是 HTML5 的新 标签。

插入和删除

插入和删除在审稿的时候经常用到，表示一个修改动作，从标记为插入或删除的文本上，方便用户了解之前和现在的版本。

代码苍蝇座的位置极易分辨，它位于南十字座和 长蛇座 半人马座 南边，蝘蜓座以北的船底座和圆规座之间的银河中，「煤袋星云」就在苍蝇座、南十字座和半人马座的交界处，在位于 +10° 到 -90° 之间纬度的地区可全见。

效果苍蝇座的位置极易分辨，它位于南十字座和 长蛇座 半人马座 南边，蝘蜓座以北的船底座和圆规座之间的银河中，「煤袋星云」就在苍蝇座、南十字座和半人马座的交界处，在位于 +10° 到 -90° 之间纬度的地区可全见。

说明 表示删除， 表示插入。

和 一起用表示修改。

文本颜色

颜色虽是样式属性，但为了区别于强调有时会用到，通常不同的颜色代表不同的状态。

代码包括新泽西州、康涅狄格州以及纽约市在内许多地区的法律都 明确禁止 居民把电子废品当成一般垃圾来丢弃。

效果包括新泽西州、康涅狄格州以及纽约市在内许多地区的法律都 明确禁止 居民把电子废品当成一般垃圾来丢弃。

说明尽管 是 HTML5 的不建议标签，但语义上仍然是所有标签中最好的。

标签前后各留一个英文空格。

用颜色的英文名而不是十六进制表示法表示。

文字注音

对于一些多音字或者生癖字，留下注音能帮助读者更好的阅读。

代码饕餮 tāo tiè 是古代中国神话传说中的一种神秘怪物，别名叫 狍鸮 páo xiāo，古书《山海经·北次二经》介绍其特点是：其形状如羊身人面，眼在腋下，虎齿人手。

效果饕餮 tāo tiè是古代中国神话传说中的一种神秘怪物，别名叫狍鸮 páo xiāo，古书《山海经·北次二经》介绍其特点是：其形状如羊身人面，眼在腋下，虎齿人手。

说明‌ 和 ‌ 是 HTML5 的新 标签。

导航到位置

几乎所有的转换工具都会为每一级的标题生成一个位置 #id 用于大纲的导航。然而每个工具的生成规则有差异，在创作文章的时候无法确定目标的最终位置，如果想自定义一个导航到文章具体目标的链接，需要写 HTML 实现。

代码

⋮

建议回去看看文章开头的 适用情况。

效果如果你不知道本文所列举的案例应该用在哪些地方，建议回去看看文章开头的 适用情况。

说明取决于 技术实现2 ，「导航到位置」在大多数邮箱中不适用。

由于导航的动作会导致修改页面地址的 hash 值，可能会破坏页面的逻辑，比如基于 hash 来实现的 Router。

分栏

如果承载文章的载体，有比较大的宽度的话(比如横向的纸张)，分栏可以有效改善阅读体验，而不至于一行的文字太长，CSS3 里提供了分栏的样式。

代码

效果在广义相对论的实验验证上，有著名的三大验证。在水星近日点的进动中，每百年 43 秒的剩余进动长期无法得到解释，被广义相对论完满地解释清楚了。光线在引力场中的弯曲，广义相对论计算的结果比牛顿理论正好大了 1 倍，爱丁顿和戴森的观测队利用 1919 年 5 月 29 日的日全食进行观测的结果，证实了广义相对论是正确的。再就是引力红移，按照广义相对论，在引力场中的时钟要变慢，因此从恒星表面射到地球上来的光线，其光谱线会发生红移，这也在很高精度上得到了证实。从此，广义相对论理论的正确性被得到了广泛地承认。

说明columns 是个复合复性，参见 这个介绍。

如果你的文章是发往多个渠道的，不建议使用。

附录：高兼容性 Markdown 语法

Markdown 的标准有很多派系，各工具的实现都不太一样，如果你想你的文章能在各工具平台上更好的兼容，我的最佳实践是尽可能只用他们公认/实现的子集。

下表筛选自 CommonMark，经过多个编辑器和转换工具的测试，可以放心使用。作用语法说明斜体*Italic*

加粗**Bold**

一级标题# 标题

二级标题## 标题

三级标题### 标题

四级标题#### 标题

五级标题##### 标题

六级标题###### 标题

链接[Link](http://example.com)

链接[Link][1]

⋮

[1]: http://example.com

图像

引用‌> 内容可以引用 Markdown

无序列表‌- 列表项

有序列表‌1. 列表项

水平线---

内链代码`内容`将原文打印内容

代码块```language

代码

```不建议采用缩进 4 个空格的语法来代表代码

转义字符\

这里值得一提的是，‌

|:--|:--|

| 内容 | 内容 |

| 内容 | 内容 |

注释转换工具将 Markdown 文本换为 HTML 代码，以在 webview 上展示。

大多数 web 邮箱，邮件内容展示区是一个无地址的 标签实现的，故不能用 #hash 的办法实现导航。