VuePress构建一个文档管理网站

序言

目前无论笔记还是项目文档，大部分我都会通过 Markdown来记录，并且大部分文档写完都只存在自己电脑上，每次查找起来都需要耗费一些时间

自己的写的一部分技术教程由于初次记录时了解知识不多，内容存在偏差或考虑不全面，后面需要修订和再加工过程，因此创建一个随时可查看，可编辑补充的文档知识库对我来说尤为得较为重要。

想法不落实于行动，毕竟还是想法，于是网上查阅了创建文档库的相关资料，分为以下几类：

• 1，Hexo

快速、简介且高效的博客框架 是官网对自己的介绍，Hexo是基于 Node.js 搭建因此响应速度比较快，结合 Github Pages 可以一键部署；

• 2，VuePress

运行时会将将每个Markdown 预渲染生成静态 的 HTML，每个页面加载时将作为 SPA 运行，VuePress 是基于 Vue + webpack 开发，对于 vue 开发者相对比较友好，对 SEO 相对友好

• 3，Docute

也是基于 vue 开发，采用运行时解析的策略，适用于公司内部文档系统，

• 4，docsify

与 Docute 相同，该框架也是基于 vue 开发， 并且采用运行时解析的策略，可支持多种主题切换。

注：以上方法 1-4 都不需要后端接入。

• 5，自己搭建

也就是说需要自己手动搭建一个文档平台，技术方向一定涉及前端，可能也会涉及的后端和运维，与前面已经较为成熟的开源框架相比，自己搭建的话，周期要长许多；

由于自己之前了解过一点 Vue 基础，并且 VuePress 的网站主题自己也比较喜欢，因此个人的文档平台是基于 VuePress 搭建，初步效果如下：

用 VuePress 创建一个实例项目

安装Node.js

VuePress 是基于 Vue 开发，而 Vue 运行又依赖于包管理器( 这里我采用npm )，在使用 VuePress 之前，请确保本机已经安装好 Node.js ， 地址：Node.JS 官网

Windows 安装 Node.js 是通过安装包方式，按照指引一路下一步即可，安装完成之后，记得需要手动将 Node 安装路径加入环境变量。

创建项目

VuePress 提供了一种创建项目的快捷方式，建议大家参考官方英文版文档（中文版这部分缺失）

::: NodeJS 版本要在 10 以上

在合适的文件夹下，打开终端，输入以下命令：

# optionalDirectoryName 为文件见名
npx create-vuepress-site [optionalDirectoryName]

# 根据指引，依次填写项目名、项目表述、email、作者名、项目仓库
---
? What's the name of your project? docs
? What's the description of your project? docs
? What's your email? docs
? What's your name? docs
? What's the repo of your project? docs
   create docs\docs\.npmignore
   create docs\docs\package.json
   create docs\docs\src\.vuepress\components\demo-component.vue
   create docs\docs\src\.vuepress\components\Foo\Bar.vue
   create docs\docs\src\.vuepress\components\OtherComponent.vue
   create docs\docs\src\.vuepress\config.js
   create docs\docs\src\.vuepress\enhanceApp.js
   create docs\docs\src\.vuepress\styles\index.styl
   create docs\docs\src\.vuepress\styles\palette.styl
   create docs\docs\src\config\README.md
   create docs\docs\src\guide\README.md
   create docs\docs\src\guide\using-vue.md
   create docs\docs\src\index.md
📋 Copied to clipboard, just use Ctrl+V
✨ File Generate Done
---
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

项目启动

以上操作完成之后，先别关闭终端，输入以下命令

# optionalDirectoryName 同上个步骤，没填的话可以忽略
cd [optionalDirectoryName]

# 安装 vue-template-compiler
npm i vue-template-compiler

npm run dev

# 当终端出现以下信息时，代表项目启动成功
---
success [23:47:27] Build 108e22 finished in 5821 ms!
> VuePress dev server listening at http://localhost:8081/
---
1
2
3
4
5
6
7
8
9
10
11
12
13

用浏览器打开项目启动成功后的网址，默认为 localhost:8080 ，默认展示页面如下：

VuePress 项目依赖介绍

创建后的项目基本依赖数如下（依赖树忽略了 node_modules(第三方依赖包)、package.json（npm 项目配置文件))：

