前言
只聽過vue罐盔，沒聽過vuepress揭厚？它可是新的vue全家桶成員之一却特，尤雨溪大神于2018年4月12日推出。
不信筛圆？請(qǐng)看Evan You github裂明。star數(shù)已過萬，并不少太援。
vuepress用于迅速搭建技術(shù)文檔網(wǎng)站與個(gè)人博客闽晦，簡(jiǎn)單快捷，下面和我一起開始學(xué)習(xí)吧提岔！
（想直接coding的同學(xué)可從第三節(jié)開始）
一尼荆、模塊概述
1. 定義
Vue 驅(qū)動(dòng)的靜態(tài)網(wǎng)站生成器
2. 亮點(diǎn)
3. 同類模塊橫向?qū)Ρ?/h5>
①. Nuxt:
- Nuxt: VuePress 能做的事情，Nuxt 理論上確實(shí)能夠勝任唧垦，但Nuxt 是為構(gòu)建應(yīng)用程序而生的
- VuePress: 專注在以內(nèi)容為中心的靜態(tài)網(wǎng)站上，同時(shí)提供了一些為技術(shù)文檔定制的開箱即用的特性
②. Docsify / Docute:
同樣都是基于 Vue液样，然而它們都是完全的運(yùn)行時(shí)驅(qū)動(dòng)振亮，因此對(duì) SEO 不夠友好
③. Hexo:
主題系統(tǒng)太過于靜態(tài)以及過度地依賴純字符串, 而不是基于Vue。同時(shí)鞭莽，Hexo 的 Markdown 渲染的配置也不是最靈活的
④. GitBook：
- 當(dāng)文件很多時(shí)坊秸，每次編輯后的重新加載時(shí)間長(zhǎng)得令人無法忍受
- 默認(rèn)主題導(dǎo)航結(jié)構(gòu)也比較有限制性
- 主題系統(tǒng)也不是 Vue 驅(qū)動(dòng)的
- GitBook 團(tuán)隊(duì)更專注于將其打造為一個(gè)商業(yè)產(chǎn)品而不是開源工具
二、成品展示
1. 技術(shù)文檔網(wǎng)站：
vue全家桶官網(wǎng)：vue澎怒、vuex褒搔、vue-cli、vue-router以及vuepress本身
2. 個(gè)人博客：
三星瘾、開始搭建
coding之前走孽，建議大家先了解markdown語法，為之后的文檔撰寫做鋪墊：傳送門
1. 全局安裝 VuePress
npm install -g vuepress
2. 創(chuàng)建并進(jìn)入項(xiàng)目
mkdir vuepress-demo && cd vuepress-demo
3. 初始化項(xiàng)目
npm init -y // 默認(rèn)配置yes
在生成的package.json中琳状，添加如下兩個(gè)啟動(dòng)命令：
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
}
4. 創(chuàng)建基本項(xiàng)目結(jié)構(gòu)
官方只有推薦目錄結(jié)構(gòu)磕瓷，并沒有現(xiàn)成的cli，所以需要通過命令行或手動(dòng)創(chuàng)建如下結(jié)構(gòu)：
vuepress-demo
├─package.json
├─docs
| ├─README.md
| ├─.vuepress
| | ├─config.js
| | ├─public
| | | └avatar.png
| | | └spider.png
其中有后綴的是文件念逞，沒后綴的是文件夾
5. 配置config.js
該文件為項(xiàng)目最重要的配置文件困食，幾乎所有配置項(xiàng)都是在此進(jìn)行。
我們先來一個(gè)最簡(jiǎn)單的配置看看效果：
module.exports = {
title: '南宮的博客',
head: [ // 注入到當(dāng)前頁面的 HTML <head> 中的標(biāo)簽
['link', { rel: 'icon', href: '/avatar.png' }], // 增加一個(gè)自定義的 favicon(網(wǎng)頁標(biāo)簽的圖標(biāo))
],
themeConfig: {
logo: '/avatar.png', // 左上角logo
nav:[ // 導(dǎo)航欄配置
{text: '首頁', link: '/' },
{text: '技術(shù)文檔', link: '/tech/interview/' },
{text: '簡(jiǎn)書主頁', link: 'http://www.reibang.com/u/c455567c7f50'}
],
sidebar: 'auto', // 側(cè)邊欄配置
}
};
想看詳細(xì)配置的同學(xué)可直接查詢官網(wǎng)-config配置翎承。
注意：路由根路徑為docs文件夾硕盹，靜態(tài)資源（圖片）根路徑為public文件夾
6. 啟動(dòng)項(xiàng)目
npm run dev
默認(rèn)服務(wù)啟動(dòng)在了http://localhost:8080/，效果如下：
我們配置的title叨咖、nav瘩例、sidebar、logo全都生效了芒澜！
恭喜仰剿，你完成了第一個(gè)極簡(jiǎn)版demo！
這里使用的官方默認(rèn)主題：
- 左上角的logo與title
- 右上角的全局搜索框與nav導(dǎo)航欄
- 左側(cè)的sidebar導(dǎo)航欄（自動(dòng)將md一級(jí)標(biāo)題設(shè)置為導(dǎo)航文案）
- 右側(cè)的markdown內(nèi)容
注意：項(xiàng)目自帶熱更新; 但config.js有時(shí)可能會(huì)熱更新失敗痴晦，需要重啟項(xiàng)目
7. 配置首頁（可選）：
一般的技術(shù)文檔網(wǎng)站都需要一個(gè)首頁作為該技術(shù)的簡(jiǎn)介南吮，個(gè)人博客也需要這樣的歡迎頁。vuepress提供了一個(gè)默認(rèn)格式的簡(jiǎn)潔首頁誊酌，需要在你的根級(jí)（docs下）README.md添加home: true部凑，格式如下：
---
home: true
heroImage: /spider.png
heroText: 我的主頁
tagline: My homepage
actionText: 技術(shù)文檔 →
actionLink: /tech/interview/
features:
- title: 簡(jiǎn)潔至上
details: 以 Markdown 為中心的項(xiàng)目結(jié)構(gòu)，以最少的配置幫助你專注于寫作碧浊。
- title: Vue驅(qū)動(dòng)
details: 享受 Vue + webpack 的開發(fā)體驗(yàn)涂邀，在 Markdown 中使用 Vue 組件，同時(shí)可以使用 Vue 來開發(fā)自定義主題箱锐。
- title: 高性能
details: VuePress 為每個(gè)頁面預(yù)渲染生成靜態(tài)的 HTML比勉，同時(shí)在頁面被加載的時(shí)候，將作為 SPA 運(yùn)行驹止。
footer: 南宮的個(gè)人博客
---
效果如下：
8. 變更主題（可選）
① 更換主題：
對(duì)默認(rèn)主題不滿意浩聋，想換個(gè)別的主題？安排臊恋！
在config.js中設(shè)置：
module.exports = {
theme: 'vuepress-theme-xx'
}
可以在npm中尋找自己喜歡的主題衣洁，其中以 @vuepress/theme- 開頭的主題是官方維護(hù)的主題：
② 開發(fā)主題：
npm上也沒有合適的主題？安排抖仅！
那咱們就自己開發(fā)一個(gè)主題坊夫，篇幅原因就不介紹細(xì)節(jié)了砖第，感興趣的同學(xué)可以自行查看官方文檔-開發(fā)主題
③ 修改默認(rèn)主題：
不想那么麻煩，但默認(rèn)主題又不滿足需求环凿？安排梧兼！
那就在默認(rèn)主題基礎(chǔ)上做一些修改，以滿足需求拷邢。
執(zhí)行如下命令袱院，可將默認(rèn)主題的各功能組件釋放出來：
vuepress eject docs
你會(huì)發(fā)現(xiàn)，在根目錄下瞭稼，多了一個(gè)theme文件夾忽洛，如下：
上圖列出了主要的布局組件，只需在其中做適量修改以滿足業(yè)務(wù)需求即可环肘。
9. md文件中使用vue組件（可選）
vuepress項(xiàng)目中的md文件欲虚，可以直接使用vue組件。
我們可以在.vuepress文件夾下新建一個(gè)components文件夾悔雹，其中的vue組件會(huì)自動(dòng)注冊(cè)到全局复哆，如下：
頁面效果如下：
10. 客戶端增強(qiáng)（可選）
如果你想對(duì)自己的應(yīng)用做一些優(yōu)化，比如使用router做登錄攔截腌零、給vue實(shí)例掛載全局變量或注冊(cè)其他組件等梯找，可以在.vuepress下新建文件enhanceApp.js：
export default ({
Vue, // VuePress 正在使用的 Vue 構(gòu)造函數(shù)
options, // 附加到根實(shí)例的一些選項(xiàng)
router, // 當(dāng)前應(yīng)用的路由實(shí)例
siteData // 站點(diǎn)元數(shù)據(jù)
}) => {
// ...做一些其他的應(yīng)用級(jí)別的優(yōu)化
}
這個(gè)文件類似于vue-cli腳手架中的main.js文件
四、部署上線
通過上面的工作益涧，我們已經(jīng)掌握了vuepress的基本用法锈锤，大家可以填充更多的md文件去豐富你的網(wǎng)頁。
但這些都還只是跑在本地闲询，想要所有人都能通過互聯(lián)網(wǎng)訪問你的網(wǎng)站久免，需要申請(qǐng)一個(gè)域名以及服務(wù)器，并將你的項(xiàng)目部署上去：
1. 選擇你的服務(wù)器
服務(wù)器有免費(fèi)和收費(fèi)兩種扭弧，各有優(yōu)劣：
① 免費(fèi)：
使用 Github Pages 阎姥。即 Github 提供的、用于搭建個(gè)人網(wǎng)站的靜態(tài)站點(diǎn)托管服務(wù)鸽捻。很多人用它搭建個(gè)人博客呼巴。這種方式的好處是免費(fèi)、方便御蒲，壞處是速度可能會(huì)有些慢衣赶、不能被國內(nèi)的搜索引擎收錄。
② 收費(fèi)：
國內(nèi)做的比較好的云服務(wù)有阿里云删咱、騰訊云，好處是速度有保證豪筝、可以被搜索引擎收錄痰滋，壞處是要花錢摘能，土豪請(qǐng)無視。
這里我們選擇方案①
2. github創(chuàng)建倉庫
① 登錄 github
② 新建倉庫一：username.github.io
（必須為你的github賬戶的username敲街，而不是昵稱啥的）
③ 新建倉庫二团搞，名稱隨意如vuepress-demo
二者的關(guān)系是：倉庫一負(fù)責(zé)顯示網(wǎng)站內(nèi)容，我們不需要改動(dòng)它多艇；日常開發(fā)和新增內(nèi)容逻恐，都在倉庫二中，并通過 npm run deploy 命令峻黍，將代碼發(fā)布到倉庫一
3. 關(guān)聯(lián)本地項(xiàng)目與github倉庫
// 先cd到你的demo
cd vuepress-demo
// git初始化
git init
// 關(guān)聯(lián)github倉庫
git remote add origin git@github.com:nan-gong/vuepress-demo.git
4. 新建部署文件
①根目錄下新建deploy.sh:
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯(cuò)誤
set -e
# 生成靜態(tài)文件
npm run build
# 進(jìn)入生成的文件夾
cd docs/.vuepress/dist
# 如果是發(fā)布到自定義域名
# echo 'www.yourwebsite.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果你想要部署到 https://USERNAME.github.io
git push -f git@github.com:nan-gong/nan-gong.github.io.git master
# 如果發(fā)布到 https://USERNAME.github.io/<REPO> REPO=github上的項(xiàng)目
# git push -f git@github.com:USERNAME/<REPO>.git master:gh-pages
cd -
② 根目錄新建README.md
此文件為你的項(xiàng)目描述或用法复隆，一般的git項(xiàng)目都會(huì)有此文件，和項(xiàng)目中的md文件無關(guān)姆涩。
5. git提交
git提交前挽拂，先確保你的本地登錄了git賬號(hào)，否則沒有權(quán)限提交到遠(yuǎn)端骨饿。
如果本地未登錄亏栈，可參考git初次登錄教程。
另外宏赘，可以在根目錄下添加.gitignore文件绒北，以防止不必要的提交：
// 提交到暫存區(qū)
git add .
// 提交到本地倉庫
git commit -m '基本搭建完畢'
// push到github倉庫
git push --set-upstream origin master
檢查你的github倉庫，發(fā)現(xiàn)已經(jīng)上傳成功：
6. 新建deploy指令并執(zhí)行
package.json 文件夾中添加發(fā)布命令：
"scripts": {
"deploy": "bash deploy.sh"
}
npm run deploy
7. 發(fā)布成功察署！
查看自己的博客域名：https://nan-gong.github.io/
這樣所有的人都能訪問到你的博客了闷游！
github源碼傳送門
8. PWA（可選）
PWA，即progressive web apps箕母，以web的形式給你原生app的體驗(yàn)储藐。
VuePress 默認(rèn)支持 PWA，配置方法如下：
① config.js添加配置：
head: [ // 注入到當(dāng)前頁面的 HTML <head> 中的標(biāo)簽
['link', { rel: 'manifest', href: '/photo.jpg' }],
['link', { rel: 'apple-touch-icon', href: '/photo.jpg' }],
],
serviceWorker: true // 是否開啟 PWA
② public 文件夾下新建 manifest.json 文件嘶是，添加：
{
"name": "南宮",
"short_name": "南宮",
"start_url": "index.html",
"display": "standalone",
"background_color": "#2196f3",
"description": "南宮的個(gè)人主頁",
"theme_color": "blue",
"icons": [
{
"src": "./avatar.png",
"sizes": "144x144",
"type": "image/png"
}
],
"related_applications": [
{
"platform": "web"
},
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=cheeaun.hackerweb"
}
]
}
③ 重新部署：npm run deploy
④ 移動(dòng)端操作：
