> 本篇已收录到我的掘金专栏[《博客搭建系列》](https://juejin.cn/column/7041871760995647502)，该系列一共 33 篇文章。 > > 欢迎围观我的[“朋友圈”](https://yayujs.com)、加入[“低调务实优秀中国好青年”](https://www.yuque.com/yayu/nice-people/xou8qr)前端社群，分享技术，带你成长。 ## 前言在 [《一篇带你用 VuePress + Github Pages 搭建博客》](https://github.com/mqyqingfeng/Blog/issues/235)中，我们使用 VuePress 搭建了一个博客，最终的效果查看：[TypeScript 中文文档](http://ts.yayujs.com/)。在搭建博客的过程中，我们出于实际的需求，在[《VuePress 博客优化之拓展 Markdown 语法》](https://github.com/mqyqingfeng/Blog/issues/251)中讲解了如何写一个 `markdown-it`插件，本篇我们将深入`markdown-it`的源码，讲解 `markdown-it`的执行原理，旨在让大家对 `markdown-it`有更加深入的理解。 ## 介绍引用 [markdown-it Github 仓库](https://github.com/markdown-it/markdown-it)的介绍： > Markdown parser done right. Fast and easy to extend. 可以看出 `markdown-it`是一个 markdown 解析器，并且易于拓展。其演示地址为： `markdown-it`具有以下几个优势： * 遵循 [CommonMark spec](http://spec.commonmark.org/) 并且添加了语法拓展和语法糖（如URL 自动识别，针对印刷做了特殊处理） * 可配置语法，你可以添加新的规则或者替换掉现有的规则 * 快 * 默认安全 * 社区有很多的[插件](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)或者[其他包](https://www.npmjs.com/search?q=keywords:markdown-it) ## 使用 ```bash // 安装 npm install markdown-it --save ``` ```javascript // node.js, "classic" way: var MarkdownIt = require('markdown-it'), md = new MarkdownIt(); var result = md.render('# markdown-it rulezz!'); // browser without AMD, added to "window" on script load // Note, there is no dash in "markdownit". var md = window.markdownit(); var result = md.render('# markdown-it rulezz!'); ``` ## 源码解析我们查看 `markdown-it` 的[入口代码](https://github.com/markdown-it/markdown-it/blob/master/lib/index.js)，可以发现其代码逻辑清晰明了： ```javascript // ... var Renderer = require('./renderer'); var ParserCore = require('./parser_core'); var ParserBlock = require('./parser_block'); var ParserInline = require('./parser_inline'); function MarkdownIt(presetName, options) { // ... this.inline = new ParserInline(); this.block = new ParserBlock(); this.core = new ParserCore(); this.renderer = new Renderer(); // ... } MarkdownIt.prototype.parse = function (src, env) { // ... var state = new this.core.State(src, this, env); this.core.process(state); return state.tokens; }; MarkdownIt.prototype.render = function (src, env) { env = env || {}; return this.renderer.render(this.parse(src, env), this.options, env); }; ``` 从 `render`方法中也可以看出，其渲染分为两个过程： 1. Parse：将 Markdown 文件 Parse 为 Tokens 2. Render：遍历 Tokens 生成 HTML 跟 Babel 很像，不过 Babel 是转换为抽象语法树（AST），而 `markdown-it` 没有选择使用 AST，主要是为了遵循 KISS(**Keep It Simple, Stupid**) 原则。 ## Tokens 那 Tokens 长什么样呢？我们不妨在[演示页面](https://markdown-it.github.io/)中尝试一下： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e13173fe23db467996b1fe1a7e1adcc0~tplv-k3u1fbpfcp-zoom-1.image#?w=2420\&h=596\&s=83113\&e=png\&b=fbfbfb) 可以看出 `# header`生成的 Token 格式为（注：这里为了展示方便，简化了）： ```json [ { "type": "heading_open", "tag": "h1" }, { "type": "inline", "tag": "", "children": [ { "type": "text", "tag": "", "content": "header" } ] }, { "type": "heading_close", "tag": "h1" } ] ``` 具体 Token 里的字段含义可以查看 [Token Class](https://github.com/markdown-it/markdown-it/blob/master/lib/token.js)。通过这个简单的 Tokens 示例也可以看出 Tokens 和 AST 的区别： 1. Tokens 只是一个简单的数组 2. 起始标签和闭合标签是分开的 ## Parse 查看 parse 方法相关的代码： ```javascript // ... var ParserCore = require('./parser_core'); function MarkdownIt(presetName, options) { // ... this.core = new ParserCore(); // ... } MarkdownIt.prototype.parse = function (src, env) { // ... var state = new this.core.State(src, this, env); this.core.process(state); return state.tokens; }; ``` 可以看到其具体执行的代码，应该是写在了`./parse_core` 里，查看下 `parse_core.js` 的代码： ```javascript var _rules = [ [ 'normalize', require('./rules_core/normalize') ], [ 'block', require('./rules_core/block') ], [ 'inline', require('./rules_core/inline') ], [ 'linkify', require('./rules_core/linkify') ], [ 'replacements', require('./rules_core/replacements') ], [ 'smartquotes', require('./rules_core/smartquotes') ] ]; function Core() { // ... } Core.prototype.process = function (state) { // ... for (i = 0, l = rules.length; i < l; i++) { rules[i](state); } }; ``` 可以看出，Parse 过程默认有 6 条规则，其主要作用分别是： ### 1. normalize 在 CSS 中，我们使用`normalize.css` 抹平各端差异，这里也是一样的逻辑，我们查看 normalize 的代码，其实很简单： ```javascript // https://spec.commonmark.org/0.29/#line-ending var NEWLINES_RE = /\r\n?|\n/g; var NULL_RE = /\0/g; module.exports = function normalize(state) { var str; // Normalize newlines str = state.src.replace(NEWLINES_RE, '\n'); // Replace NULL characters str = str.replace(NULL_RE, '\uFFFD'); state.src = str; }; ``` 我们知道 `\n`是匹配一个换行符，`\r`是匹配一个回车符，那这里为什么要将 `\r\n`替换成 `\n` 呢? 我们可以在阮一峰老师的这篇 [《回车与换行》](https://www.ruanyifeng.com/blog/2006/04/post_213.html)中找到`\r\n`出现的历史： > 在计算机还没有出现之前，有一种叫做电传打字机（Teletype Model 33）的玩意，每秒钟可以打10个字符。但是它有一个问题，就是打完一行换行的时候，要用去0.2秒，正好可以打两个字符。要是在这0.2秒里面，又有新的字符传过来，那么这个字符将丢失。 > 于是，研制人员想了个办法解决这个问题，就是在每行后面加两个表示结束的字符。一个叫做"回车"，告诉打字机把打印头定位在左边界；另一个叫做"换行"，告诉打字机把纸向下移一行。 > 这就是"换行"和"回车"的来历，从它们的英语名字上也可以看出一二。 > 后来，计算机发明了，这两个概念也就被般到了计算机上。那时，存储器很贵，一些科学家认为在每行结尾加两个字符太浪费了，加一个就可以。于是，就出现了分歧。 > Unix系统里，每行结尾只有"<换行>"，即"\n"；Windows系统里面，每行结尾是"<回车><换行>"，即"\r\n"；Mac系统里，每行结尾是"<回车>"。一个直接后果是，Unix/Mac系统下的文件在Windows里打开的话，所有文字会变成一行；而Windows里的文件在Unix/Mac下打开的话，在每行的结尾可能会多出一个^M符号。之所以将 `\r\n`替换成 `\n`其实是[遵循规范](https://spec.commonmark.org/0.29/#line-ending)： > A line ending is a newline (U+000A), a carriage return (U+000D) not followed by a newline, or a carriage return and a following newline. 其中 U+000A 表示换行(LF) ，U+000D 表示回车(CR) 。除了替换回车符外，源码里还替换了空字符，在[正则](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Regular_Expressions#special-null)中，`\0`表示匹配 NULL（U+0000）字符，根据 [WIKI](https://zh.wikipedia.org/wiki/%E7%A9%BA%E5%AD%97%E7%AC%A6) 的解释： > 空字符（Null character）又称结束符，缩写 NUL，是一个数值为 0 的控制字符。 > 在许多字符编码中都包括空字符，包括ISO/IEC 646（ASCII）、C0控制码、通用字符集、Unicode和EBCDIC等，几乎所有主流的编程语言都包括有空字符 > 这个字符原来的意思类似NOP指令，当送到列表机或终端时，设备不需作任何的动作（不过有些设备会错误的打印或显示一个空白）。而我们将空字符替换为 `\uFFFD`，在 Unicode 中，`\uFFFD`表示替换字符： [![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f1e44506eb6645c29365d53fbd18a6de~tplv-k3u1fbpfcp-zoom-1.image#?w=778\&h=352\&s=17761\&e=png\&b=ffffff)](https://unicode-table.com/cn/FFFD/) 之所以进行这个替换，其实也是遵循规范，我们查阅 [CommonMark spec 2.3 章节](https://spec.commonmark.org/0.30/#insecure-characters)： > For security reasons, the Unicode character U+0000 must be replaced with the REPLACEMENT CHARACTER (U+FFFD). 我们测试下这个效果： ```javascript md.render('foo\u0000bar'), '

foo\uFFFDbar

\n' ``` 效果如下，你会发现原本不可见的**空字符**被替换成**替换字符**后，展示了出来： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7a4b2cb9df1744a6a7f333e4badf5f36~tplv-k3u1fbpfcp-zoom-1.image#?w=638\&h=204\&s=25110\&e=png\&b=202124) ### 2. block block 这个规则的作用就是找出 block，生成 tokens，那什么是 block？什么是 inline 呢？我们也可以在[CommonMark spec 中的 Blocks and inlines 章节](https://spec.commonmark.org/0.30/#blocks-and-inlines) 找到答案： > We can think of a document as a sequence of [blocks](https://spec.commonmark.org/0.30/#blocks)—structural elements like paragraphs, block quotations, lists, headings, rules, and code blocks. Some blocks (like block quotes and list items) contain other blocks; others (like headings and paragraphs) contain [inline](https://spec.commonmark.org/0.30/#inline) content—text, links, emphasized text, images, code spans, and so on. 翻译一下就是：我们认为文档是由一组 blocks 组成，结构化的元素类似于段落、引用、列表、标题、代码区块等。一些 blocks （像引用和列表）可以包含其他 blocks，其他的一些 blocks（像标题和段落）则可以包含 inline 内容，比如文字、链接、强调文字、图片、代码片段等等。当然在`markdown-it`中，哪些会识别成 blocks，可以查看 [parser\_block.js](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_block.js)，这里同样定义了一些识别和 parse 的规则： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5c75ed0913ca490dad70dcb9a2569dd6~tplv-k3u1fbpfcp-zoom-1.image#?w=1604\&h=614\&s=161592\&e=png\&b=0e1116) 关于这些规则我挑几个不常见的说明一下: `code` 规则用于识别 `Indented code blocks` (4 spaces padded)，在 markdown 中: ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5d52b104c72c4543827ed517d6b3df66~tplv-k3u1fbpfcp-zoom-1.image#?w=1772\&h=286\&s=38508\&e=png\&b=ffffff) `fence` 规则用于识别 Fenced code blocks，在markdown 中： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ea24939e373a4baeb74b79b2c0039ede~tplv-k3u1fbpfcp-zoom-1.image#?w=1742\&h=330\&s=30918\&e=png\&b=d1d6da) `hr` 规则用于识别换行，在 markdown 中： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e68e461b2dd2475dadd8bad239e0771f~tplv-k3u1fbpfcp-zoom-1.image#?w=1768\&h=182\&s=15114\&e=png\&b=ffffff) `reference` 规则用于识别 `reference links`，在 markdown 中： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f9bd3ecd436640fa84d732ca70671ee7~tplv-k3u1fbpfcp-zoom-1.image#?w=1712\&h=258\&s=31019\&e=png\&b=ffffff) `html_block` 用于识别 markdown 中的 HTML block 元素标签，就比如`div`。 `lheading` 用于识别 `Setext headings`，在 markdown 中： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c259cf851cd64f068ae55bb272620f54~tplv-k3u1fbpfcp-zoom-1.image#?w=1730\&h=344\&s=37711\&e=png\&b=ffffff) ### 3. inline inline 规则的作用则是解析 markdown 中的 inline，然后生成 tokens，之所以 block 先执行，是因为 block 可以包含 inline ，解析的规则可以查看 [parser\_inline.js](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_inline.js)： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/864fe3443e844aa4afb2f7dfea5709b7~tplv-k3u1fbpfcp-zoom-1.image#?w=1120\&h=530\&s=100464\&e=png\&b=0e1116) 关于这些规则我挑几个不常见的说明一下: `newline`规则用于识别 `\n`，将 `\n` 替换为一个 hardbreak 类型的 token `backticks` 规则用于识别反引号： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/641b4c5bc1604fb0b5898f5371f0404f~tplv-k3u1fbpfcp-zoom-1.image#?w=1746\&h=180\&s=19930\&e=png\&b=ffffff) `entity` 规则用于处理 HTML entity，比如 `{``¯``"`等： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9b72b044d8d34f97a7f13f64e5fd0fc5~tplv-k3u1fbpfcp-zoom-1.image#?w=2370\&h=268\&s=28462\&e=png\&b=fdfdfd) ### 4. linkify 自动识别链接 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d7d711f1e9fc49bab4ed4b83cf25101f~tplv-k3u1fbpfcp-zoom-1.image#?w=2352\&h=324\&s=59964\&e=png\&b=fafafa) ### 5. replacements 将 `(c)`` (C)` 替换成 `©`，将 `????????` 替换成 `???`，将 `!!!!!` 替换成 `!!!`，诸如此类： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2b6b7a1c5eee456f9929aea2bf5833ba~tplv-k3u1fbpfcp-zoom-1.image#?w=2344\&h=210\&s=31609\&e=png\&b=fefefe) ### 6. smartquotes 为了方便印刷，对直引号做了处理： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8de70de222264e82a0355fbc789ddc3f~tplv-k3u1fbpfcp-zoom-1.image#?w=2344\&h=70\&s=18597\&e=png\&b=fefefe) ## Render Render 过程其实就比较简单了，查看 [renderer.js](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js) 文件，可以看到内置了一些默认的渲染 rules： ```javascript default_rules.code_inline default_rules.code_block default_rules.fence default_rules.image default_rules.hardbreak default_rules.softbreak default_rules.text default_rules.html_block default_rules.html_inline ``` 其实这些名字也是 token 的 type，在遍历 token 的时候根据 token 的 type 对应这里的 rules 进行执行，我们看下 code\_inline 规则的内容，其实非常简单： ```javascript default_rules.code_inline = function (tokens, idx, options, env, slf) { var token = tokens[idx]; return '' + escapeHtml(tokens[idx].content) + ''; }; ``` ## 自定义 Rules 至此，我们对 markdown-it 的渲染原理进行了简单的了解，无论是 Parse 还是 Render 过程中的 Rules，markdown-it 都提供了方法可以自定义这些 Rules，这些也是写 markdown-it 插件的关键，这些后续我们会讲到。 ## 博客搭建系列博客搭建系列讲解如何使用 VuePress 搭建、优化博客，并部署到 GitHub、Gitee、私有服务器等平台。本篇已收录到我的掘金专栏[《博客搭建系列》](https://juejin.cn/column/7041871760995647502)，该系列一共 33 篇文章。此外我还写过 [JavaScript 系列](https://juejin.cn/column/7035531575974592520)、[TypeScript 系列](https://juejin.cn/column/7029490086710345742)、[React 系列](https://juejin.cn/column/7142674773930147853)、[Next.js 系列](https://juejin.cn/column/7343569488744611849)、[冴羽答读者问](https://juejin.cn/column/7039526067891077151)等 14 个系列文章，全系列文章目录：通过文字建立交流本身就是一种缘分，欢迎围观我的[“朋友圈”](https://yayujs.com)、加入[“低调务实优秀中国好青年”](https://www.yuque.com/yayu/nice-people/xou8qr)前端社群，分享技术，带你成长。