VuePress 是一款使用 Vue 驅(qū)動的靜態(tài)網(wǎng)站生成器，是 Vue 的作者 Evan You 為了方便文檔的編寫而開發(fā)的。
- 默認(rèn)主題與 Vue 官方文檔一致
- 簡潔，少配置，高性能
- Markdown 專為技術(shù)文檔提供拓展
- 自帶 PWA
- 自定義主題，可定制程度完全由自己決定
官方文檔：由于 1.x 還處于測試階段，可能隨時變更，所以建議選用 0.x 版本
1. 初始化
安裝
首先需要安裝 vuepress
可以使用全局安裝：（選一個版本安裝即可，使用 yarn 或 npm 都可以）
yarn add global vuepress # 0.x 版本
yarn add global vuepress@next # 1.x 版本
也可以使用局部安裝，在你的項目根目錄下：
yarn add -D vuepress
yarn add -D vuepress@next
注意有一個坑，我遇到過，安裝 vuepress@next 以及其他插件時，默認(rèn)會安裝 alpha 0 版本，需要修改 package.json 文件，更改版本號，再重新使用 yarn 安裝一下。
另外，全局安裝與局部安裝在后面的部署命令中會有些差別。
結(jié)構(gòu)目錄
.
├── docs
│ ├── .vuepress
│ │ ├── public
│ │ └── config.js
│ │
│ └── README.md
│
└── package.json
可詳細(xì)查看：目錄結(jié)構(gòu)
2. 配置 config.js 文件
基礎(chǔ)配置
module.exports = {
title: "destiny'Note",
description: "生命的意義不僅是活著，而是我們給別人的生命帶來了何種不同。",
base: '/', // 項目根路徑
dest: '/dist/', // 打包后的文件夾路徑，為了方便，我把 dist 文件夾放到了根目錄上
// head 標(biāo)簽中的額外內(nèi)容
head: [
['link', { rel: 'icon', href: '/favicon.ico' }] // 這個是標(biāo)簽頁 logo
],
// 語言配置
locales: {
// 鍵名是該語言所屬的子路徑
// 作為特例，默認(rèn)語言可以使用 '/' 作為其路徑。
'/': {
lang: 'zh-CN', // 將會被設(shè)置為 <html> 的 lang 屬性
}
}
}
可詳細(xì)查看：配置
主題配置
module.exports = {
...
// 主題配置
themeConfig: {
// 頂部導(dǎo)航
nav: [
{ text: '首頁', link: '/' },
{ text: '歸檔', link: '/archives/'},
{ text: '分類', link: '/categories/' },
{ text: '標(biāo)簽', link: '/tags/' },
{ text: '關(guān)于我', link: '/about/' }
],
// 側(cè)邊欄
sidebar: [
'/'
],
sidebarDepth: 2, // 默認(rèn) 1 提取到 h2，0 為禁用，2 為 h2，h3
displayAllHeaders: false, // 默認(rèn)值：false 側(cè)邊欄只會顯示由當(dāng)前活動頁面的標(biāo)題組成的鏈接
activeHeaderLinks: true, // 默認(rèn)值：true 滾動時通過 hash 高亮側(cè)邊欄標(biāo)題
// Git 倉庫和編輯鏈接
repo: 'username/repo', // 你的倉庫
repoLabel: 'GitHub', // 導(dǎo)航欄上的文本
editLinks: true,
// 默認(rèn)為 "Edit this page"
editLinkText: '編輯此頁面'
}
}
可詳細(xì)查看：默認(rèn)主題配置
3. 首頁
配置 docs 下的 README.md 文件即可：
---
home: true
heroImage: /hero.jpg
heroText: Hero
tagline: Hero 副標(biāo)題
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 簡潔至上
details: 以 Markdown 為中心的項目結(jié)構(gòu)，以最少的配置幫助你專注于寫作。
- title: Vue驅(qū)動
details: 享受 Vue + webpack 的開發(fā)體驗，在 Markdown 中使用 Vue 組件，同時可以使用 Vue 來開發(fā)自定義主題。
- title: 高性能
details: VuePress 為每個頁面預(yù)渲染生成靜態(tài)的 HTML，同時在頁面被加載的時候，將作為 SPA 運行。
footer: MIT Licensed | Copyright ? 2018-present Evan You
---
首頁必須設(shè)置 home 為 true。默認(rèn)樣式與官方文檔首頁一致。
4. 開發(fā)和部署
定義腳本
初始化 package.json，如果是局部安裝的話，這個文件已經(jīng)存在，不需要執(zhí)行這個命令
yarn init
編輯 package.json 文件，添加如下腳本：（這里需要注意）
{
...
// 全局安裝
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
}
// 局部安裝
"scripts": {
"dev": "npx vuepress dev docs",
"build": "npx vuepress build docs"
}
}
個人不喜歡官方的寫法，就把名稱寫的簡潔一些。
運行腳本命令：
yarn dev # 開發(fā)
yarn build # 打包
部署到 GitHub Pages 上
部署到 GitHub 上，首先要在 GitHub 上建立倉庫，這里省略。
然后再本地初始化倉庫，并關(guān)聯(lián)遠(yuǎn)程倉庫
git init
git remote add origin <repo> # 你的遠(yuǎn)程倉庫
打包之后把整個項目上傳到 master 分支上，方便管理
git add -A
git commit -m 'init blog'
# 首次提交需要 --set-upstream，后續(xù)可以去掉
git push --set-upstream origin master # 所有代碼推送到遠(yuǎn)程倉庫的 master 分支上
單獨將打包好的文件上傳到 gh-pages 分支上，自動會生成 GitHub Pages，在倉庫設(shè)置里可以查看到相應(yīng)地址。
git subtree push --prefix dist origin gh-pages # 只將 dist 上傳到 gh-pages 分支
注意，最好配置一個 .gitignore 文件，去掉不需要上傳的文件和文件夾。
自動化部署
每一次更新完文章之后，都需要敲一大串代碼，才能重新部署，顯得很繁瑣。那么我們來讓這些命令合并成一個命令吧。
項目根目錄下創(chuàng)建 deploy.sh 文件：
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯誤
set -e
# 生成靜態(tài)文件
yarn build
# 提交到歷史區(qū)，$1 為運行 sh 時的第一個參數(shù)
git add -A
git commit -m $1
# 提交到 master 分支
git push origin master
# 將 dist 文件提交到 gh-pages 分支
git subtree push --prefix dist origin gh-pages
# 退出命令
exit 0
然后在 package.json 文件中配置腳本：
{
"scripts": {
//...
"deploy": "bash deploy.sh"
}
}
后續(xù)部署直接使用命令：
yarn deploy "updatedBlog"
需要注意的是，后面帶的消息，不能使用空格隔開（本人對 shell 腳本不熟悉，查找了也沒明白，希望有大神指點一下），使用了空格，就會導(dǎo)致只提交了空格前的消息
另外，這個命令需要在 git bash 中使用，不能在 Windows 的命令行中使用。
5. 后續(xù)
太喜歡 VuePress 了，因為后面都托管給 Vue 了，所以速度飛快。
后續(xù)會出一個如何修改默認(rèn)主題的文章。
