我是如何阅读 md-loader 源码并优化它的？
背景
相信很多同学在学习 webpack 的时候，对 loader 的概念应该有所了解，它用于模块源码的转换，描述了 webpack 如何处理非 JavaScript 模块，常见的有 css-loader、babel-loader、url-loader、vue-loader 等。
大部分 loader 已经满足我们的日常开发需求，不过有些时候我们仍然需要自定义 loader。为了让你了解如何开发一个 webpack loader，我决定从 ElementUI 组件库的 md-loader 入手，带你去了解其中的实现原理，以及在它的基础上，如何做进一步的优化。
文档的设计
对于一个组件的文档，首先我们要考虑的是如何更好地展现组件的功能，其次要考虑的是如何更方便地做文档维护。
想要编写好一个组件的文档，需要做好以下几点：
1.功能描述
对组件功能、使用场景做详细的描述。
2.demo 演示
直观地让用户感受到组件的功能，并且能展示 demo 对应的代码。
3.接口说明
写清楚组件支持的属性、方法、事件等。
那么，如何方便地维护文档呢？
ElementUI 组件库的文档也是一个 Vue 项目，组件的文档页面是单独的路由视图，而文档是用 markdown 文件来描述的，在文档内部，不仅包含了对组件的功能以及接口的描述，还可以通过编写 vue 组件的方式直接编写组件的 demo，这种方式对于组件文档的维护还是比较方便的。
以 ElementUI 组件库 Alter 组件为例：
## Alert 警告
用于页面中展示重要的提示信息。
### 基本用法
页面中的非浮层元素，不会自动消失。
:::demo Alert 组件提供四种主题，由`type`属性指定，默认值为`info`。
```html
title="成功提示的文案"
type="success">
title="消息提示的文案"
type="info">
title="警告提示的文案"
type="warning">
title="错误提示的文案"
type="error">
```
:::
最终它在页面上的展示效果如下：
可以看到，组件的路由视图对应的是一个 markdown 文件，而在我们通常的认知中，Vue 的路由视图应该对应的是一个 Vue 组件。
在 ElementUI 内部，是通过 require.ensure 的方式去加载一个 .md 文件，它的返回值会作为路由视图对应的异步组件。
const LOAD_DOCS_MAP = {
'zh-CN': path => {
return r => require.ensure([], () =>
r(require(`./docs/zh-CN${path}.md`)),
'zh-CN');
},
// ...
}
因此内部就必须要把 markdown 文件转换一个 Vue 组件，我们可以借助 webpack loader 来实现这一需求。
自定义 md-loader
首先，在 webpack 的配置规则中，需要指定 .md 文件应用的 loader：
{
test: /\.md$/,
use: [
{
loader: 'vue-loader',
options: {
compilerOptions: {
preserveWhitespace: false
}
}
},
{
loader: path.resolve(__dirname, './md-loader/index.js')
}
]
}
接下来，我们就来分析 md-loader 的源码实现：
const {
stripScript,
stripTemplate,
genInlineComponentText
} = require('./util');
const md = require('./config');
module.exports = function(source) {
const content = md.render(source);
const startTag = '';
const endTagLen = endTag.length;
let componenetsString = '';
let id = 0; // demo 的 id
let output = []; // 输出的内容
let start = 0; // 字符串开始位置
let commentStart = content.indexOf(startTag);
let commentEnd = content.indexOf(endTag, commentStart + startTagLen);
while (commentStart !== -1 && commentEnd !== -1) {
output.push(content.slice(start, commentStart));
const commentContent = content.slice(commentStart + startTagLen, commentEnd);
const html = stripTemplate(commentContent);
const script = stripScript(commentContent);
let demoComponentContent = genInlineComponentText(html, script);
const demoComponentName = `element-demo${id}`;
output.push(`<${demoComponentName} />` );
componenetsString += `${JSON.stringify(demoComponentName)}: ${demoComponentContent},`;
// 重新计算下一次的位置
id++;
start = commentEnd + endTagLen;
commentStart = content.indexOf(startTag, start);
commentEnd = content.indexOf(endTag, commentStart + startTagLen);
}
// 仅允许在 demo 不存在时，才可以在 Markdown 中写 script 标签
let pageScript = '';
if (componenetsString) {
pageScript = ``;
} else if (content.indexOf('') + ''.length;
pageScript = content.slice(0, start);
}
output.push(content.slice(start));
return `
${output.join('')}
${pageScript}
`;
};
md-loader 要做的事情，就是把 markdown 语法的字符串，转成 Vue 组件字符串。转换的过程可以拆成三个步骤：markdown 渲染，demo 子组件的处理，构造完整的组件。接下来我们就来依次分析这三个步骤。
markdown 渲染
markdown 文件内容会渲染生成对应的 HTML，它是通过下面这段代码完成的：
const md = require('./config');
module.exports = function(source) {
const content = md.render(source);
}
而 md 对象的来源如下：
const Config = require('markdown-it-chain');
const anchorPlugin = require('markdown-it-anchor');
const slugify = require('transliteration').slugify;
const containers = require('./containers');
const overWriteFenceRule = require('./fence');
const config = new Config();
config.options.html(true).end()
.plugin('anchor').use(anchorPlugin, [
{
level: 2,
slugify: slugify,
permalink: true,
permalinkBefore: true
}
]).end()
.plugin('containers').use(containers).end();
const md = config.toMd();
overWriteFenceRule(md);
module.exports = md;
首先实例化了 config 对象，它依赖于 markdown-it-chain，通过 webpack chain 的链式 API，配置了 markdown-it 的插件。而 md 对象指向的就是 markdown-it 的实例。
markdown-it 的实例提供了很多 API，具体可以参考它的官网文档。其中 md.render 就是把 markdown 字符串渲染生成 HTML。
不过我们注意到，组件文档使用了一些非标准的 markdown 语法，比如：
:::demo
:::
它实际上是一个 markdown 的自定义容器，借助于 markdown-it-container 插件，就可以解析这个自定义容器：
const mdContainer = require('markdown-it-container');
module.exports = md => {
md.use(mdContainer, 'demo', {
validate(params) {
return params.trim().match(/^demo\s*(.*)$/);
},
render(tokens, idx) {
const m = tokens[idx].info.trim().match(/^demo\s*(.*)$/);
if (tokens[idx].nesting === 1) {
const description = m && m.length > 1 ? m[1] : '';
const content = tokens[idx + 1].type === 'fence' ? tokens[idx + 1].content : '';
return `
${description ? `${md.render(description)}` : ''}
`
}
return '';
}
});
md.use(mdContainer, 'tip');
md.use(mdContainer, 'warning');
};
可以看到，对于 demo 这个自定义容器，它会解析 demo 后面紧接着的描述字符串以及 code fence，并生成新的 HTML 字符串。
此外，code fence 也定义了新的渲染策略：
// 覆盖默认的 fence 渲染策略
module.exports = md => {
const defaultRender = md.renderer.rules.fence;
md.renderer.rules.fence = (tokens, idx, options, env, self) => {
const token = tokens[idx];
// 判断该 fence 是否在 :::demo 内
const prevToken = tokens[idx - 1];
const isInDemoContainer = prevToken && prevToken.nesting === 1 && prevToken.info.trim().match(/^demo\s*(.*)$/);
if (token.info === 'html' && isInDemoContainer) {
return `${md.utils.escapeHtml(token.content)} }
return defaultRender(tokens, idx, options, env, self);
};
};
对于在 demo 容器内且带有 html 标记的 code fence，会做一层特殊处理。
对于我们前面的示例：
:::demo Alert 组件提供四种主题，由`type`属性指定，默认值为`info`。
```html
title="成功提示的文案"
type="success">
title="消息提示的文案"
type="info">
title="警告提示的文案"
type="warning">
title="错误提示的文案"
type="error">
```
:::
经过解析后，生成的 HTML 大致如下：
<demo-block>
<div><p>Alert 组件提供四种主题，由<code>typecode>属性指定，默认值为<code>infocode>。p>
div>
<template slot="highlight"><pre v-pre><code class="html"><template>
<el-alert
title="成功提示的文案"
type="success">
</el-alert>
<el-alert
title="消息提示的文案"
type="info">
</el-alert>
<el-alert
title="警告提示的文案"
type="warning">
</el-alert>
<el-alert
title="错误提示的文案"
type="error">
</el-alert>
</template>
code>pre>template>
demo-block>
demo 子组件的处理
目前我们了解到，每一个 demo 容器对应一个示例，它会解析生成对应的 HTML，最终会通过 demo-block 组件渲染，这个组件是预先定义好的 Vue 组件：
<template>
<div
class="demo-block"
:class="[blockClass, { 'hover': hovering }]"
@mouseenter="hovering = true"
@mouseleave="hovering = false">
<div class="source">
<slot name="source">slot>
div>
<div class="meta" ref="meta">
<div class="description" v-if="$slots.default">
<slot>slot>
div>
<div class="highlight">
<slot name="highlight">slot>
div>
div>
<div
class="demo-block-control"
ref="control"
:class="{ 'is-fixed': fixedControl }"
@click="isExpanded = !isExpanded">
<transition name="arrow-slide">
<i :class="[iconClass, { 'hovering': hovering }]">i>
transition>
<transition name="text-slide">
<span v-show="hovering">{{ controlText }}span>
transition>
<el-tooltip effect="dark" :content="langConfig['tooltip-text']" placement="right">
<transition name="text-slide">
<el-button
v-show="hovering || isExpanded"
size="small"
type="text"
class="control-button"
@click.stop="goCodepen">
{{ langConfig['button-text'] }}
el-button>
transition>
el-tooltip>
div>
div>
template>
demo-block 支持了多个插槽，其中默认插槽对应了组件的描述部分；highlight 插槽对应组件高亮的代码部分；source 插槽对应 demo 实现的部分。
因此，目前我们生成的 HTML 字符串还不能够直接被 demo-block 组件使用，需要进一步的处理：
module.exports = function(source) {
const content = md.render(source);
const startTag = '';
const endTagLen = endTag.length;
let componenetsString = '';
let id = 0; // demo 的 id
let output = []; // 输出的内容
let start = 0; // 字符串开始位置
let commentStart = content.indexOf(startTag);
let commentEnd = content.indexOf(endTag, commentStart + startTagLen);
while (commentStart !== -1 && commentEnd !== -1) {
output.push(content.slice(start, commentStart));
const commentContent = content.slice(commentStart + startTagLen, commentEnd);
const html = stripTemplate(commentContent);
const script = stripScript(commentContent);
let demoComponentContent = genInlineComponentText(html, script);
const demoComponentName = `element-demo${id}`;
output.push(`<${demoComponentName} />` );
componenetsString += `${JSON.stringify(demoComponentName)}: ${demoComponentContent},`;
// 重新计算下一次的位置
id++;
start = commentEnd + endTagLen;
commentStart = content.indexOf(startTag, start);
commentEnd = content.indexOf(endTag, commentStart + startTagLen);
}
// 处理 script
// ...
output.push(content.slice(start))
};
其中 output 表示要输出的模板内容，componenetsString 表示要输出的脚本内容。这段代码要做的事情就是填充 demo-block 组件内部的 source 插槽，并且插槽的内容是一个 demo 子组件。
由于前面生成的 HTML 中包含了 注释字符串，因此就可以找到注释字符串的位置，通过字符串截取的方式来获取注释内外的内容。
对于注释内的内容，会提取其中的模板部分和 JS 部分，然后构造出一个内联的组件字符串。
前面的示例经过处理，output 对应的内容如下：
[
`
Alert 组件提供四种主题，由type属性指定，默认值为info。
`
`
`<template>
<el-alert
title="成功提示的文案"
type="success">
</el-alert>
<el-alert
title="消息提示的文案"
type="info">
</el-alert>
<el-alert
title="警告提示的文案"
type="warning">
</el-alert>
<el-alert
title="错误提示的文案"
type="error">
</el-alert>
</template>
]
处理后的 demo-block 就变成一个标准的 Vue 组件的应用了。
componenetsString 对应的内容如下：
`"element-demo0": (function() {
var render = function() {
var _vm = this
var _h = _vm.$createElement
var _c = _vm._self._c || _h
return _c(
"div",
[
[
_c("el-alert", { attrs: { title: "成功提示的文案", type: "success" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "消息提示的文案", type: "info" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "警告提示的文案", type: "warning" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "错误提示的文案", type: "error" } })
]
],
2
)
}
var staticRenderFns = []
render._withStripped = true
const democomponentExport = {}
return {
render,
staticRenderFns,
...democomponentExport
}
})(),`
通过内联的方式定义了 element-demo0 子组件的实现。
示例只是处理了单个 demo 子组件，如果有多个 demo 容器，就可以通过循环查找注释字符串 element-demo:，处理所有的 demo-block。
构造完整的组件
module.exports = function(source) {
const content = md.render(source);
let componenetsString = '';
let output = [];
let start = 0;
// 循环处理 demo 子组件
// ...
let pageScript = '';
if (componenetsString) {
pageScript = ``;
} else if (content.indexOf('') + ''.length;
pageScript = content.slice(0, start);
}
output.push(content.slice(start));
return `
${output.join('')}
${pageScript}
`;
};
可以看到，output 负责组件的模板定义，pageScript 负责组件的脚本定义，最终会通过字符串拼接的方式，返回完整的组件定义。
对于最开始完整的示例而言，经过 md-loader 处理的结果如下：
<template>
<section class="content element-doc">
<h2 id="alert-jing-gao"><a class="header-anchor" href="#alert-jing-gao" aria-hidden="true">¶a> Alert 警告h2>
<p>用于页面中展示重要的提示信息。p>
<h3 id="ji-ben-yong-fa"><a class="header-anchor" href="#ji-ben-yong-fa" aria-hidden="true">¶a> 基本用法h3>
<p>页面中的非浮层元素，不会自动消失。p>
<demo-block>
<div><p>Alert 组件提供四种主题，由<code>typecode>属性指定，默认值为<code>infocode>。p>
div>
<template slot="source">
<element-demo0/>
template>
<template slot="highlight"><pre v-pre><code class="html"><template>
<el-alert
title="成功提示的文案"
type="success">
</el-alert>
<el-alert
title="消息提示的文案"
type="info">
</el-alert>
<el-alert
title="警告提示的文案"
type="warning">
</el-alert>
<el-alert
title="错误提示的文案"
type="error">
</el-alert>
</template>
code>pre>
template>
demo-block>
section>
template>
<script>
export default {
name: 'component-doc',
components: {
"element-demo0": (function() {
var render = function() {
var _vm = this
var _h = _vm.$createElement
var _c = _vm._self._c || _h
return _c(
"div",
[
[
_c("el-alert", { attrs: { title: "成功提示的文案", type: "success" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "消息提示的文案", type: "info" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "警告提示的文案", type: "warning" } }),
_vm._v(" "),
_c("el-alert", { attrs: { title: "错误提示的文案", type: "error" } })
]
],
2
)
}
var staticRenderFns = []
render._withStripped = true
const democomponentExport = {}
return {
render,
staticRenderFns,
...democomponentExport
}
})(),
}
}
script>
显然，经过 md-loader 处理后原来 markdown 语法的字符串变成了一个 Vue 组件定义的字符串，就可以交给 vue-loader 继续处理了。
文档的优化
ElementUI 文档的设计确实巧妙，由于我们研发的 ZoomUI 是 fork 自 ElementUI 的，很长一段时间，我们也沿用了 ElementUI 文档的编写方式。
但是随着我们自研的组件越来越多，组件使用的场景也越来越丰富，我们对于文档编写和维护的需求也越来越多。
我发现在现有模式下写文档有几个不爽的点：
1.在 .md 中写 Vue 组件不方便，没法格式化代码，IDE 的智能提示不够友好。
2.在 demo 中写 style 是无效的，需要在外部的 css 文件另外定义样式。
3.中英文文档需要分别写 demo，修改一处没法自动同步到另一处。
我认为理想中编写一个组件的文档的方式是这样的：
## Select 选择器
当选项过多时，使用下拉菜单展示并选择内容。
### 基础用法
适用广泛的基础单选。
:::demo `v-model` 的值为当前被选中的 `zm-option` 的 `value` 属性值。
```html
```
:::
### 有禁用选项
:::demo 在 `zm-option` 中，设定 `disabled` 值为 `true`，即可禁用该选项。
```html
```
:::
所有组件的 demo 拆成一个个 Vue 组件，然后在 markdown 文档中引入这些同名的组件。通过这种方式，前面提到的三个痛点就解决了。
那么，想达到这种效果，我们需要对 md-loader 做哪些修改呢？
来看一下修改后的 md-loader 的实现：
const md = require('./config');
module.exports = function(source) {
const content = md.render(source, {
resourcePath: this.resourcePath
});
const startTag = '';
const endTagLen = endTag.length;
const tagReg = /\s*<([\w-_]+)\s*\/>\s*/;
let componenetsString = '';
let output = []; // 输出的内容
let start = 0; // 字符串开始位置
let commentStart = content.indexOf(startTag);
let commentEnd = content.indexOf(endTag, commentStart + startTagLen);
while (commentStart !== -1 && commentEnd !== -1) {
output.push(content.slice(start, commentStart));
const commentContent = content.slice(commentStart + startTagLen, commentEnd);
const matches = commentContent.match(tagReg);
if (matches) {
const demoComponentName = matches[1];
output.push(`<${demoComponentName} />` );
const imports = `()=>import('../demos/${demoComponentName}.vue')`;
componenetsString += `${JSON.stringify(demoComponentName)}: ${imports},`;
}
start = commentEnd + endTagLen;
commentStart = content.indexOf(startTag, start);
commentEnd = content.indexOf(endTag, commentStart + startTagLen);
}
let pageScript = '';
if (componenetsString) {
pageScript = ``;
} else if (content.indexOf('') + ''.length;
pageScript = content.slice(0, start);
}
output.push(content.slice(start));
return `
${output.join('')}
${pageScript}
`;
};
思路很简单，解析出每个 demo 容器中的组件名称，通过动态 import 的方式加载组件，然后在 source 插槽中直接用这个组件。
这样就把组件的 markdown 文档和 demo 直接关联起来。但这样还不够，我们还需要解决组件 demo 下面的代码展示问题，需要对 code fence 渲染策略做一定的修改：
const path = require('path');
const fs = require('fs');
const tagReg = /\s*<([\w-_]+)\s*\/>\s*/;
// 覆盖默认的 fence 渲染策略
module.exports = md => {
const defaultRender = md.renderer.rules.fence;
md.renderer.rules.fence = (tokens, idx, options, env, self) => {
const token = tokens[idx];
// 判断该 fence 是否在 :::demo 内
const prevToken = tokens[idx - 1];
const isInDemoContainer = prevToken && prevToken.nesting === 1 && prevToken.info.trim().match(/^demo\s*(.*)$/);
if (token.info === 'html' && isInDemoContainer) {
const matches = token.content.match(tagReg);
if (matches) {
const componentName = matches[1];
const componentPath = path.resolve(env.resourcePath, `../../demos/${componentName}.vue`);
const content = fs.readFileSync(componentPath, 'utf-8');
return `${md.utils.escapeHtml(content)} }
return '';
}
return defaultRender(tokens, idx, options, env, self);
};
};
由于组件 demo 的代码已经不在 markdown 文档中维护了，因此只能从组件文件中读取了。
但是我们如何知道应该从哪个路径读取对应的 demo 组件呢？
在 webpack loader 中，我们可以通过 this.resourcePath 获取到当前处理文件的路径，那么在执行 markdown 渲染的过程中就可以把路径当做环境变量传入：
const content = md.render(source, {
resourcePath: this.resourcePath
})
这样在 markdown 处理器的内部我们就可以通过 env.resourcePath 拿到处理的 markdown 文件路径，从而通过相对路径计算出要读取组件的路径，然后读取它们的内容：
const componentPath = path.resolve(env.resourcePath, `../../demos/${componentName}.vue`);
const content = fs.readFileSync(componentPath, 'utf-8');
有了组件文档的重构方案，接下来的工作就是依次重构组件的文档。当然在这个阶段，新老文档编写的方式都需要支持。
因此需要对 webpack 的配置做一些修改：
{
test: /examples(\/|\\)docs(\/|\\).*\.md$/,
use: [
{
loader: 'vue-loader',
options: {
compilerOptions: {
preserveWhitespace: false
}
}
},
{
loader: path.resolve(__dirname, './md-loader/index.js')
}
]
}, {
test: /(examples(\/|\\)docs-next(\/|\\).*|changelog\.[\w-_]+)\.md$/i,
use: [
{
loader: 'vue-loader',
options: {
compilerOptions: {
preserveWhitespace: false
}
}
},
{
loader: path.resolve(__dirname, './md-loader-next/index.js')
}
]
}
对于重构的文档，使用新的 markdown loader。当然加载组件视图的逻辑也需要做一定的修改，对于重构的文档，指向新的文档地址。
总结
ElementUI 通过 markdown 编写组件文档的思路还是非常棒的，主要利用了自定义 md-loader 对 markdown 文件内容做了一层处理，解析成 Vue 组件字符串，再交给 vue-loader 处理。
在写这篇文章之前，我就在粉丝群里分享了重构文档的方案。有同学告诉我，Element-plus 已经用 vitepress 重写，看了一下文档的组织方式，和我重构的方式非常类似，这就是传说中的英雄所见略同吗？
我在之前的文章中强调过，要善于发现工作中的痛点，并通过技术的方式解决，这是优秀的工程师重要的能力之一，希望这篇文章能够带给你这方面的一些思考。
参考资料
[1] markdown-it-chain: https://github.com/ulivz/markdown-it-chain
[2] markdown-it: https://markdown-it.github.io/markdown-it/