前端积累

# 如何搭建本文档

VuePress 是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目，VuePress 界面十分简洁，并且非常容易上手，一个小时就可以将项目架构搭好。现在已经有很多这种类型的文档，如果你有写技术文档/技术博客的需求，VuePress 绝对可以成为你的备选项之一。

# VuePress 特性：

  • 为技术文档而优化的 内置 Markdown 拓展
  • 在 Markdown 文件中使用 Vue 组件的能力
  • Vue 驱动的自定义主题系统
  • 自动生成 Service Worker
  • Google Analytics 集成
  • 基于 Git 的 “最后更新时间”
  • 多语言支持
  • 默认主题包含：

建议先看一下官方文档

# 效果：

可能你会搭建出一个类似这样的文档：

# 搭建：

# 全局安装 VuePress

    yarn global add vuepress # 或者：npm install -g vuepress
1

# 新建文件夹

可以手动右键新建，也可以使用下面的命令新建文件夹：

    mkdir project
1

# 项目初始化

进入到project文件夹中，使用命令行初始化项目:

    yarn init -y # 或者 npm init -y
1

将会创建一个package.json文件，长这样子：

    {
      "name": "project",
      "version": "1.0.0",
      "description": "",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "keywords": [],
      "author": "",
      "license": "ISC"
    }
1
2
3
4
5
6
7
8
9
10
11
12

# 在 project 的根目录下新建 docs 文件夹：

这个文档将作为项目文档的根目录来使用：

    mkdir docs
1

# 在 docs 文件夹下创建.vuepress文件夹：

mkdir.vuepress
1

所有 VuePress 相关的文件都将会被放在这里

# 在.vuepress文件夹下面创建config.js:

    touch config.js
1

config.js 是 VuePress 必要的配置文件，它导出一个 javascript 对象。

你可以先加入如下配置：

module.exports = {
	title: 'Hello VuePress',
	description: 'Just playing around'
}
1
2
3
4

# 在.vuepress文件夹下面创建 public 文件夹:

    mkdir public
1

这个文件夹是用来放置静态资源的，打包出来之后会放在.vuepress/dist/的根目录。

# 首页(像 VuePress 文档主页一样)

在 docs 文件夹下面创建一个README.md：

默认的主题提供了一个首页，像下面一样设置home:true即可，可以把下面的设置放入README.md中，待会儿你将会看到跟VuePress一样的主页。

--- home: true heroImage: /logo.jpg actionText: 快速上手 → actionLink:
/zh/guide/ features: - title: 简洁至上 details: 以 Markdown
为中心的项目结构，以最少的配置帮助你专注于写作。 - title: Vue驱动 details: 享受
Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue
来开发自定义主题。 - title: 高性能 details: VuePress 为每个页面预渲染生成静态的
HTML，同时在页面被加载的时候，将作为 SPA 运行。 footer: MIT Licensed | Copyright
© 2018-present Evan You ---
1
2
3
4
5
6
7

ps：你需要放一张图片到 public 文件夹中。

# 我们的项目结构已经搭好了：

    project
    ├─── docs
    │   ├── README.md
    │   └── .vuepress
    │       ├── public
    │       └── config.js
    └── package.json
1
2
3
4
5
6
7

# 在 package.json 里添加两个启动命令:

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

# 启动你的 VuePress：

默认是localhost:8080端口。

    yarn docs:dev # 或者：npm run docs:dev
1

# 构建：

build 生成静态的 HTML 文件,默认会在 .vuepress/dist 文件夹下

    yarn docs:build # 或者：npm run docs:build
1

# 基本配置：

最标准的当然是官方文档,可以自己的需求来配置config.js。

可以参考一下我的config.js的配置：

