前言
来啦老铁！
接上一篇文章 玩玩 Google Codelabs ，今天我们来玩玩另外一个文档工具，以期能从中做个横向对比，它就是：
-
VuePress
笔者有一点 vue 的使用经验，对 Vue 还是挺喜爱的，而 VuePress 的作者跟 Vue 框架的作者同一个，都是尤雨溪，顿时感觉亲切无比，你说咱们是不是得拿下它~
网络摘抄：VuePress 是尤雨溪（vue.js 框架作者）4月12日发布的一个全新的基于 Vue 驱动的静态网站生成器，实际上就是一个 vue 的 spa （single page application, 单页应用）应用，内置 webpack，可以用来写文档、博客等。VuePress 专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。
主要参考文献：
整体步骤
- 开发环境搭建；
- 配置 VuePress；
- 站点设置；
- 使用开源主题；
- 生成静态文件；
- 简单对比Google Codelabs 与 VuePress；
1. 开发环境搭建；
-
确保安装了 Node.js，且 Node.js 版本 >= 8.6，安装过程参考上一篇文章：玩玩 Google Codelabs ；
-
找一个地方创建项目，项目名如：vuepress-docs；
-
使用 npm 初始化项目；
npm init
初始化项目
- 安装 vuepress；
npm install --save-dev vuepress
或：
npm install -D vuepress
- 在 package.json 中添加执行命令；
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
此时 package.json 中的内容为：
{
"name": "vuepress-docs",
"version": "1.0.0",
"description": "vuepress-docs",
"main": "index.js",
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
"author": "dylanz",
"license": "ISC",
"devDependencies": {
"vuepress": "^1.8.2"
}
}
- Hello VuePress 一下；
- 创建 docs 文件夹；
mkdir docs
- 简单搞个页面；
echo '# Hello VuePress!' > docs/README.md
- 启动服务；
npm run docs:dev
启动服务
VuePress 会在 http://localhost:8080 启动一个热重载的服务，即：修改文件，保存后会自动更新站点，方便开发。
- 浏览器访问 http://localhost:8080 ；
浏览器访问
怎么样，简单不，一个简单的页面就这么完成了，我们继续学习~
2. 配置 VuePress；
- docs 下创建 .vuepress 文件夹；
- .vuepress 文件夹下创建 config.js 文件；
网站的title、页面布局，页面目录以及插件的配置，都在这个 .vuepress/config.js 文件中，这个文件包含网站所有的配置信息；
接下来我们将会修改 .vuepress/config.js 对我们的站点进行配置~
3. 站点设置；
- 在 docs/README.md 文件中写入站点首页配置，如：
---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
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
---
- 修改 .vuepress/config.js 文件，如：
module.exports = {
title: 'VuePress 中文文档',
description: 'VuePress 中文文档，尤雨溪出品',
head: [
['link', { rel: 'icon', href: '/favicon.ico' }]
],
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://www.baidu.com' },
]
}
}
- .vuepress 文件夹下创建 public 文件夹，用于存放公共文件，如图片等；
- .vuepress/public 文件夹下准备好主页 logo 图片文件，如 hero.png
这时候你的项目目录是类似这样子的：
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
└─ public
└─ hero.png
│ └─ config.js
└─ package.json
- 重新部署站点后，这时候主页的样子：
主页
- 导航栏与侧边栏配置实践；
这部分参考文章 使用VuePress 搭建文档网站并进行配置 ，不难，笔者看到更酷炫的功能，等不及了，先来介绍下面的功能。
4. 使用开源主题；
VuePress 有个很强大的功能，那就是：主题。我们可以自定义主题，如上述 3 介绍的，就是一个简单的主题，然而上述的主题还是太过于粗糙了，自己玩玩还是可以，项目上有点拿不出手，并且作为初学者，我也不想花太多时间搞这些，怎么办？
还好，神通广大的网友开发了各种漂亮的主题，例如这个，就比较符合我的需求：
- demo: https://xugaoyi.com/
- github：vuepress-theme-vdoing
作为一个初学者，咱们先不纠结 VuePress 文档上的其他知识点，先探究一下这个 vuepress-theme-vdoing；
1. 快速上手：
# clone the project
git clone https://github.com/xugaoyi/vuepress-theme-vdoing.git
# enter the project directory
cd vuepress-theme-vdoing
# install dependency
npm install # or yarn install
# develop
npm run dev # or yarn dev
2. 执行完成后，会看到熟悉的 “success”：
success
3. 浏览器打开 http://localhost:8080/，酷炫来袭：
首页 1
首页 2
4. 页面很多，我们以“技术”为例，截几个图：
技术分类主页面
技术文章：Markdown使用教程
5. 简单对页面做一下分区介绍；
页面分区
-
第一个区域：
这个区域是已选中分类的导航栏，树状结构，清晰明了，同时支持将该导航栏收缩起来，扩大其他区域的大小； -
第二个区域：
这个区域是文档浏览窗口，顶部包含几个非常贴心的入口，即：“面包屑”导航（可以回到主页、跳转至所属分类主页面）、作者、写作日期；
分区二，顶部
而在区域的底部，也有一些非常贴心的入口，如：上次更新时间、上一篇与下一篇快速跳转入口、最近更新的文章的入口、github 方面的集成等；
分区二，底部
-
第三个区域：
这个区域是当前已浏览的文章的导航，可以快速跳转到段落，也是十分清晰明了；
页面的右下角有几个入口也是十分贴心，主要是：回到页面顶部入口、皮肤入口
页面右下角 1
页面右下角 2
6. 尝试在这个主题上做自己的页面；
- 首先在 docs 文件夹下创建如下目录与文件；
创建目录与文件
- 执行 npm run dev 命令；
我们执行 npm run dev 命令，执行完命令后，会在各新建的文件中自动填充内容，如：
---
title: 第一个测试文档
date: 2021-11-22 15:10:05
permalink: /pages/b060ae/
categories:
- 测试
- 子分类A
tags:
-
---
- 目录页设置；
如果需要展示目录，则需要在“00.目录页”文件夹下创建文件，如 “07.测试.md”（序号不限，不一定与文件夹序号一致，不过推荐一致，这样容易维护）；
我们可以设置我们的目录页，例如我们要用 “07.测试” 文件夹下的内容生成目录页，则：
---
pageComponent:
name: Catalogue
data:
key: 07.测试
imgUrl: /img/more.png
description: 这仅仅是个测试
title: 测试
date: 2020-03-11 21:50:56
permalink: /test
sidebar: false
article: false
comment: false
editLink: false
---
注意：
a. "key: 07.测试" 用于配置要自动生成目录页的是哪个文件夹下的内容；
b. "permalink: /test" 用于配置目录页的路由，这个自定；
- 编写文件；
我们可以写点简单的内容到文件中去，如：
---
title: 第一个测试文档
date: 2021-11-21 22:28:42
permalink: /pages/ee1b58/
categories:
- 测试
- 子分类A
tags:
-
author:
name: dylan zhang
link:
---
# 子分类A 测试文档1
Markdown语法参考
# 一级标题
## 二级标题
##### 五级标题
- 列表第一项
- 列表第二项
1. 有序列表第一项
2. 有序列表第二项
[标题](链接地址)
*斜体*
**粗体**
> 引用段落
\`\`\`
代码块
\`\`\`
- 探索设置导航栏；
修改 docs/.vuepress/config/nav.js 文件，如：
导航栏设置
{
text: '测试',
link: '/test/',
items: [
{ text: '子分类A', link: '/pages/ee1b58/' },
{ text: '子分类B', link: '/pages/fcdab6/' },
{ text: '子分类C', link: '/pages/50475e/' },
],
}
其中：
a. link 值为路由，items内的 link 一般设置子分类文件夹下的第一个文件中的 permalink 值；
b. 配置的顺序决定了导航栏上的顺序，如我们将“测试”设置在“技术”与“更多”之间；
- 浏览器打开 http://localhost:8080/ 验证结果；
a. 导航栏入口：
导航栏
b. 点击“测试”可进入“测试”目录页：
目录页
c. 点击“测试”分类下的子分类链接或目录页的文件链接，进入文件浏览页面：
文件浏览页面
- 探索主页大功能入口设置；
a. 找到 docs/index.md 文件，为“测试”添加主页入口，添加位置位于“features”字段下，如：
features: # 可选的
- title: 前端
details: JavaScript、ES6、Vue框架等前端技术
link: /web/ # 可选
imgUrl: /img/web.png # 可选
- title: 页面
details: html(5)/css(3)，前端页面相关技术
link: /ui/
imgUrl: /img/ui.png
- title: 技术
details: 技术文档、教程、技巧、总结等文章
link: /technology/
imgUrl: /img/other.png
- title: 测试
details: 这仅仅是个测试
link: /test/
imgUrl: /img/other.png
b. 保存后浏览器验证：
主页大功能入口
Ok，我们演示了如何探索式地增加分类、自动生成目录页、文件、主页大功能入口，主要就是模仿当前的项目文件结构和数据，作为快速使用方和调研目的，这样已经够了，其他功能点也是类似，请读者自行探索，我也会在后续应用场景中探索~
5. 生成静态文件；
执行命令：
npm run build
执行完命令后，会将产物放至：docs/.vuepress/dist，与上一篇文章介绍的一样，将该文件夹丢到nginx 服务器上后，就可以部署到远程服务器啦~
6. 简单对比 Google Codelabs 与 VuePress；
1. 开发环境搭建；
VuePress 更优。
VuePress 只需要 Node.js 环境，而 Google Codelabs 不仅需要 Node.js 环境，还需要 go 语言环境、还需要 claat (Codelabs command line tool) 工具。
2. 组织文档的方式；
VuePress 更优。
VuePress 作为文档空间，文档组织具有很强的结构化特点，加上开源主题的应用，使文档空间变得十分强大。而 Google Codelabs 是比较扁平化的文档组织方式，没有结构化、归纳等特点；
3. 文档浏览体验；
个人感觉 VuePress 更优。
在文档浏览页面，VuePress 不仅能浏览当前页面，并且有当前分类的导航、当前浏览页面的纲要，可以快速跳转到文档中的节点。
Google Codelabs 页面会按编写设置，将文档划分为不同节点（类似页面的纲要），点击节点也可以快速跳转到文档中的节点，但功能相对有限；
4. 文档浏览体验；
个人感觉 VuePress 更优。
VuePress 文档的编写，与编写任何 Markdown 文件无异，而 Google Codelabs 则需要按规则，设置好哪个文字作为节点的 title，实际上 Google Codelabs 节点的 title 占用了最大号的 Markdown head，如 “# 这是第一个节点title”。
截个图做一下对比：
文档浏览体验对比
5. 美观性；
个人感觉 VuePress 更优。
使用了开源主题前，VuePress 也不逊于 Google Codelabs，而使用了开源主题后，更是将 Google Codelabs 甩出几条街。
综上，不吹不黑，我个人感觉 VuePress 更胜一筹！
当然，不排除 Google Codelabs 可以在某些应用场景下应用，可能由于笔者见识少哈，请读者自行选择~
有兴趣的同学可以访问以下 demo 进行体验哈：
- Google Codelabs: http://clmirror.storage.googleapis.com/index.html
- VuePress（vuepress-theme-vdoing 主题）: https://xugaoyi.com/
另外，我们依然可以用上一篇文章介绍的 Minio 对象存储服务，作为图床。还有可以使用 Typora 进行 Markdown 文件的编写，有机会咱们也可以学起，nice to have：
好了，今天我们就先聊到这啦，更多的 VuePress 知识，官网上学习哈，有机会我们再聊聊这方面~
如果本文对您有帮助，麻烦动动手指点点赞？
非常感谢！
网友评论