Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
ChenJiaH opened this issue Aug 2, 2019 · 0 comments
Open

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

ChenJiaH opened this issue Aug 2, 2019 · 0 comments
Labels

Comments

@ChenJiaH
Copy link
Owner

ChenJiaH commented Aug 2, 2019

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

背景

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

解决过程

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

  1. 通过npm中找到 marked 这个node包,首先进行安装
npm install marked --save
  1. 在.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
  1. 在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
  1. 在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
  1. 在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)

@ChenJiaH ChenJiaH added the vue.js label Aug 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant