一步步搭建 VuePress 及優化【初始化到發佈】

介紹

在以前爲了搭建 VuePress 的文檔，順帶製做了視頻教程，現在準備再次搭建一個 VuePress 的項目，一看本身的視頻居然有五個小時，天吶，我只是須要過一遍而已，因此從新整理成文檔吧，萬一未來又要用呢……

固然，若是您以爲文字版不夠直觀，能夠前往觀看視頻版： 【☛ 視頻地址 ☚】 ，當時錄製完本地測試後以爲聲音大小還能夠，結果一套錄完了才發現聲音很小，因此推薦帶上耳機。

VuePress 文檔示例

環境準備

對於環境準備不怎麼熟悉的仍是推薦看 視頻第一節 吧。

Windows

1. 安裝 cmder

   解壓完成後複製其路徑地址，將其添加到環境變量。

   使用 Win + R 鍵快速啓動 cmder，若成功則添加環境變量成功。

2. 安裝 git

   安裝包一路 next 便可，在桌面上右鍵出現 git bash here 或命令行中輸入 git --version 可以獲得具體的版本信息則安裝成功。

3. 安裝 nodejs

   安裝包一樣一路 next 便可，在命令行輸入 node -v ，若獲得具體版本信息則安裝成功。

4. 安裝 yarn

   安裝完成後，在命令行輸入 yarn --version ， 若獲得具體版本信息則安裝成功。

5. 建立項目

   建立項目能夠分爲兩種形式：

   • 遠程倉庫

     # xxx 爲你的遠程倉庫鏈接
     git clone xxx
     cd your_project_name
     npm init -y

   • 本地倉庫

     # xxx 爲你的遠程倉庫鏈接
     npm init your_project_name -y
     cd your_project_name
     git remote add origin xxx

6. 安裝 vuepress

   # 全局安裝
   yarn global add vuepress@next # 或者：npm install -g vuepress@next
   
   # 本地安裝
   yarn add -D vuepress@next # 或者：npm install -D vuepress@next

7. 配置 package.json 腳本

   若是你的文檔不是在 docs 下，能夠按照你的設置來：

   {
     "scripts": {
       "docs:dev": "vuepress dev docs",
       "docs:build": "vuepress build docs"
     }
   }

   上面配置完後，能夠進行測試：

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

   若能在瀏覽器中正常訪問，則表示安裝成功。

Linux

Linux 配置與 Windows 所需一致，相信都用上 Linux 了，這點問題可以解決。

搭建及優化

1. 瞭解路由與配置導航

關於文件是如何渲染爲對應的路由的：

文件的相對路徑	頁面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

瞭解了這個基本的概念後，就能夠去配置對應的導航了。具體的導航欄配置介紹能夠看 官方文檔，看不懂能夠去看個人 視頻 。

在實踐後發現，若將全部內容放置在 docs/.vuepress/config.js 下將會很臃腫，難以閱讀與維護，推薦將其分離開，在根目錄下新建一個 config 文件夾：

// docs/.vuepress/config.js
const navConf = require('../../config/navConf.js');

module.exports = {
  themeConfig: {
    nav: navConf
  },
}

舉個例子：

// config/navConf.js
module.exports = [
  { text: 'Home', link: '/' },
  { text: 'Guide', link: '/guide/' },
  { text: '基礎', items: [
    { text: 'Algorithm', link: '/base/algorithm/' },
    { text: 'Interview', link: '/base/interview/' },
    { text: 'Clean', link: '/base/clean/' },
    { text: 'Git', link: '/base/git/' },
  ]},
  {
    text: '開發',
    items: [
      { text: 'FrontEnd', items: [
        { text: 'JavaScript', link: '/FrontEnd/javascript/' },
        { text: 'CSS', link: '/FrontEnd/css/' },
        { text: 'Webpack', link: '/FrontEnd/webpack/' },
        { text: 'Nodejs', link: '/FrontEnd/nodejs/' },
      ]},
      { text: 'BackEnd', items: [
        { text: 'Koa', link: '/BackEnd/koa/' },
        { text: 'MongoDB', link: '/BackEnd/mongodb/' },
        { text: 'Nginx', link: '/BackEnd/nginx/' },
      ] },
    ]
  }
];

2. 配置側邊欄

側邊欄比導航欄要更爲繁瑣一些。具體的導航欄配置介紹能夠看 官方文檔 。

首先在 docs 文件夾下新建你須要的目錄及文件：

OS
├── centos
│   ├── 01-add-user.md
│   ├── 02-login-with-rsa-key.md
│   ├── 03-upload-file-to-server.md
│   └── README.md
├── manjaro
│   ├── 01-solve-problems-with-manjaro.md
│   └── README.md
└── windows
    └── README.md

配置 config 文件，當文章不少的狀況下，還集中在 config 文件中，那就得炸了：

// docs/.vuepress/config.js
const sidebarConf = require('../../config/sidebarConf/index.js');

module.exports = {
  themeConfig: {
    sidebar: sidebarConf
  },
}

文章須要進行分類，因此會分紅更多的子文件，經過 index.js 進行管理：

# config/sidebarConf

