element js 包含字符_谈谈 Element 文档中的 Markdown 解析

题图来自 Plush Design Studio

Element 的文档站与普通的 web 项目开发并无二致，只不过我们把 Markdown 当成 Vue 组件来使用。在文档中，我们还编写了许多示例去描述组件的用法。在编写示例代码时，我们还有这两个需求：

1. 示例代码格与单文件组件保持一致
2. 示例代码像组件一样在页面中渲染

原生的 Markdown 不具备上述功能。因此，势必要对 Markdown 进行特殊的订制，拓展其能力。订制过的 Markdown 像下面这样。

## 禁用状态

:::demo 通过 `disabled` 属性指定是否禁用 input 组件
```html
<el-input
  placeholder="请输入内容"
  v-model="input"
  :disabled="true">
</el-input>

<script>
export default {
  data() {
    return {
      input: ''
    }
  }
}
</script>
```
:::

看到这里，你可能会好奇 Element 文档站是如何实现这些功能的，本文将带你一探究竟。

从 Webpack 配置入手

Webpack 通过 loader 来处理特定类型的文件。要想理解其原理，可以先从项目的 Webpack 配置（webpack.demo.js）入手。

{
  test: '.md$',
  use: [
    {
      loader: 'vue-loader'
    },
    {
      loader: path.resolve(__dirname, './md-loader/index.js')
    }
  ]
}

从配置文件中可以看出，Markdown 先经由 md-loader 处理，然后再交由 vue-loader 处理。经过这两个 loader 的处理，Markdown 就与 Vue 组件一样了。

在分析 md-loader 原理之前，先对 Element 文档格式做一下简单的介绍。

约定的文档格式

