vuepress搭建技術文檔實戰（帶github項目地址）

本文主要講解的是用vuepress搭建一個技術文檔，且這個技術文檔是與github pages 相關聯的。就是咱們常見的下圖的這種：

最終效果以下圖：

若是與你想要作的同樣，請仔細閱讀下面的內容。

重要提示

本文不會重複介紹官方文檔的內容，官網的API已經寫得很詳細而且寫得很好了。因此，請先按照官網的講解一步步實踐，若是遇到其餘的問題，這篇文章的內容也許可以幫到你。去官網

背景

一開始我並非想直接搭建一個技術文檔，咱們團隊是先開發了一套快應用UI組件庫Quist-UI，爲了方便開發者閱讀，最後決定用vuepress搭建。因此，我用的安裝方式和官網介紹的現有項目安裝是一致的。

個人項目一開始就是快應用的一個項目架構，webpack的版本是3.12.0。

開始

在用現有項目安裝時，我遇到了一個怪異的問題，執行npx vuepress dev docs的命令時，老是報錯。若是你也遇到了，試試全局安裝yarn global add vuepress或npm install -g vuepress。

目錄結構

有兩點要特殊說明一下，當時我在配置的時候也費了點時間。

1. 首頁的圖片(在這裏就是白色鴿子的那張圖)

打開docs文件夾下的README.md文件，參考官網說明。

heroImage: /quistUI.png
複製代碼

這個配置，須要在.vuepress文件夾下新建一個public文件夾，把圖片放在這裏，這樣在打包的時候會自動打包。

2. 瀏覽器左側的小圖標

須要在config.js文件裏進行配置，參考官網說明。 在個人項目裏，和官網有一點點差異，href後的/。

#個人項目
head: [
    ['link', { rel: 'icon', href: 'favicon.ico' }]
]
#官網
head: [
    ['link', { rel: 'icon', href: '/logo.png' }]
]
複製代碼

這兩張圖片都須要放在public文件夾下~

首頁上部導航

參考官網說明。

左側導航

參考官網說明。

到這裏，你的技術文檔應該已經在本地能夠瀏覽了，最後一步，部署。

部署

參考官網說明。

上面說過，個人項目是部署github上的，因此，這裏只說github的部署方式，且只說和官網哪些地方是不一樣的。

部署分爲兩步：

1. 在項目根目錄下建立deploy.sh文件，與package.json是同級的。

#!/usr/bin/env sh 
# 確保腳本拋出遇到的錯誤
set -e

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

# 進入生成的文件夾
cd docs/.vuepress/dist
# git init 官網是有這行的，但個人項目裏給註釋掉了，由於我是現有項目，不想每次都初始化

# 下面這行是官網沒有的，若是是多人開發項目，務必執行此命令
git pull https://github.com/JDsecretFE/quist-ui.git master 
git add -A
git commit -m 'deploy'
git push -f https://github.com/JDsecretFE/quist-ui.git master:gh-pages

cd -
複製代碼

打開package.json文件，添加scripts的命令,以下圖：

"deploy": "bash deploy.sh"
複製代碼

2. 登陸github,找到settings->GitHub Pages，選擇gh-pages分支，保存。

如今咱們打開命令工具，查看咱們的分支，應該有一個master分支和gh-pages分支(若是沒有gh-pages分支，自行建立一個)。咱們在master分支上執行 npm run deploy命令，這時docs/.vuepress下會多出一個dist文件夾，咱們要的東西都在這裏了。

最後，咱們把master分支下dist文件夾裏的內容拷貝到gh-pages分支，完成。

若是你有更好的方式，也請回復我一下，感謝感謝。

最後附上項目地址，請參考此項目下的docs項目結構。若是幫助到你，請給個star鼓勵一下~~~