在搭建博客的过程中,我们出于实际的需求,在《VuePress 博客优化之拓展 Markdown 语法》中讲解了如何写一个 markdown-it插件,又在 《markdown-it 原理解析》中讲解了 markdown-it的执行原理,本篇我们将讲解具体的实战代码,帮助大家更好的写插件。

Parse

markdown-it的渲染过程分为两部分,Parse 和 Render,如果我们要实现新的 markdown 语法,举个例子,比如我们希望解析 @ header 为

header

,就可以从 Parse 过程入手。
markdown-it 的官方文档里可以找到自定义 parse 规则的方式,那就是通过 Ruler 类:

  1. var md = require('markdown-it')();
  2. md.block.ruler.before('paragraph', 'my_rule', function replace(state) {
  3. //...
  4. });

这句话的意思是指在 markdown-it 的解析 block 的一组规则中,在 paragraph 规则前插入一个名为 my_rule 的自定义规则,我们慢慢来解释。
首先是 md.block.ruler,除此之外,还有 md.inline.ruler、md.core.ruler可以自定义其中的规则。
然后是 .before,查看 Ruler 相关的 API,还有 after、at、disable、enable等方法,这是因为规则是按照顺序执行的,某一规则的改变可能会影响其他规则。
接着是 paragraph,我怎么知道插入在哪个规则前面或者后面呢?这就需要你看源码了,并没有文档给你讲这个……
如果是md.block,查看 parse_block.js,如果是md.inline,查看 parse_inline.js,如果是 md.core,查看 parse_core.js,我们以md.block为例,可以看到源码里写了这些规则:

  1. var _rules = [
  2. // First 2 params - rule name & source. Secondary array - list of rules,
  3. // which can be terminated by this one.
  4. [ 'table', require('./rules_block/table'), [ 'paragraph', 'reference' ] ],
  5. [ 'code', require('./rules_block/code') ],
  6. [ 'fence', require('./rules_block/fence'), [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  7. [ 'blockquote', require('./rules_block/blockquote'), [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  8. [ 'hr', require('./rules_block/hr'), [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  9. [ 'list', require('./rules_block/list'), [ 'paragraph', 'reference', 'blockquote' ] ],
  10. [ 'reference', require('./rules_block/reference') ],
  11. [ 'html_block', require('./rules_block/html_block'), [ 'paragraph', 'reference', 'blockquote' ] ],
  12. [ 'heading', require('./rules_block/heading'), [ 'paragraph', 'reference', 'blockquote' ] ],
  13. [ 'lheading', require('./rules_block/lheading') ],
  14. [ 'paragraph', require('./rules_block/paragraph') ]
  15. ];

最后是function replace(state),这里函数的参数其实不止有 state,我们查看任何一个具体规则的 parse 代码,就比如 heading.js:

  1. module.exports = function heading(state, startLine, endLine, silent) {
  2. var ch, level, tmp, token,
  3. pos = state.bMarks[startLine] + state.tShift[startLine],
  4. max = state.eMarks[startLine];
  5. // ...
  6. };

可以看出除了 state,还有 startLine、endLine、silent,而具体这其中的代码怎么写,其实最好的方式就是参考这些已经实现的代码。

实例讲解

接下来我们以解析 @ header 为

header

为例,讲解其中涉及的代码,这是要渲染的内容:

  1. var md = window.markdownit();
  2. // md.block.ruler.before(...)
  3. var result = md.render(`@ header
  4. contentTwo
  5. `);
  6. console.log(result);

正常它的渲染结果是:

  1. <p>@ header
  2. contentTwo</p>

现在期望的渲染结果是:

  1. <h1>header</h1>
  2. <p>contentTwo</p>

我们来看看如何实现,先参照 header.js 的代码依葫芦画瓢:

  1. md.block.ruler.before('paragraph','@header',function(state, startLine, endLine, silent){
  2. var ch, level, tmp, token,
  3. pos = state.bMarks[startLine] + state.tShift[startLine],
  4. max = state.eMarks[startLine];
  5. //...
  6. })

parse 的过程是根据换行符逐行扫描的,所以每一行的内容都会执行我们这个自定义函数进行匹配,函数支持传入四个参数,其中,state 记录了各种状态数据,startLine 表示本次的起始行数,而 endLine 表示总的结束行数。
我们打印下 state``startLine,endLine 等数据:

  1. md.block.ruler.before('paragraph','@header',function(state, startLine, endLine, silent){
  2. var ch, level, tmp, token,
  3. pos = state.bMarks[startLine] + state.tShift[startLine],
  4. max = state.eMarks[startLine];
  5. console.log(JSON.parse(JSON.stringify(state)), startLine, endLine);
  6. })

这是打印的结果:
markdown-it 插件如何写(二) - 图1
其中 state 的内容我们简化下展示出来:

  1. {
  2. "src": "@ header\ncontentTwo\n",
  3. "md": {...},
  4. "env": {...},
  5. "tokens": [...],
  6. "bMarks": [0, 9, 20],
  7. "eMarks": [8, 19, 20],
  8. "tShift": [0, 0, 0],
  9. "line": 0
  10. }

state 中这些字段的具体含义可以查看 state_block.js 文件,这其中:

  • bMarks 表示每一行的起始位置
  • eMarks 表示每一行的终止位置
  • tShift 表示每一行第一个非空格字符的位置

我们看下 pos 的计算逻辑为 state.bMarks[startLine] + state.tShift[startLine],其中 startLine 是 0,所以 pos = 0 + 0 = 0
再看下 max 的计算逻辑为 state.eMarks[startLine],所以max = 8
从这也可以看出,其实 pos 就是这行字符的初始位置,max 这行字符的结束位置,通过 pos 和 max,我们可以截取出这行字符串:

  1. md.block.ruler.before('paragraph','@header',function(state, startLine, endLine, silent){
  2. var ch, level, tmp, token,
  3. pos = state.bMarks[startLine] + state.tShift[startLine],
  4. max = state.eMarks[startLine];
  5. console.log(JSON.parse(JSON.stringify(state)), startLine, endLine);
  6. let text = state.src.substring(pos, max);
  7. console.log(text);
  8. state.line = startLine + 1;
  9. return true
  10. })

打印结果为:
markdown-it 插件如何写(二) - 图2
在代码里我们加入了state.line = startLine + 1;和 return true,这是为了进入到下一行的遍历之中。
如果我们能取出每次用于判断的字符串,那我们就可以进行正则匹配,如果匹配,就自定义 tokens,剩下的逻辑很简单,我们直接给出最后的代码:

  1. md.block.ruler.before('paragraph', 'myplugin', function (state,startLine,endLine) {
  2. var ch, level, tmp, token,
  3. pos = state.bMarks[startLine] + state.tShift[startLine],
  4. max = state.eMarks[startLine];
  5. ch = state.src.charCodeAt(pos);
  6. if (ch !== 0x40/*@*/ || pos >= max) { return false; }
  7. let text = state.src.substring(pos, max);
  8. let rg = /^@\s(.*)/;
  9. let match = text.match(rg);
  10. if (match && match.length) {
  11. let result = match[1];
  12. token = state.push('heading_open', 'h1', 1);
  13. token.markup = '@';
  14. token.map = [ startLine, state.line ];
  15. token = state.push('inline', '', 0);
  16. token.content = result;
  17. token.map = [ startLine, state.line ];
  18. token.children = [];
  19. token = state.push('heading_close', 'h1', -1);
  20. token.markup = '@';
  21. state.line = startLine + 1;
  22. return true;
  23. }
  24. })

至此,就实现了预期的效果:
markdown-it 插件如何写(二) - 图3