VuePress搭建个人技术文档网站教程

VuePress 由两部分组成：一部分是支持用 Vue 开发主题的极简静态网站生成器，另一个部分是为书写技术文档而优化的默认主题。它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。

1. 安装

1.1 依赖环境：node8.0以上的版本

如果没有安装node，可在node官网选择对应操作系统下载安装：https://nodejs.org/zh-cn/

查看node版本：

~ node -v

v8.12.0

如果你的node版本低，请把node版本升级到8.0以上。
如何升级node：https://segmentfault.com/a/11...

1.2 安装VuePress

全局安装，打开终端，输入如下命令：

~ npm install -g vuepress

http fetch GET 200 https://registry.npm.taobao.org/caniuse-db/download/caniuse-db-1.0.30000909.tgz 3993ms
/usr/local/bin/vuepress -> /usr/local/lib/node_modules/vuepress/bin/vuepress.js
+ vuepress@0.14.5
removed 1 package and updated 13 packages in 68.944s

1.3 查看vuepress安装位置和版本

本人是Mac电脑，终端：

~ where vuepress
/usr/local/bin/vuepress
➜  ~ vuepress --version
0.14.5

2. 启动一个服务

终端创建一个文件夹,并创建一个md文件：

~ mkdir press
~ cd press
# 新建一个 markdown 文件
~ echo '# Hello VuePress!' > README.md

2.1 本地启动服务开发

终端输入命令：

~ vuepress dev .


 WAIT  Extracting site metadata...

 DONE  [00:34:16] Build 94707d finished in 5175 ms!

> VuePress dev server listening at http://localhost:8080/

此时在浏览器中输入http://localhost:8080/就能浏览效果了。

3. 配置文件说明

配置需要在文档目录下创建一个.vuepress目录,所有 VuePress 相关的文件都将会被放在这里。
终端创建一个文件夹：

mkdir .vuepress

其中有一个最重要的文件.vuepress/config.js，网站的所有文件的配置都在这个文件里面，
需要创建该文件touch .vuepress/config.js,该文件要导出一个JavaScript 对象：

module.exports = {
  title: '个人文档',
  description: '练习文档'
}

现在的目录结构：

.
├── .vuepress
│   └── config.js
└── README.md

4. 关于每个页面和路径说明

在vuepress里面，一个md文件就是一个页面，如在下面的目录结构中：

./
├── .vuepress
│   └── config.js
├── README.md
├── home1.md
└── page-a
    ├── README.md
    ├── a.md
    ├── b.md
    └── 你好.md

由于服务是在./启动的，所以路径以./为服务根路径。

• 默认主页
  服务启动后，默认找到的是./README.md文件，也就是http://localhost:8080/
• ./home1.md
  该文件在服务中的路径http://localhost:8080/home1.html。
  在vuepress中配置路径/home1
• ./page-a/README.md
  该文件在服务路径：http://localhost:8080/page-a/时默认找的文件。
  注意URL最后的/不能少，否则会去找./page-a.md文件。
• ./page-a/a.md
  该文件在服务的路径：http://localhost:8080/page-a/a.html。

注： md文件的文件名可以是中文，但是文件夹名字一定要是英文的。

5. 首页设置

vuepress内置了一个主页样式，是Front-matter格式的，
Front-matter教程：https://hexo.io/zh-cn/docs/fr...
首页的文件是根级README.md文件，在文件中写入如下配置：

---
home: true
heroImage: 
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
---
# Hello VuePress!

保存文件后页面效果如下图所示：

注意Front-matter一定要在md文件的顶部，否则不会生效。

6. 导航栏配置

