作者: 南宮__
https://www.jianshu.com/p/37509da5a020
前言
只聽過vue，沒聽過vuepress？它可是新的vue全家桶成員之一，尤雨溪大神推出的一款好用的模板。
不信？請看Evan You github。star數已過萬，並不少。
vuepress用於迅速搭建技術文檔網站與個人博客，簡單快捷，下面和我一起開始學習吧！
（想直接coding的同學可從第三節開始）
一、模塊概述
1. 定義
Vue 驅動的靜態網站生成器
2. 亮點
自己總結的vuepress優點
3. 同類模塊橫向對比
①. Nuxt:
Nuxt: VuePress 能做的事情，Nuxt 理論上確實能夠勝任，但Nuxt 是爲構建應用程序而生的
VuePress: 專注在以內容爲中心的靜態網站上，同時提供了一些爲技術文檔定製的開箱即用的特性
②. Docsify / Docute:
同樣都是基於 Vue，然而它們都是完全的運行時驅動，因此對 SEO 不夠友好
③. Hexo:
主題系統太過於靜態以及過度地依賴純字符串, 而不是基於Vue。同時，Hexo 的 Markdown 渲染的配置也不是最靈活的
④. GitBook：
當文件很多時，每次編輯後的重新加載時間長得令人無法忍受
默認主題導航結構也比較有限制性
主題系統也不是 Vue 驅動的
GitBook 團隊更專注於將其打造爲一個商業產品而不是開源工具
二、成品展示
1. 技術文檔網站：
vue全家桶官網：vue、vuex、vue-cli、vue-router以及vuepress本身
2. 個人博客：
博客1（默認主題）、博客2（自定義主題）
三、開始搭建
coding之前，建議大家先了解markdown語法，爲之後的文檔撰寫做鋪墊：傳送門
1. 全局安裝 VuePress
npm install \-g vuepress
2. 創建並進入項目
mkdir vuepress-demo && cd vuepress-demo
3. 初始化項目
npm init \-y // 默認配置yes
在生成的package.json中，添加如下兩個啓動命令：
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
}
4. 創建基本項目結構
官方只有推薦目錄結構，並沒有現成的cli，所以需要通過命令行或手動創建如下結構：
vuepress-demo
├─package.json
├─docs
| ├─README.md
| ├─.vuepress
| | ├─config.js
| | ├─public
| | | └avatar.png
| | | └spider.png
其中有後綴的是文件，沒後綴的是文件夾
5. 配置config.js
該文件爲項目最重要的配置文件，幾乎所有配置項都是在此進行。
我們先來一個最簡單的配置看看效果：
module.exports = {
title: '南宮的博客',
head: [ // 注入到當前頁面的 HTML <head> 中的標籤
['link', { rel: 'icon', href: '/avatar.png' }], // 增加一個自定義的 favicon(網頁標籤的圖標)
],
themeConfig: {
logo: '/avatar.png', // 左上角logo
nav:[ // 導航欄配置
{text: '首頁', link: '/' },
{text: '技術文檔', link: '/tech/interview/' },
{text: '簡書主頁', link: 'https://www.jianshu.com/u/c455567c7f50'}
],
sidebar: 'auto', // 側邊欄配置
}
};
想看詳細配置的同學可直接查詢官網-config配置。
注意：路由根路徑爲docs文件夾，靜態資源（圖片）根路徑爲public文件夾
6. 啓動項目
npm run dev
默認服務啓動在了http://localhost:8080/，效果如下：
demo第一版
我們配置的title、nav、sidebar、logo全都生效了！
恭喜，你完成了第一個極簡版demo！
這裏使用的官方默認主題：
左上角的logo與title
右上角的全局搜索框與nav導航欄
左側的sidebar導航欄（自動將md一級標題設置爲導航文案）
右側的markdown內容
注意：項目自帶熱更新; 但config.js有時可能會熱更新失敗，需要重啓項目
7. 配置首頁（可選）：
一般的技術文檔網站都需要一個首頁作爲該技術的簡介，個人博客也需要這樣的歡迎頁。vuepress提供了一個默認格式的簡潔首頁，需要在你的根級（docs下）README.md添加home: true，格式如下：
---
home: true
heroImage: /spider.png
heroText: 我的主頁
tagline: My homepage
actionText: 技術文檔 →
actionLink: /tech/interview/
features:
- title: 簡潔至上
details: 以 Markdown 爲中心的項目結構，以最少的配置幫助你專注於寫作。
- title: Vue驅動
details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 組件，同時可以使用 Vue 來開發自定義主題。
- title: 高性能
details: VuePress 爲每個頁面預渲染生成靜態的 HTML，同時在頁面被加載的時候，將作爲 SPA 運行。
footer: 南宮的個人博客
---
效果如下：
8. 變更主題（可選）
① 更換主題：
對默認主題不滿意，想換個別的主題？安排！
在config.js中設置：
module.exports = {
theme: 'vuepress-theme-xx'
}
可以在npm中尋找自己喜歡的主題，其中以 @vuepress/theme- 開頭的主題是官方維護的主題：
② 開發主題：
npm上也沒有合適的主題？安排！
那咱們就自己開發一個主題，篇幅原因就不介紹細節了，感興趣的同學可以自行查看官方文檔-開發主題
③ 修改默認主題：
不想那麼麻煩，但默認主題又不滿足需求？安排！
那就在默認主題基礎上做一些修改，以滿足需求。
執行如下命令，可將默認主題的各功能組件釋放出來：vuepress eject docs
你會發現，在根目錄下，多了一個theme文件夾，如下：
上圖列出了主要的佈局組件，只需在其中做適量修改以滿足業務需求即可。
9. md文件中使用vue組件（可選）
vuepress項目中的md文件，可以直接使用vue組件。
我們可以在.vuepress文件夾下新建一個components文件夾，其中的vue組件會自動註冊到全局，如下：
頁面效果如下：
10. 客戶端增強（可選）
如果你想對自己的應用做一些優化，比如使用router做登錄攔截、給vue實例掛載全局變量或註冊其他組件等，可以在.vuepress下新建文件enhanceApp.js：
export default ({
Vue, // VuePress 正在使用的 Vue 構造函數
options, // 附加到根實例的一些選項
router, // 當前應用的路由實例
siteData // 站點元數據
}) => {
// ...做一些其他的應用級別的優化
}
這個文件類似於vue-cli腳手架中的main.js文件
四、部署上線
通過上面的工作，我們已經掌握了vuepress的基本用法，大家可以填充更多的md文件去豐富你的網頁。
但這些都還只是跑在本地，想要所有人都能通過互聯網訪問你的網站，需要申請一個域名以及服務器，並將你的項目部署上去：
1. 選擇你的服務器
服務器有免費和收費兩種，各有優劣：
① 免費：
使用 Github Pages 。即 Github 提供的、用於搭建個人網站的靜態站點託管服務。很多人用它搭建個人博客。這種方式的好處是免費、方便，壞處是速度可能會有些慢、不能被國內的搜索引擎收錄。
② 收費：
國內做的比較好的雲服務有阿里雲、騰訊雲，好處是速度有保證、可以被搜索引擎收錄，壞處是要花錢，土豪請無視。
這裏我們選擇方案①
2. github創建倉庫
① 登錄 github
② 新建倉庫一：username.github.io
（必須爲你的github賬戶的username，而不是暱稱啥的）
③ 新建倉庫二，名稱隨意如vuepress-demo
二者的關係是：倉庫一負責顯示網站內容，我們不需要改動它；日常開發和新增內容，都在倉庫二中，並通過 npm run deploy 命令，將代碼發佈到倉庫一
3. 關聯本地項目與github倉庫
// 先cd到你的demo
cd vuepress-demo
// git初始化
git init
// 關聯github倉庫
git remote add origin [email protected]:nan-gong/vuepress-demo.git
4. 新建部署文件
①根目錄下新建deploy.sh:
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯誤
set -e
# 生成靜態文件
npm run build
# 進入生成的文件夾
cd docs/.vuepress/dist
# 如果是發佈到自定義域名
# echo 'www.yourwebsite.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果你想要部署到 https://USERNAME.github.io
git push -f [email protected]:nan-gong/nan-gong.github.io.git master
# 如果發佈到 https://USERNAME.github.io/<REPO> REPO=github上的項目
# git push -f [email protected]:USERNAME/<REPO>.git master:gh-pages
cd -
② 根目錄新建README.md
此文件爲你的項目描述或用法，一般的git項目都會有此文件，和項目中的md文件無關。
5. git提交
git提交前，先確保你的本地登錄了git賬號，否則沒有權限提交到遠端。
如果本地未登錄，可參考git初次登錄教程。
另外，可以在根目錄下添加.gitignore文件，以防止不必要的提交：
// 提交到暫存區
git add .
// 提交到本地倉庫
git commit -m '基本搭建完畢'
// push到github倉庫
git push --set-upstream origin master
檢查你的github倉庫，發現已經上傳成功：
6. 新建deploy指令並執行
package.json 文件夾中添加發布命令：
"scripts": {
"deploy": "bash deploy.sh"
}
npm run deploy
7. 發佈成功！
查看自己的博客域名：https://nan-gong.github.io/
這樣所有的人都能訪問到你的博客了！
8. PWA（可選）
PWA，即progressive web apps，以web的形式給你原生app的體驗。
VuePress 默認支持 PWA，配置方法如下：
① config.js添加配置：
head: [ // 注入到當前頁面的 HTML <head> 中的標籤
['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": "南宮的個人主頁",
"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
④ 移動端操作：
