Vuepress自动生成技术文档

Vuepress安装与使用

  • 如果你的现有项目依赖了webpack 3.x,推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下,npm 会生成错误的依赖树。
  • 请确保你的 Node.js版本 >= 8。

安装

将 VuePress 作为一个本地依赖安装

1
yarn add vuepress -D

新建一个 docs 文件夹

mkdir docs

新建一个 markdown 文件

echo “# Hello VuePress!” > docs/README.md

开始写作

npx vuepress dev docs

接着,在 package.json 里加一些脚本:

1
2
3
4
5
6
7
{
 "scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
  }
}

然后就可以开始写作了:

目录结构

目录结构如下:

1
2
3
4
5
6
7
8
9
10
11
  docs

└─ .vuepress
   ├─ config.js            // 主题配置(navbar,sidebar等)
   └─ public               // 公用资源
   ├─ logo.png
   └─ components
   ├─ README.md
   ├─ Button.md
   ├─ Checkbox.md
├─ README.md                // 首页配置

.vuepress/config.js中:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
module.exports = {
  title: 'UI-NuClear-Mobile',
  description: 'Welcome To UI-NuClear-Mobile',
  themeConfig: {
// 配置顶部导航栏
nav: [
  { text: '首页', link: '/' },
  { text: '组件', link: '../components/' },
  { text: 'External', link: 'https://google.com' }
],
// 配置sidebar
sidebar: {
  '/components/': [
    '',
    'Button', 
    'Checkbox'
  ]
}
  },
}

docs/README.md中做首页的配置:

01

Node自动遍历复制生成技术文档

需求

  • 遍历Vue/components/src/components下的所有.md文件,将其复制到Vue/docs/components路径下。
  • 在docs/.vuepress/config.js中,将Vue/docs/components路径下的所有文件作为sidebar的配置选项

实现思路

copy-docs.js

  • fs.readdir读取sourcePath下的所有文件名,拿到文件名数组paths
  • 遍历并判断文件类型拿到所有.md类型的文件名_p
  • 利用fs.createReadStreamfs.createWriteStream分别在源路径和目标路径下读写文件,.pipe方法定位连接输出。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// copy-docs.js

var fs = require('fs')
var path = require('path')
var sourcePath = path.resolve('./src/components/')
var targetPath = path.resolve('./docs/components')

function syncFiles (sourcePath, targetPath, fileName = '') {
  if (!fs.existsSync(targetPath)) {
	fs.mkdirSync(targetPath)
 }
	fs.readdir(sourcePath, function (err, paths) {
	  if (err) {
    console.log('读取文件夹出错')
  }
  paths.map(_p => {
  	if (!/\./.test(_p)) { // 如果是文件夹
    	return syncFiles(path.join(sourcePath, _p), targetPath, _p)
  	}
  	if (!/\.md/.test(_p)) {
    	return
  	}
  	var readstream = fs.createReadStream(path.join(sourcePath, _p))
  	var writestream = fs.createWriteStream(path.join(targetPath, fileName + '.md'))
  	readstream.pipe(writestream)
		})
  	})
}
syncFiles(sourcePath, targetPath)

docs/.vuepress/config.js

  • 遍历目标路径下的所有文档,配置进sidebar中。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
var fs = require('fs');
var path = require('path');
var filePath = path.resolve('./docs/components/');
var filelist = [
  '',
];
function getfilelist(dir,callback) {
  fs.readdirSync(dir).forEach(function (file) {  
  callback(file);
    });
}
getfilelist(filePath,function (file) {
  filelist.push(file);
});

// 去掉components文件夹下的README.md
function removereadme(arr, val) {
  for(var i=0; iarr.length; i++) {
  if(arr[i] == val) {
  arr.splice(i, 1);
  break;
	}
  }
}
removereadme(filelist, 'README.md');
module.exports = {
  title: 'UI-NuClear-Mobile',
  description: '一套基于Vue.js的移动端UI组件库',
  themeConfig: {
	nav: [{
    text: '首页',
    link: '/'
  	},
  {
    text: '组件',
    link: '../components/'
  },
  {
    text: 'External',
    link: 'https://google.com'
  }
],
sidebar: {
  '/components/': filelist
	}
 },
};


这里注意我们需要在整个项目的package.json中添加两条命令:node build/copy-docs.jsvuepress docs dev

npm 脚本里面需要执行多个任务,那么需要明确它们的执行顺序。

  • 如果是并行执行(即同时的平行执行),可以使用&符号。
  • 如果是继发执行(即只有前一个任务成功,才执行下一个任务),可以使用&&符号。

所以package.json中:

1
2
3
4
"scripts": {
  "docs:dev": "node build/copy-docs.js && vuepress dev docs",
}