基于markdown快速生成易维护的Vue项目文档

[ChenJiaH]

首发于微信公众号《前端成长记》，写于 2018.02.23

背景

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。通常我们都用来写文档。

解决过程

** 最开始的思路是，文档只通过.md进行维护，找到一个md解析器，将md解析成html对应填入到.vue文件中，于是便有了下面的操作： **

1. 通过npm中找到 marked 这个node包，首先进行安装

npm install marked --save

2. 在.vue文件中引入md文件并解析成html输出到页面上

var marked = require('marked');
var md = require('./test.md')
export default {
  data () {
    return {
      mdHtml: "",
    }
  },
  mounted () {
    this.mdHtml = marked(md);
  }
}

这时候发现，因为解析过程是在marked中做的，如果md中想使用自定义组件，比如jrv-alert，也会被原封不动的转成。这并不是我们期望的效果，所以，** 这种方式不可行 **。

** 接下来，考虑的就是在编译过程中应当使用vue预发先做前置的解析。所以便有了下面的代码： **

1. 通过npm中找到 markdown-loader 这个node包，首先进行安装。

npm install markdown-loader

2. 在webpack中配置loader

{    module: {
        rules: [{
                test: /\.md$/,
                use: [
                    {
                        loader: "html-loader"
                    },
                    {
                        loader: "markdown-loader",
                        options: {
                            /* your options here */
                        }
                    }
                ]
            }]
    }
}

在路由配置中，通过不同的.md文件去渲染对应的路径，验证发现，诸如jrv-alert这种自定义组件的html也被正确编译，没有问题。但是，我这边的需求仍然有变动，还有一些参数需要动态配置传入，这时候光使用loader已经无法满足要求了。** 这种方式也不可行 **。

** 于是，思路变成了，如何能够自定义处理编译过程中的md文件。接下来就是实践的步骤： **

1. 通过npm中找到 vue-markdown-loader 这个node包，首先进行安装。

npm install vue-markdown-loader

2. 在webpack中配置loader

{  test: /\.md$/,
  loader: 'vue-markdown-loader',
  options: options
}

** 这时候，我们可以拿到整个编译的过程了，在options里可以做一些自定义配置。但是，我们想让md变得更易于维护，想编写一个自定义的md语法，这时候仍然需要以下处理。 **

1. 通过npm中找到 markdown-it-container 这个node包，首先进行安装。

npm install markdown-it-container --save

2. 在webpack中配置loader的options

const MarkdownItContainer = require('markdown-it-container')
const striptags = require('./strip-tags')
const vueMarkdown = {
   preprocess: (MarkdownIt, source) => {
      MarkdownIt.renderer.rules.table_open = function () {
         return '<table class="table">'
      }
      MarkdownIt.renderer.rules.fence = utils.wrapCustomClass(MarkdownIt.renderer.rules.fence)
      return source
   },
   use: [
      [MarkdownItContainer, 'demo', {
         validate: params => params.trim().match(/^demo\s*(.*)$/),
         render: (tokens, idx) => {
            if (tokens[idx].nesting === 1) {
               const html = utils.convertHtml(striptags(tokens[idx + 1].content, 'script'));
 
               const m = tokens[idx].info.trim().match(/^demo\s+(.*)$/);
               if(m && m[1]) { // demo 有配置info
                  const infoArr = m[1].split("|");
                  let str = "";
                  for(let i = 1 ; i < infoArr.length; i++) {
                     str += `<p>${infoArr[i].trim()}</p>`
                  }
                  return `<jrv-demo>`
                     + `<div slot="demo">${html}</div>`
                     + `<div slot="info"><h4>${infoArr[0].trim()}</h4>${str}</div>`
                     + `<div slot="source-code">`
               } else {
                  return `<jrv-demo>`
                     + `<div slot="demo">${html}</div>`
                     + `<div slot="source-code">`
               }
            } else {
               // closing tag
               return '</div></jrv-demo>'
            }
         }
      }]
   ]
}
{  test: /\.md$/,
  loader: 'vue-markdown-loader',
  options: options
}

在上述代码中，我们定义了一个名叫 demo的自定义语法，并且制定了使用 jrv-demo 这个组件去生成该预发对应的html。完整配置代码

** 到这一步为止，我们已经能够实现，使用纯md维护对应的vue文档了。接下来要实现的就是自动化的过程。 **

后续

自动化的过程的思路大概如下：通过抓取组件列表，获取组件的slot项和data项，自动生成对应md中的slot部分和data部分。或者说半自动化就可以手动维护一个json表去对应这些。设置scripts自动生成更新对应md文件。

实例参见：art-vue文档

（完）

---

本文为原创文章，可能会更新知识点及修正错误，因此转载请保留原出处，方便溯源，避免陈旧错误知识的误导，同时有更好的阅读体验
如果能给您带去些许帮助，欢迎 ⭐️star 或 ✏️ fork
(转载请注明出处：https://chenjiahao.xyz)