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

2019-08-23 by Dron

前言

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

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

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

适用情况

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

• 博客文章、评论
• Github 的文档
• ATA 文章
• 邮件内容

扩展案例

文章摘要/导读

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

代码

<!-- More -->

说明

• HTML 注释不会被渲染到页面中。
• More 左右各留一个英文空格。

分页

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

代码

<!---->

说明

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

脚注

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

代码

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

## 注释

1. 黑洞是广义相对论中宇宙空间内存在的一种天体。黑洞的引力很大，使得视界内的逃逸速度大于光速。
2. 能量是质量的时空分布可能变化程度的度量，用来表征物理系统做功的本领。

效果

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

注释

1. 黑洞是广义相对论中宇宙空间内存在的一种天体。黑洞的引力很大，使得视界内的逃逸速度大于光速。
2. 能量是质量的时空分布可能变化程度的度量，用来表征物理系统做功的本领。

说明

• 关键词左边和 </sup> 右边，各留一个英文空格。
• 页底的脚注信息，用 Markdown 的有序列表语法即可。
• 这个方法的缺点是需要人肉维护脚注的序号，应尽量少用，建议每页条目最多不超过 5 个。

文本高亮

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

代码

…… <mark>海森堡在 1927 年首先提出</mark> ……

效果

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

说明

• ‌<mark> ‌是 HTML5 的新 标签。

插入和删除

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

代码

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

效果

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

说明

• <del> 表示删除，<ins> 表示插入。
• <del> 和 <ins> 一起用表示修改。

文本颜色

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

代码

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

效果

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

说明

• 尽管 <font> 是 HTML5 的不建议标签，但语义上仍然是所有标签中最好的。
• <font> 标签前后各留一个英文空格。
• 用颜色的英文名而不是十六进制表示法表示。

文字注音

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

代码

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

效果

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

说明

• ‌<ruby> 和 ‌<rt> 是 HTML5 的新 标签。

导航到位置

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

代码

<a name="applicable-situation"></a>
⋮
建议回去看看文章开头的 <a href="#applicable-situation">适用情况</a>。

效果

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

说明

• 取决于 技术实现² ，「导航到位置」在大多数邮箱中不适用。
• 由于导航的动作会导致修改页面地址的 hash 值，可能会破坏页面的逻辑，比如基于 hash 来实现的 Router。

分栏

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

代码

<div style="columns: 2;">
在广义相对论的实验验证上，有著名的三大验证。在水星近日点的进动中......
</div>

效果

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

说明

• columns 是个复合复性，参见 这个介绍。
• 如果你的文章是发往多个渠道的，不建议使用。

附录：高兼容性 Markdown 语法

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

下表筛选自 CommonMark，经过多个编辑器和转换工具的测试，可以放心使用。

这里值得一提的是，‌<table> 也是现实中的一个强需求，标准里并没有对它有明确的语法说明，但是有多数的工具对此作了实现，它的语法是：

| 表头 | 表头 |
|:--|:--|
| 内容 | 内容 |
| 内容 | 内容 |

注释

1. 转换工具将 Markdown 文本换为 HTML 代码，以在 webview 上展示。
2. 大多数 web 邮箱，邮件内容展示区是一个无地址的 <iframe> 标签实现的，故不能用 #hash 的办法实现导航。