尽管笔者专门写了一个文章系列 《从 Markdown 到 reStructuredText》,推荐在日常文档写作中更多地使用 reStructuredText。不过平心而论,Markdown 标记语言其实还是不错的,再加上一堆漂亮好用的客户端,使其作为博客写作语言相当合适。静态博客 Nikola 本身也对 Markdown 开箱提供了完整支持,Markdown 与 reStructuredText 一样都是“一等公民”。

Nikola 中使用的语法与主流 Markdown 语法,可以说是一模一样的。同时,还以扩展的形式 1 额外提供了一些:

Extension "Name"
Extra markdown.extensions.extra
    Abbreviations markdown.extensions.abbr
    Attribute Lists markdown.extensions.attr_list
    Definition Lists markdown.extensions.def_list
    Fenced Code Blocks markdown.extensions.fenced_code
    Footnotes markdown.extensions.footnotes
    Tables markdown.extensions.tables
    Smart Strong markdown.extensions.smart_strong
Admonition markdown.extensions.admonition
CodeHilite markdown.extensions.codehilite
HeaderId markdown.extensions.headerid
Meta-Data markdown.extensions.meta
New Line to Break markdown.extensions.nl2br
Sane Lists markdown.extensions.sane_lists
SmartyPants markdown.extensions.smarty
Table of Contents markdown.extensions.toc
WikiLinks markdown.extensions.wikilinks

使用前注意到 conf.py 配置文件中开启相应选项,比如本博客的设置为:

MARKDOWN_EXTENSIONS = ['markdown.extensions.toc', 'markdown.extensions.admonition', 'markdown.extensions.fenced_code', 'markdown.extensions.codehilite', 'markdown.extensions.extra']

这样设置以后,与市面上绝大多数 Markdown 客户端支持的语法特性就都一样了,譬如:文档目录(TOC)、表格(Tables)、代码区块(Fenced Code Blocks)、脚注(Footnotes)等等。这些完全一样的语法在此就不再赘述,只说一下本博客设置里开启的个人感觉值得关注的两项:告诫(Admonition)和属性列表(Attribute Lists)。

告诫(Admonition)

告诫(Admonition) 语法是从 reStructuredText 标记语言借鉴而来的,包含于标准 Markdown 库中。常用于在文档中给予提示、警告、严重警告等,以引起读者注意。语法如下:

!!! warning
    千万不要在家中尝试!

渲染结果:

Warning

千万不要在家中尝试!

可以有一个自定义的标题:

!!! danger "请勿在森林里生火!"
    可能会引起森林大火,给人身安全和国家财产带来严重威胁。

请勿在森林里生火!

可能会引起森林大火,给人身安全和国家财产带来严重威胁。

属性列表(Attribute Lists)

属性列表(Attribute Lists)的重要性在 从 Markdown 到 reStructuredText(三) 一文中已经有所提及:要实现“图片居中”等样式效果,则最好通过 类选择器 进行元素定位,以方便套用事先定义好的样式。而 属性列表 则可以自定义元素的 class、id 及其它属性等等。其语法如下:

{: #someid .someclass somekey='some value' }

比如给标题自定义 id 以方便文章别处引用和点击跳转:

### 告诫(Admonition) ### {: #admonition }

点击 [此处](#admonition) 跳转到 `告诫(Admonition)` 标题。

渲染结果:

点击 此处 跳转到 告诫(Admonition) 标题。

给图片自定义 class 以实现圆形居中:

![avatar](/images/avatar.png){: class="ui centered small circular image" }

渲染结果:

avatar

原图 avatar.png 实际上是一张 800x800 的正方形图片(右键保存查看)。考虑到如此强大的“图片处理”效果,学习属性列表(Attribute Lists)语法是不是显得没那么麻烦了? :)

自定义属性以利用 semantic-uiPopup(气泡提示) 功能:

鼠标悬停 [此处](#){: data-tooltip="此处应该有气泡提示 O(∩_∩)O~~" } 以查看效果。

渲染结果:

鼠标悬停 此处 以查看效果。

在 Markdown 文档中插入 mermaid 图表:

sequenceDiagram
loop every day
   Alice->>John: Hello John, how are you?
   John-->>Alice: Great!
end
{: .mermaid }

渲染结果:

sequenceDiagram loop every day Alice->>John: Hello John, how are you? John-->>Alice: Great! end

除此之外,属性列表(Attribute Lists) 应该还有很多别的玩法,这里就不再继续演示了。

最后,以上介绍的两种语法:告诫(Admonition)和属性列表(Attribute Lists)在绝大多数 Markdown 编辑器中均不受支持。如果你的目标输出格式为静态博客(HTML)等,这点倒是不必担心,只是 Markdown 编辑器缺乏相应的实时预览功能罢了;如果是其它输出格式,则尽量不要使用这两种语法。请根据实际情况自行权衡。

最后的最后,本文以及一些早期文章均使用 Markdown 语法书写,你可以点击文章标题下方的 edit 查看源文件。