src
├─index.md     
├─guide        
|   ├─README.md
|   └using-vue.md
├─config
|   └README.md
├─.vuepress
|     ├─config.js
|     ├─enhanceApp.js
|     ├─styles
|     |   ├─index.styl
|     |   └palette.styl
|     ├─components
|     |     ├─demo-component.vue
|     |     ├─OtherComponent.vue
|     |     ├─Foo
|     |     |  └Bar.vue
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

• src/.vuepress -> VuePress 相关的配置都放置在在该文件夹下
  • src/.vuepress/config.js -> VuePress 核心配置文件，配置站点标题、描述，主题，插件、侧边栏、上边栏等；
  • src/.vuepress/styles 用于重写项目样式
    • src/.vuepress/styles/index.styl ：非变量样式；
    • src/.vuepress/styles/palette.styl ：核心是一些颜色样式；
  • src/.vuepress/components ： 自定义的一些 Vue 组件，在 vuePress 中 Markdown 中 是可以使用 Vue 组件的；

src 除去 .vuepress 文件夹外，剩下就是文档库需要填充的MarkDown，之前介绍过 VuePress 的运行机制，是将 每一个 .md 文件预渲染成 Html 页面，因此项目中 每个md 文件 都可以看作一个页面；

src
├─index.md     
├─guide        
|   ├─README.md
|   └using-vue.md
├─config
|   └README.md
1
2
3
4
5
6
7

src/index.md 页面既可以设为 项目启动的主页，我们可以通过查看index.md 内容与主页进行比对，来简单了解下，vuePress 中 md 的语法， index.md 中的内容如下

---
home: true
heroImage: https://v1.vuepress.vuejs.org/hero.png
tagline: docs
actionText: Quick Start →
actionLink: /guide/
features:
- title: Feature 1 Title
  details: Feature 1 Description
- title: Feature 2 Title
  details: Feature 2 Description
- title: Feature 3 Title
  details: Feature 3 Description
footer: Made by docs with ❤️
---
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

从内容可以看到，首页 index.home 的首尾部分都含有 --- 标识符，这是因为 VuePress 提供了 YAML frout matter，

标识符 --- 内的这些数据可以在当前及任意自定义或主题组件中使用，也就是说，这些数据都是动态配置的，根据确定好的约定，通过设定某些值，让其放置在固定位置

YAML frout matter 中的变量称之为 预定义变量，VuePress 默认主题 首页index.md中 预定义变量定义如下：

• home 是否为首页；
• title : 标题
• tagline: 标题下的描述
• heroImage : 首页主图
• actionText: 首页按钮
• features 首页下的方块，由标题title 和 details 描述组成
• footer 页面底部内容

在 VuePress 中 ，需要注意的是，根据使用主题的不同，使用到Font Matter 中的预定义变量也有可能不同，具体详情需要参考相关主题官网介绍。

基本配置

VuePress 的配置文件 conf.js 位于 .vuepress 的下面；配置文件的类型，VuePress 支持以下几种：

• .vuepress/config.js；
• .vuepress/config.yml；
• .vuepress/config.toml；
• .vuepress/config.ts； (1.9.0 版本以上支持)

配置文件中常用到额几个配置：

base ：String 类型，表示网站的首页路径，默认为 / ；也可以加上前准/xxx/ ，加上前缀后再部署到服务器上，此时完整路径为 https://abc.com/xxx/，其中 https://abc.com 为网站的域名；

title: String 类型，默认主题下，站点导航栏标题，即为浏览器中打开网页时显示的文字，如下：

VuePress中， 默认 title 是所有页面标题的后缀，以 | 符号分隔；

description ：String 类型

站点描述，将渲染为页面 HTML 的 meta 标签，用于网站介绍和 SEO 优化；

head ：数组类型(Array)

HTML 页面的其它额外标签，设置时每个标签的格式为 [tagName,{attrName:attrValue},innerHTML] ，如下，配置网站导航栏的icon

  head: [
    ['link', { rel: 'icon', href: '/logo.png' }]
  ]

1
2
3
4

port : number 类型

指定服务器 dev 环境运行的端口号，默认 8080;

dest: String 类型

指定vuepress build 打包后的文件路径，默认为 ./vuepress/dist，如果指定的是一个相对路径，则基础路径将以 process.cwd() 为基准；

locales ：Object 类型，

