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，由自己处理这些代码，最终返回想要的内容。

::: demo
​`html   ​`
:::

上面就是插件的用法，demo 由自己定义，初始注入的代码如下：

parser.use(require("markdown-it-container"), "demo", {
    validate(params) {
        return params.trim().match(/^demo\s*(.*)$/);
    },
    // 把demo代码放到div.kv-demo里面
    render(tokens, idx) {
        const m = tokens[idx].info.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 `
${content}
`;
        }
        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*(.*)$/);
    if (token.info === "html" && isInDemoContainer) {
        return ``;
    }

    return `
${defaultRender(
        tokens,
        idx,
        options,
        env,
        self
    )}
`;
};

需要注意highlight不会把代码中的{{tab}} 这种插值转译，如果直接给vue渲染会报错，所以需要添加一个v-pre的指令，需要包装原始的rules.fence：

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(/(

做完以上部分之后，md 的内容会被渲染成代码片断，内部包含普通的 html 标签和 vue 组件标签，大概如下：

一些文字

    

        

            

                
                    
                    {{'kv-' + name}}
                
            
        
        

        
    
    

组装成 vue 模板

这个代码和 vue 的组件的代码不一致，是无法解析的，需要修正一下。

另外,一篇文档中会有多个 demo 即多个 export default，解决方案就是把各个 demo 提取成组件，注册当前文档这个 vue 组件中，把 demo 的部分替换组件的名字。

第一部分：组装当前文档为 vue 组件 ,同时挂载提取出来 demo 组件https://github.com/blank-x/kv/blob/master/build/markdown-loader/index.js#L15

var renderMd = function (html,fileName) {
	......
}

第二部分：提取其中的 demo 为组件，https://github.com/blank-x/kv/blob/master/build/markdown-loader/index.js#L57)

var renderVueTemplate = function (content) {
	......
}

结果类似于如下：

组件 kv-demo0 和 kv-demo1 在 components 中定义；

在 demo 内部的 scss 会被提出来，放到了外层 vue 组件中，如果需要修改样式，可以参考如下写法：

.demo-tag .kv-demo1{
	//
}
.demo-tag .kv-demo0{
	//
}
tag  // md的名字
demo0  // 页面内第几个demo

未解决的问题

每一个 demo 中 script 标签和 export 之间的代码被丢弃。如果需要引入其他文件，可以在 data 中通过 require 引入；

最后

本代码仅为练手使用，未在实际开发中使用，如有不正之处望指正。
地址https://github.com/blank-x/kv