sidebarConf
├── Base
│   ├── algorithm
│   │   └── index.js
│   ├── clean
│   │   └── index.js
│   ├── git
│   │   └── index.js
│   └── interview
│       └── index.js
├── Guide
│   └── index.js
├── index.js
└── OS
    ├── centos
    │   └── index.js
    ├── manjaro
    │   └── index.js
    └── windows
        └── index.js

// config/sidebarConf/index.js

// 介紹
const guide = require('./Guide/index.js');

// 基礎
const git = require('./Base/git/index.js');
const interview = require('./Base/interview/index.js');
const algorithm = require('./Base/algorithm/index.js');
const clean = require('./Base/clean/index.js');

// 操做系統
const windows = require('./OS/windows/index.js');
const manjaro = require('./OS/manjaro/index.js');
const centos = require('./OS/centos/index.js');


/**
 * 側邊欄的配置
 * 當路由深度越深時應當排序在更前方
 * 示例: /frontend 和 /frontend/css
 * 
 * 應當將 /frontend/css 寫在更上方
 */
module.exports = {
  // 指南 Guide
  '/guide/': guide,

  // 基礎 Base
  '/Base/git/': git,
  '/Base/interview/': interview,
  '/Base/clean/': clean,
  '/Base/algorithm/': algorithm,

  // 操做系統 OS
  '/OS/manjaro/': manjaro,
  '/OS/windows/': windows,
  '/OS/centos/': centos,

  // 根目錄下的 sidebar, 對於全部未匹配到的都會應用該 sidebar
  // '/': [''] // 此處選擇禁用
};

以 CentOS 舉個例子：

// config/sidebarConf/OS/centos/index.js
const utils = require('../../../../utils/index.js');
const children = ['','01-add-user','02-login-with-rsa-key','03-upload-file-to-server'];

module.exports = [
  utils.genSidebar('CentOS', children, false),
];

genSidebar 函數：

const utils = {
  genSidebar: function (title, children = [''], collapsable = true, sidebarDepth = 1) {
    return {
      title,
      collapsable,
      sidebarDepth,
      children
    }
  }
};

module.exports = utils;

3. SEO 配置

基本配置能夠幫助咱們作好網站的 SEO，更容易被搜索到。具體的基本配置介紹能夠看 官方文檔 。

// docs/.vuepress/config.js
module.exports = {
  title: '飛躍高山與大洋的魚',
  description: '飛躍高山與大洋的魚的文檔, vuepress 文檔',
}

4. 更新時間與靜態資源

更新時間，若是按照文檔進行配置的話時間格式是非中文的風格，解決很簡單：

// 添加多語言，改成國內便可

module.exports = {
  locales: {
    '/': {
      lang: 'zh-CN', 
    }
  },
  themeConfig: {
    lastUpdated: '上次更新',
  },
}

全部的靜態資源都須要放置在 .vuepress/public 目錄下，你也能夠爲它們創建分類文件夾（這裏很差的效果是在預覽本地的 Markdown 文件時沒法看到圖片）：

public
├── apple-touch-icon.png
├── app.png
├── base
│   └── interview
│       └── 1468042984788341.png
├── favicon-32x32.png
├── favicon.ico
├── FrontEnd
│   └── javascript
│       ├── es6_20190112123602.png
│       └── es6_20190112124206.png
├── manifest.json

5. 部署到 github 並關聯到自定義域名

具體的部署介紹能夠看 官方文檔 。

以前作視頻的時候尚未 Travis CI 的使用說明，剛剛看的時候發現有了，昨天花了很久來硬啃 Travis 官網，血虧……

這邊我發佈到的是 docs.shanyuhai.top ，因此 base 屬性默認爲空便可；如果發佈到 docs.shanyuhai.top/docs 則 base 屬性爲 docs。

deploy.sh 文件示例：

#!/usr/bin/env sh

# 確保腳本拋出遇到的錯誤
set -e

# 生成靜態文件
npm run docs:build

# 進入生成的文件夾
cd docs/.vuepress/dist

# 若是是發佈到自定義域名
echo 'docs.shanyuhai.top' > CNAME

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

# 若是發佈到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:shanyuhai123/documents.git master:gh-pages

cd -

6. 添加 Git 倉庫和編輯連接

參考文檔及視頻同上：

// docs/.vuepress/config.js

module.exports = {
  themeConfig: {
    // 你的 Git 項目地址，添加後會在導航欄的最後追加
    repo: 'shanyuhai123/documents',
    // 啓用編輯
    editLinks: true,
    // 編輯按鈕的 Text
    editLinkText: '編輯文檔！',
    // 編輯文檔的所在目錄
    docsDir: 'docs',
    // 假如文檔放在一個特定的分支下：
    // docsBranch: 'master',
  },
}

7. 域名解析

關於域名解析詳情能夠去看個人 視頻 （第五個視頻中的解析方式存在問題）。

解析方式須要改成 CNAME 的形式：

最後

爲了方便閱讀，因此將內容進行了劃分：

1. VuePress 初始化及發佈
2. VuePress 插件系列
3. VuePress 自動化

參考資料

1. VuePress 官網