module.exports = {
	title: '网站标题',
	description: '网站描述',
	// 注入到当前页面的 HTML <head> 中的标签
	head: [
		['link', { rel: 'icon', href: '/favicon.ico' }] // 增加一个自定义的 favicon(网页标签的图标)
	],
	base: '/web_accumulate/', // 这是部署到github相关的配置 下面会讲
	markdown: {
		lineNumbers: true // 代码块显示行号
	},
	themeConfig: {
		sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题，显示在侧边栏上。
		lastUpdated: 'Last Updated' // 文档更新时间：每个文件git最后提交的时间
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 导航栏配置：

    module.exports = {
      themeConfig: {
        [
			{
				text: 'Vue系列',
				items: [
					{ text: 'Vue开发规范', link: '/standard/' }, // 内部链接 以docs为根目录
					{ text: 'VsCode EsLint自动格式化', link: '/eslint_auto_format/' },
					{ text: 'Vue+Axios请求封装', link: '/axios/' },
					{ text: '自定义代码模板', link: '/code_template/' },
					{ text: '前端积累', link: '/accumulate/' },
					{ text: '前端算法', link: '/algorithm/' },
					{ text: '代码块', link: '/codeBlack/' }
				]
			},
			{
				text: '开源库',
				items: [
					{
						text: '普元高低开组件库',
						link: 'https://github.com/Boom-BO/primeton-proc-components'
					},
					{
						text: '普元工具函数库（基于lodash.js扩展的工具函数库，内网可访问）',
						link: 'https://github.com/Boom-BO/primeton-proc-components'
					}
				]
			},
			// 下拉列表
			{
				text: 'GitHub',
				items: [{ text: 'GitHub地址', link: 'https://github.com/Boom-BO' }]
			}
		]
      }
    }
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

# 侧边栏配置：

侧边栏的配置相对麻烦点，我里面都做了详细的注释，仔细看，自己鼓捣鼓捣 就知道怎么搞了。

module.exports = {
	themeConfig: {
		sidebar: {
			// docs文件夹下面的accumulate文件夹 文档中md文件 书写的位置(命名随意)
			'/accumulate/': [
				'/accumulate/', // accumulate文件夹的README.md 不是下拉框形式
				{
					title: '侧边栏下拉框的标题1',
					children: [
						'/accumulate/JS/test' // 以docs为根目录来查找文件
						// 上面地址查找的是：docs>accumulate>JS>test.md 文件
						// 自动加.md 每个子选项的标题 是该md文件中的第一个h1/h2/h3标题
					]
				}
			],
			// docs文件夹下面的algorithm文件夹 这是第二组侧边栏 跟第一组侧边栏没关系
			'/algorithm/': [
				'/algorithm/',
				{
					title: '第二组侧边栏下拉框的标题1',
					children: ['/algorithm/simple/test']
				}
			]
		}
	}
}
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

# 其他：

# 代码块编译错误：

像下面这段代码会导致编译错误，VuePress 会去找里面的变量，把它编译成 text：

    {{}} 啦 {{}}
1

所以我们的代码块要以这种形式书写：

//```js
{{}} 啦 {{}} // 注释需要打开 这样vuepress会把这里面包裹的当成代码块而不是js
//```
1
2
3

并且这样也会让我们的代码高亮显示，阅读体验更好：

更改标题：

    ::: tip 替换tip的标题
    这里是内容。
    :::
1
2
3

其实文档里有，我这里只是提一下。

# 支持 Emoji

文档中只提了支持 Emoji,我在 GitHub 上找到了 Emoji 的列表，分享一下。

# 一个命令行发布到 github 上：

# 在 docs/.vuepress/config.js 中设置正确的 base:

如果你打算发布到 https://<USERNAME>.github.io/，则可以省略这一步，因为 base 默认即是 "/"。

如果你打算发布到 https://<USERNAME>.github.io/<REPO>/（也就是说你的仓库在 https://github.com/<USERNAME>/<REPO>），则将 base 设置为 "/<REPO>/"。

module.exports = {
	base: '/test/' // 比如你的仓库是test
}
1
2
3

# 创建脚步文件:

在project的根目录下，创建一个deploy.sh文件：

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io  USERNAME=你的用户名
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>  REPO=github上的项目
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -
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

# 设置 package.json：

{
	"scripts": {
		"d": "bash deploy.sh"
	}
}
1
2
3
4
5

# 部署：

然后你每次可以运行下面的命令行，来把最新更改推到github上：

npm run d
1

如果你对运行项目和构建项目的命令行觉得很烦，你也可以像我这么做：

"scripts": {
    "dev": "vuepress dev docs", // 本地运行项目 npm run dev
    "build": "vuepress build docs", // 构建项目 nom run build
    "d": "bash deploy.sh" // 部署项目 npm run d
},
1
2
3
4
5

# 更多：

实际上 VuePress 的配置、用法还有很多，像还可以配置 PWA，以及在 markdown 里面使用 Vue 组件等，这些功能我也还在摸索，所以大家一定要去看文档!

# 小结

上面已经写得尽可能详细了，我遇到的坑都写上去了。搭建起来确实很简单，心动不如行动，随手花一两个小时搭建一下又不吃亏，何乐而不为？

← Vue 定义全局函数 →