导航栏可能包含你的页面标题、搜索框、 导航栏链接、多语言切换、仓库链接，它们均取决于你的配置。
导航栏通过.vuepress/config.js文件的themeConfig.nav来配置：

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },                      // 根路径
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' }, // 外部链接
      // 显示下拉列表
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'Japanese', link: '/language/japanese' }
        ]
      },
      // 下拉列表显示分组
      {
        text: '高级',
        items: [
          { 
            text: '算法', 
            items: [
              { text: '冒泡', link: '/language/chinese' },
              { text: '快速', link: '/language/japanese' }
            ] 
          },
          { 
            text: '设计模式', 
            items: [
              { text: '工厂', link: '/language/chinese' },
              { text: '单例', link: '/language/chinese'},
            ] 
          },
        ]
      }
    ]
  }
}

文件保存后，页面导航效果：

vuepress官方文档中关于导航栏的介绍：https://v0.vuepress.vuejs.org...

7. 侧边栏设置

如果你什么也不做，那么一个页面是没有侧边栏的,如下图所示：

如果想要配置侧边栏，需要用到sidebar参数，该参数可以在配置文件中配置，也可以在每个md文件中配置。

7.1 自动生成侧边栏(仅当前页面)

两种方法：

1. 在md文件的顶部写上下面代码：

   ---
   sidebar: auto
   ---

   此配置之针对当前md文件生效。
   注：此格式是YAML front matter,一定要在md文件的顶部才会生效。

2. 在.vuepress/config.js中配置

   // .vuepress/config.js
   module.exports = {
     themeConfig: {
       sidebar: 'auto'
     }
   }

   在配置文件中设置这句话后，所有页面都会生效。

配置后页面效果：

7.2 设置侧边栏标题显示的层数

默认情况下，侧边栏会自动显示当前页面的标题(h2~h3)组成的链接，按照页面本身的结构进行嵌套。
侧边栏不会显示h1标题，从h2开始显示，最多显示到h3。
可以通过在配置文件中配置themeConfig.sidebarDepth来设置嵌套层级

// .vuepress/config.js
 module.exports = {
   themeConfig: {
     sidebarDepth: 2,
   }
 }

或者在md文件的顶部使用YAML front matter来为某个页面重写此值：

---
sidebarDepth: 2
---

sidebarDepth可设置的值：

值	说明
0	禁用标题（headers）链接
1	默认值,只显示h2的标题
2	可设置的最大值，再大无效, 同时提取h2和h3标题

注：如果设置了 sidebar: 'auto' ,侧边栏会显示h2和h3标题，此时sidebarDepth的值只有0是生效的(仅显示h2的标题)，这里需要注意一下。

在md文件中标题的写法：

# 这是一级标题，对应HTML中<h1>标签

## 这是二级标题，对应HTML中<h2>标签

### 这是三级标题，对应HTML中<h3>标签
....

7.3 项目只显示一个侧边栏

如果想要所有页面显示一个侧边栏，那么需要在配置文件中添加sidebar字段:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/home1',
      ['/home2', 'home2自定义标题'],
      '/home3',
      '中文',
    ]
  }
}

说明：

1. 可以省略 .md 拓展名
2. 以/结尾的路径将会被视为*/README.md
3. 页面的链接文字自动获取(页面的第一个header)，如果明确地在 YAML front matter 中指定页面的标题，则
   显示front matter中的标题。
4. 也可以指定链接的文字，使用一个格式为 [link, text] 的数组。

md文件顶部使用front matter设置标题的方法：

---
title: 自定义标题
---

配置好后页面效果：

7.4 侧边栏分组

你可以通过使用对象来将侧边栏划分成多个组

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: '一组题目',
        collapsable: false,
        children: [
          '/', '/home1',
        ]
      },
      {
        title: '二组题目',
        children: [
          ['/home2', 'home2自定义题目'], 
          '/home3',
          '/中文',
        ]
      }
    ]
  }
}

侧边栏的每个子组默认是可折叠的，你可以设置 collapsable: false 来让一个组永远都是展开状态。

设置后页面效果，其中二组题目是可以折叠的：

7.5 设置多个侧边栏

如果你想为不同的页面组来显示不同的侧边栏，需要把一个侧边栏下的多个文件放在一个目录下，一个侧边栏一个目录，如下面的文件结构：