Element 文档与普通的 Markdown 略有差异，约定了文档的格式。::: demo 中写演示的例子，::: demo 中 ```(fence)中编写代码。::: 属于Markdown 中的拓展语法，通过它来自定义容器。

最终达到的效果如下图所示：

预期效果

分析

我们的需求很多明确：实现 md-loader，把 Markdown 转化成 Vue 组件。一个典型的单文件组件包括三块：template，script 与 style。对于 Element 的文档来说，demo 中 style 是不提取的。那么接下的重点就是如何拼凑出 template 与 script 的内容。

使用 markdown-it 可以很方便地把普通的 Markdown 文本转换成 HTML。但要如何处理 demo 自定义容器与其包含的代码片段呢？

• 对于 demo 自定义容器，无非是自定义它的渲染策略，比如把该容器转化一个 demo-block 组件。
• 对于容器包含的代码片段，要多做一些处理。它除了被转换成 HTML 片段，还要提取出来作为一个组件去渲染。

markdown-it 处理后的内容构成 template，容器内的代码片段被转化成组件，构成 script。整个转换过程如下图所示：

下面开始讲解一下具体的实现。

Markdown 编译

使用 markdown-it-container 来转换自定义容器。

module.exports = md => {
  md.use(require('markdown-it-container'), 'demo', {
    // ....
    render(tokens, idx) {
      if (tokens[idx].nesting === 1) {
        return `<demo-block><div>${md.render(description)}</div>`;
      }
      return '</demo-block>';
    }
  });
};

自定义容器 demo 就被转成了 demo-block 组件。

针对代码块（fence），markdown-it 有默认的渲染逻辑。当代码块在 demo 容器内要做一下特殊处理。

const defaultRender = md.renderer.rules.fence;
// 覆盖默认渲染规则
md.renderer.rules.fence = (tokens, idx, options, env, self) => {
  // ...
  if (tokens[idx].info === 'html' && isInDemoContainer) {
    return `<template slot="highlight">
        <pre v-pre>
          <code class="html">...</code>
        </pre>
      </template>`;
  }
  return defaultRender(tokens, idx, options, env, self);
};

v-pre 是 Vue 自带的指令，用来显示原始 Mustache 标签。考虑到代码片段会包含 Mustache 标签，使用该指令来跳过对 code 的编译。

设置占位符

现在，我们已经完成了从 Markdown 到 HTML 的转换。还缺少点功能，demo 中的代码片段没有渲染。

要渲染代码片段，关注以下两点：

1. 如何渲染
2. 组件的位置

在 Vue 中，可以使用一个普通的 JavaScript 对象来定义组件。把代码片段转化成一个对象，之后在父元素中注册一下即可，问题 1 就解决了。

再看问题 2。代码区域即是组件要显示的位置。在 markdown-it 编译代码片段前，我们还需要把代码复制一份（上文中提到了代码既要显示还要渲染），创建一个占位符，用来放置在下一步才注册的组件。

md.use(require('markdown-it-container'), 'demo', {
  render(tokens, idx) {
    if (tokens[idx].nesting === 1) {
      return `<demo-block>
      ...
      __START__${code}__END__
      `;
    }
    return '</demo-block>';
  }
});

__START__${code}__END__ 就是占位符。之后要把占位符的内容进行编译并替换为组件。

这里的做法类似于宏替换。

代码片段转换成组件

代码片段的 script 原本就是导出对象。把 template 转换成 render 函数，再将 script 与 render 函数合并，这样就把代码片段转换成组件。

vue-template-compiler 正好是我们所需要的。先调用 Vue.compile 方法，查看编译后的效果。

//const res = Vue.compile('<div>demo</div>')

// res.render
function anonymous() {
  with(this) {
    return _c('div',[_v("demo")])
  }
}

// res.staticRenderFns
[]

render 函数中包含了 with 语句。with 语句是不建议使用，知乎上有关于这个问题的讨论。在该问题的回答中，Vue 作者尤雨溪提到了 vue-loader 是把 with 给去掉了。先看一下 vue-loader 是如何编译 template 的。核心逻辑如下：

const { compileTemplate } = require('@vue/component-compiler-utils');
const compiler = require('vue-template-compiler');

const finalOptions = {
  source: `<div>${template}</div>`,
  compiler
};
const compiled = compileTemplate(finalOptions);

compiled 包含了编译之后的结果，compiled.code 即是我们想要的内容。

// compiled.code
var render = function() {
  var _vm = this
  var _h = _vm.$createElement
  var _c = _vm._self._c || _h
  return _vm._m(0)
}
var staticRenderFns = [
  // ....
]
render._withStripped = true

使用 @vue/component-compiler-utils 与 vue-template-compiler 相配合就完成对 template 的编译。接下来把 render，staticRenderFns 与 script 合并成一个对象。使用自执行函数将合成后的结果返回，这样就获得了组件内容。

script = script.replace(/exports+default/, 'const demoComponentExport =');

const demoComponentContent = `(function() {
  ${compiled.code}
  ${script}
  return {
    render,
    staticRenderFns,
    ...demoComponentExport
  }
})()`

编译组件完成后，就剩批量注册组件以及占位符替换了。最后这两步本质上是字符串拼接，不再赘述。

自定义 loader 的核心代码大致如下：

module.exports = function(source) {
  const content = md.render(source);

  let componentsString = ''; // 局部注册组件的内容
  let output = []; // 输出的内容

  // 对 content 进行处理，拼接处理 template 与 script 内容

  return `
    <template>
      <section class="content element-doc">
        ${output.join('')}
      </section>
    </template>
    <script>
      export default {
        name: 'component-doc',
        components: {
          ${componentsString}
        }
      }
    </script>
  `;
};

核心的转换逻辑到这里讲解完毕，完整的代码点击这里。

总结

本文介绍了 Element 文档站中 md-loader 的实现。由于 Markdown 支持自定义容器，因此我们不仅仅可以在文档中写 Vue 组件，当然更可以写 React，比如 docz。大家可以结合自己的业务场景发掘出更多的用法，希望本文能给你带来一些的启发。

参考资料

• markdown-it
• vuepress
• vue-loader