Markdown Preview 目录 MathJax 代码高亮
背景
近期 Sublime Text Markdown Preview 更新后，原来能用的功能现在不能用了。自己用到的有[TOC]自动生成目录， MathJax 插入公式，都没有了效果。
调查发现，现在的 Markdown Preview 插件维护在 facelessuser/MarkdownPreview ，底层实现改用了两种方式：本地的 Python-Markdown/markdown ，以及在线的 Github Markdown API 。
因此，比如 Stack Overflow 上这个打开 MathJax 支持的回答其实已经过时了。
新的设置方法参见官方文档，这里简单介绍一下即开即用的日常使用。
添加和设置插件
官方提供了完整用法，主要步骤如下：
-
通过
Preferences -> Package Settings -> Markdown Preview -> Settings打开配置文件。 -
在
User部分添加"markdown_extensions": [ ext1, ext2, ... ],其中
ext1，ext2要么是一个字符串，要么是一个字典。
比如默认设置的一段："markdown_extensions": [ "markdown.extensions.abbr", { "markdown.extensions.codehilite": { "guess_lang": false } } ]同 Sublime 其他插件的设置方法一样，如果没有指明，使用的是默认值，如果指明了，进行 override 。但注意，这些插件并非默认开启，而设置是默认存在的。
还有一种作者没有明确指出，但是在示例中出现，而且更加简洁高效的写法，那就是直接写成一个字典："markdown_extensions": { "pymdownx.arithmatex": {}, "markdown.extensions.toc": {}, "markdown.extensions.codehilite": { "guess_lang": true }, },注意到使用默认选项的字典留空。
Python-Markdown 官方支持且默认安装的插件列表在这里。
特别地，这个插件的作者自己建了另一个仓库 facelessuser/pymdown-extensions 放了一大堆使用接口编写的插件，都和 Markdown Preview 一起默认安装了。
因此，设置开启就能使用的插件是两个的并集。 -
添加额外需要使用的 js 、 css 方法如下：
"css": ["default"], "js": [...]
目录支持
原有版本默认开启这一功能，更新后需要手动开启。使用官方提供的插件，只需要添加
"markdown_extensions": {
"markdown.extensions.toc": {}
},
在需要使用的地方插入 [TOC] 即可生成目录。
MathJax 支持
根据上面的方法，我们为 Markdown Preview 添加 MathJax 支持。
与上面的插件不同，这个插件是 pymdownx 提供的，因此添加到字典中：
"markdown_extensions": {
"pymdownx.arithmatex": {},
"markdown.extensions.toc": {},
},
如果使用 MathJax ，需要提供 js 文件的 URL ， 因此在扩展列表前添加：
"js": [
"https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js",
"res://MarkdownPreview/js/math_config.js"
],
这里可以查到可用的选项。
代码高亮支持
这里使用的是官方扩展 CodeHilite ，底层使用 Pygments 进行多语言的代码高亮。将其添加到扩展字典中：
"markdown_extensions": {
"pymdownx.arithmatex": {},
"markdown.extensions.toc": {},
"markdown.extensions.codehilite": {
"guess_lang": true
},
},
其中，guess_lang 如果为真，则会自动推测语言，如果为假，则只有指定时才进行高亮。
顺便简单介绍一下 Pygments 语法规则：
在 Code Block 前，如果有……
- Sheang with path ，比如
#!/usr/bin/python，则会保留该行，并设置语言为 Python 。 - Shebang without path ，比如
#!python，则会删除该行，并设置语言为 Python 。 - 三个或以上冒号， Three or more colons ，比如
:::python，则会删除该行，并设置语言为 Python 。
在第三种情况下，还可以进行行高亮等 CSS 中定义的操作。比如 :::python hl_lines="1 3" 会将第 1 、 3 行代码高亮。
注意
使用 CodeHilite 会造成 preview/build 的行为改变。
Markdown 规范中，缩进标志代码块（code block），对应 HTML 的 <pre> 标签；反引号（back quote）标志行内代码（inline code 或 inline code span），对应 HTML 的 <code> 标签。
当行内代码希望使用反引号时，可以使用两或三个引号作为开始和结束的标志。
按照规范，<code> 内的换行和空格不应被保留，而 <pre> 则完全保留样式。因此，使用缩进表示代码块是更加规范的用法。然而有些平台不加以区分，使用三个反引号也可以作为代码块标志（比如简书），因此，也就有了两种表示的说法。
不开启 CodeHilite 前， Markdown Preview 会将三个反引号编译成为代码块，开启后，变成普通文本。因此，使用高亮时，应配合使用缩进表示法。
总结
通过以上三个例子，本文展示了 Sublime Text Markdown Preview 插件中添加和配置扩展的方式。虽然相比以前默认开启，或者改动一个选项就能开启麻烦了一点，但使用统一的 Python Markdown API 可以很方便的添加第三方功能。对于已有功能的行为也可以实现精细的控制。总的来说还是不错的。
此外，查找资料时应检查日期，现在 Google 搜索 sublime markdown preview mathjax ，排名第一的还是那个过时的 Stack Overflow 回答。这种事情，还是自己查文档比较靠谱。