.
├── README.md
├── home1.md
├── home2.md
├── home3.md
├── bar
│   ├── README.md
│   ├── one.md
│   └── two.md
└── page-a
    ├── README.md
    ├── a.md
    └── b.md

配置文件中的sidebar做如下设置：

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      // /bar/ 一个侧边栏，里面的三个页面共用一个侧边栏
      '/bar/': [
        '',           // ./bar/README.md文件，对应页面上/bar/路径
        'one',        // ./bar/one.md文件，对应页面上/bar/one.html
        'two',        // ./bar/two.md文件，对应页面上/bar/two.html
      ],
      '/page-a/': [
        '',
        'a',
        'b',
      ],
      // 确保'/'侧边栏被最后定义。VuePress 会按顺序遍历侧边栏配置来寻找匹配的配置。
      '/': [
        '',
        'home1',
        'home2',
        'home3',
      ],
    },
  }
}

8. 项目部署

目前服务启动的只是本地服务，vuepress还可以把文档生成静态html文件项目，部署到服务器或第三方托管网站上。
生成最终静态文件命令：

vuepress build .

该命令执行完毕后会在.vuepress文件夹下生成dist目录：

该目录里面的文件就是生成的最终静态HTML文件，可把该目录复制到服务器或第三方托管网站部署成自己的文档网站。

8.1 部署到GitHub Pages

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

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

设置base的值：

// .vuepress/config.js
module.exports = {
  base: '/press/',     // 仓库名字是press
  themeConfig: {}
}

8.1.2 创建一个自动执行脚本

为了方便部署，可创建一个自动部署脚本文件deploy.sh,文件内容如下：

#!/usr/bin/env sh

echo '开始执行命令'
# 生成静态文件
echo '执行命令：vuepress build .'
vuepress build .

# 进入生成的文件夹
echo "执行命令：cd ./.vuepress/dist\n"
cd ./.vuepress/dist

# 初始化一个仓库，仅仅是做了一个初始化的操作，项目里的文件还没有被跟踪
echo "执行命令：git init\n"
git init

# 保存所有的修改
echo "执行命令：git add -A"
git add -A

# 把修改的文件提交
echo "执行命令：commit -m 'deploy'"
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

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

# 返回到上一次的工作目录
echo "回到刚才工作目录"
cd -

然后在终端执行如下命令来运行脚本：

bash deploy.sh

还可以使用./deploy.sh命令，不过该命令需要deploy.sh文件是可执行文件，在终端输入如下命令可把文件变成可执行文件：

chmod +x deploy.sh

注意：

1. vuepress每次执行后都会先删除dist目录，然后从新打包的，所有git都是从新添加在提交。
2. git推送是强制push的，所以github上仓库只会有一次提交。
3. 推荐把打包后的文件传到gh-pages分支上，这样就可以源码跟打包后静态文件在一个仓库上。

8.2 GitHub Pages绑定域名

可以在上面的deploy.sh脚本中加入echo 'yuming.cn' > CNAME：

# 生成静态文件
vuepress build .

# 发布到自定义域名
echo "把域名放到CNAME文件中"
echo 'yuming.cn' > CNAME

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

注意：如果GitHub Pages绑定域名，那么配置文件中的base参数则需要删除，否则域名访问会失败。

9. 其他一些个性化定制

9.1 修改默认主题

vuepress 0.14版本可以把默认主题使用如下命令复制出来。
如果你的项目名称是press,那么可在终端下：

vuepress eject press

 DONE  Copied default theme into /Users/用户名/tmp/press/.vuepress/theme.

这个命令来将默认主题的源码复制到 .vuepress/theme 文件夹下，从而可以对默认主题进行任意的修改。需要注意的是一旦 eject，即使升级 VuePress 你也无法再获得 VuePress 对默认主题的更新。

参考资料

vuepress 0.4版本官方文档：https://v0.vuepress.vuejs.org...
Front-matter 教程：https://hexo.io/zh-cn/docs/fr...