markdown-it 外掛如何寫（三）

冴羽發表於2022-01-28

前言

在 《一篇帶你用 VuePress + Github Pages 搭建部落格》中，我們使用 VuePress 搭建了一個部落格，最終的效果檢視：TypeScript 中文文件。

在搭建部落格的過程中，我們出於實際的需求，在《VuePress 部落格優化之擴充 Markdown 語法》中講解了如何寫一個 markdown-it外掛，又在 《markdown-it 原理解析》中講解了 markdown-it的執行原理，本篇我們將講解具體的實戰程式碼，幫助大家更好的寫外掛。

markdown-it-inline

markdown-it 的作者提供了 markdown-it-inine 用於方便修改 inline tokens 。舉個例子，如果我們給所有的連結新增 target="_blank"，正常你需要這樣寫：

// Remember old renderer, if overridden, or proxy to default renderer
var defaultRender = md.renderer.rules.link_open || function(tokens, idx, options, env, self) {
  return self.renderToken(tokens, idx, options);
};

md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
  // If you are sure other plugins can't add `target` - drop check below
  var aIndex = tokens[idx].attrIndex('target');

  if (aIndex < 0) {
    tokens[idx].attrPush(['target', '_blank']); // add new attribute
  } else {
    tokens[idx].attrs[aIndex][1] = '_blank';    // replace value of existing attr
  }

  // pass token to default renderer.
  return defaultRender(tokens, idx, options, env, self);
};

使用markdown-it-for-inline 後：

var iterator = require('markdown-it-for-inline');

var md = require('markdown-it')()
            .use(iterator, 'url_new_win', 'link_open', function (tokens, idx) {
              var aIndex = tokens[idx].attrIndex('target');

              if (aIndex < 0) {
                tokens[idx].attrPush(['target', '_blank']);
              } else {
                tokens[idx].attrs[aIndex][1] = '_blank';
              }
            });

如果我們要替換掉某個文字，也可以使用 markdown-it-for-inline：

var iterator = require('markdown-it-for-inline');

// plugin params are:
//
// - rule name (should be unique)
// - token type to apply
// - function
//
var md = require('markdown-it')()
            .use(iterator, 'foo_replace', 'text', function (tokens, idx) {
              tokens[idx].content = tokens[idx].content.replace(/foo/g, 'bar');
            });

markdown-it-container

Plugin for creating block-level custom containers for markdown-it markdown parser.

markdown-it 的作者同樣提供了 markdown-it-container 用於快速建立塊級自定義容器。

有了這個外掛，你可以這樣使用 markdown 語法：

::: spoiler click me
*content*
:::

注意這其中的 ::: 是外掛定義的語法，它會取出 ::: 後的字元，在這個例子中是 warning，並提供方法自定義渲染結果：

var md = require('markdown-it')();

md.use(require('markdown-it-container'), 'spoiler', {

  validate: function(params) {
    return params.trim().match(/^spoiler\s+(.*)$/);
  },

  render: function (tokens, idx) {
    // 通過 tokens[idx].info.trim() 取出 'click me' 字串
    var m = tokens[idx].info.trim().match(/^spoiler\s+(.*)$/);

    // 開始標籤的 nesting 為 1，結束標籤的 nesting 為 -1
    if (tokens[idx].nesting === 1) {
      // 開始標籤
      return '<details><summary>' + md.utils.escapeHtml(m[1]) + '</summary>\n';
    } else {
      // 結束標籤
      return '</details>\n';
    }
  }
});

最終渲染的結果為：

<details><summary>click me</summary>
<p><em>content</em></p>
</details>

像 VuePress 提供了自定義容器：

其實就是用 markdown-it-container 實現的，其實現原始碼為：

const container = require('markdown-it-container')

module.exports = md => {
  md
    .use(...createContainer('tip', 'TIP'))
    .use(...createContainer('warning', 'WARNING'))
    .use(...createContainer('danger', 'WARNING'))
        // ...
}

function createContainer (klass, defaultTitle) {
  return [container, klass, {
    render (tokens, idx) {
      const token = tokens[idx]
      const info = token.info.trim().slice(klass.length).trim()
      if (token.nesting === 1) {
        return `<div class="${klass} custom-block"><p class="custom-block-title">${info || defaultTitle}</p>\n`
      } else {
        return `</div>\n`
      }
    }
  }]
}

系列文章

部落格搭建系列是我至今寫的唯一一個偏實戰的系列教程，預計 20 篇左右，講解如何使用 VuePress 搭建、優化部落格，並部署到 GitHub、Gitee、私有伺服器等平臺。本篇為第 18 篇，全系列文章地址：https://github.com/mqyqingfeng/Blog

微信：「mqyqingfeng」，加我進冴羽唯一的讀者群。

如果有錯誤或者不嚴謹的地方，請務必給予指正，十分感謝。如果喜歡或者有所啟發，歡迎 star，對作者也是一種鼓勵。

相關文章