指定 i18n 支持的语言环境，利用该属性和多语言版本文档可以将站点适配为多语言支持。

extraWatchFiles: 数组类型

指定额外需要监听的文件，当文件发生变化，会触发 vuepress 重新打包并实时更新，如下：

module.exports = {
  extraWatchFiles: [
    '.vuepress/foo.js', // Relative path usage
    '/path/to/bar.js'   // Absolute path usage
  ]
}
1
2
3
4
5
6

patterns： 数组

指定想要解析的文件 格式，默认为 ['**/*.md','**/*.vue]

---

样式 Styling

对于 VuePress 默认预设 的样式想要简单的重写，或者定义一些变量用于之后使用，可以创建一个 .vuepress/styles/pattele,styl 文件

对于一些预定义的变量，可以进行调整，如下：

// colors
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961

// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px

// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

在根目录下的 stylus 配置文件 ，palette.styl 将被导入在最后，一些文件将使用它，因此一旦在这个文件写入 styles ，则样式将会被复制多次。

index.styl

对于一些额外的样式的添加，VuePress 也提供了一个便捷的方式，可以创建一个 .vuepress/styles/index.styl 文件，可以在里面陷入正常的 css 语法。

---

主题配置

theme : 字符串，此参数指定一个自定义主题；

themeConfig ： type 对象

为使用的主题提供配置选项，此参数根据使用的主题变化而变化

配置 Pluggable 插件

plugins ：对象或数组；

VuePress 中 插件一般会在项目中插入一些全局函数，对使用范围并没有严格定义限制，可在 Awesome-vuepress 找到很多有用的 VuePress 插件.

目前插件分为以下几大类：

1，在编译期扩展页面生成的元数据，如@vuepress/plugin-last-updated;

2，在编译器前后生成额外文件，如 @vuepress/plugin-pwa;

3，注入全局 UI 组件，例如：@vuepress/plugin-back-to-top;

4，通过自定义命令扩展 CLI ，如 vuepress-plugin-export (opens new window)

以 @vuepress/plugin-blog 为例，简单介绍下使用流程

安装

yarn add -D @vuepress/plugin-blog
# 或 npm install -D @vuepress/plugin-blog
1
2

使用

// .vuepress/config.js
module.exports = {
  plugins: [
    '@vuepress/blog',
    {
      /* options */
    },
  ],
}
1
2
3
4
5
6
7
8
9

具体更多细节参数的配置可以参考插件对应提供的官方文档

Markdown

markdown.lineNumbers: 布尔值

在代码块的左侧是否显示行数

markdown.anchor：Object

markdown-it-anchor 的选项( 首选markdown.slugify 来自定义 header 的 ids)，VuePress 将 md 文件类型转化为 html 依靠的 是 markdown-it 组件。

markdown.extractHeaders : Array，默认 [‘h2’,‘h3’]

在预编译页面时，headers 将会从 markdown 去除，并存入this.$page.headers 中，默认 VuePress 将取出 h2、h3 标签，你可以覆盖它在 markdown中的标题。

创建流程

configureWebpack : 对象和函数类型

编辑 webpack 内部配置

• 设置的如果一个对象，将使用 webpack-merge 与所有配置进行合并；

• 设置的如果是一个函数，则函数就需要写为 第一个参数为webpack 配置参数，第二个 以 isServer 作为第二个；可以直接修改配置或者返回一个对象进行合并，如下：

module.exports = {
  configureWebpack: (config, isServer) => {
    if (!isServer) {
      // mutate the config for client
    }
  }
}
1
2
3
4
5
6
7

chainWebpack：函数类型，默认为空

用 webpack-chain 编辑内部 webpack 配置

module.exports = {
  chainWebpack: (config, isServer) => {
    // config is an instance of ChainableConfig
  }
}
1
2
3
4
5

热更新配置

初始 vuepress 项目启动时，可能会出现热更新失效问题:

热更新即为 修改项目中某一配置文件中配置或代码，项目代码保存后，无需重启项目，项目自动重新编译，并且自己的修改也会在编译后重新生效

解决方法：在 package.json 文件中 的 scripts 属性替换为以下代码

"scripts": {
    "dev": "vuepress dev src --temp .temp",
    "build": "vuepress build src"
 },
1
2
3
4

项目重启后会自动创建一个 .temp 文件夹 来存放临时文件