vue组件库用markdown生成文档

前言： 开发 vue 组件库需要提供组件的使用文档，最好是有渲染到浏览器的 demo 实例，既能操作又能查看源代码。markdown 作为常用的文档编写载体，如果能在里面直接写 vue 组件，同时编写使用说明就再好不过。流行的组件库 element-ui 的文档就是用 markdown 写出来的，看了看其处理 md 的程序后，自己也决定写一个类似的处理程序，研究一下其中的细节。

技术点 1.markdown-it

处理 markdown 最常用的工具是 markdown-it，它能把我们写的 markdown 文件转换为 html。类似于 babel，markdown 也有自己的插件系统，通过设置或者编写自定义插件改变渲染的路径。

2.webpack-loader

处理 md 文件可以使用自定义 webpack-loader 来处理，先把 md 内容转为合适 html，然后再给 vue-loader 处理。

3.cheerio

使用 markdown-it 把 md 内容转为 html 之后，需要操作 html，cherrio 以类似 jquery 的方式操作 html，简单方便。

4.hljs

代码需要高亮渲染，hijs 的功能就是将代码处理成 html，通过样式使其高亮显示出来。

步骤 1.配置 webpack 解析 md { test: /.md$/, use:[ {loader: 'vue-loader'}, { loader: path.resolve(__dirname,'./markdown-loader/index.js') } ] }, 2.markdown-loader 的入口 module.exports = function(source) { this.cacheable && this.cacheable(); const { resourcePath = "" } = this; const fileName = path.basename(resourcePath, ".md"); // @符号在markdown中是特殊符号 source = source.replace(/@/g, "at"); var content = parser.render(source).replace(/at/g, "@"); var result = renderMd(content, fileName); return result; }; 3.添加插件 markdown-it-container markdown-it-container 是一个插件，使用这个插件之后就可以在 markdown 中添加自己的标识，然后就能自定义处理标识里面的内容。在这里可以在把代码块放到标识内部，主要是防止 markdown-it 把 vue 组件转成 html，由自己处理这些代码，最终返回想要的内容。

::: demohtml <i class="kv-icon-close fs-24"></i> <i class="kv-icon-link fs-24"></i>::: 上面就是插件的用法，demo 由自己定义，初始注入的代码如下：

parser.use(require("markdown-it-container"), "demo", { validate(params) { return params.trim().match(/^demo\s*(.*)/); if (tokens[idx].nesting === 1) { const content = tokens[idx + 1].type === "fence" ? tokens[idx + 1].content : ""; // 先把demo中的代码放到demo-block的之中，然后程序继续render fence，按照上面的fence规则渲染出代码部分，作为隐藏的查看代码。 return <demo-block><div class="kv-demo">${content}</div>; } return ""; }, }); render 方法仿照的是 npm 包里的例子。其中的 tokens 是 AST 节点，可以从这个网址看到 markdown-it 解析的 AST，对照着做判断。

根据自己的理解，因为 html 是有起始标签和结束标签，markdown-it 的 render 也是成对的，也就是在标记的起始和结束都会调用 render 方法，所以在 demo 起始的时候返回了一个起始 （demo-block是个全局定义的 vue 组件），这里的content后来变成了vue的组件。

继续处理 demo 标识内部``` 代码标识，代码标识在 markdown-it 中有自己的 rules (rules.fence)来处理，结果就是高亮显示。我们的目标不仅仅如此，还需要让这部分代码有一个显示隐藏的效果，所以 需要加一个vue的slot标识。

// 先保存下来const defaultRender = parser.renderer.rules.fence; parser.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*(.*){defaultRender(tokens, idx, options, env, self)}; } return

const ensureVPre = function (markdown) { if (markdown && markdown.renderer && markdown.renderer.rules) { const rules = ['code_inline', 'code_block', 'fence'] const rendererRules = markdown.renderer.rules rules.forEach(function (rule) { if (typeof rendererRules[rule] === 'function') { const saved = rendererRules[rule] rendererRules[rule] = function () { return saved.apply(this, arguments).replace(/(<pre|<code)/g, '$1 v-pre') } } }) } } ensureVPre(parser) 做完以上部分之后，md 的内容会被渲染成代码片断，内部包含普通的 html 标签和 vue 组件标签，大概如下：

    <style lang="scss">
        .demo-icon {
          	.....
           }        </style>
</div>
<template slot="highlight">
    ......    </template></demo-block>