超詳細動手搭建一個Vuepress站點及開啓PWA與自動部署

五一以前就想寫一篇關於Vuepress的文章,結果朋友結婚就不了了之了。javascript

記得最後必定要看注意事項！css

Vuepress介紹

官網：https://vuepress.vuejs.org/html

相似hexo一個極簡的靜態網站生成器,用來寫技術文檔不能在爽。固然搭建成博客也不成問題。前端

Vuepress特色

響應式,也能夠自定義主題與hexo相似
內置markdown(還增長了一些擴展),而且能夠在其使用Vue組件
Google Analytics 集成
PWA 自動生成Service Worker

快速上手

安裝

初始化項目vue

yarn init -y
# 或者 npm init -y

安裝vuepressjava

yarn add -D vuepress
# 或者 npm install -D vuepress

全局安裝vuepresswebpack

yarn global add vuepress
# 或者 npm install -g vuepress

新建一個docs文件夾nginx

mkdir docs

設置下package.jsongit

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

寫做

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

也就是運行開發環境,直接去docs文件下書寫文章就能夠,打開http://localhost:8080/能夠預覽github

image

構建

build生成靜態的HTML文件,默認會在 .vuepress/dist 文件夾下

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

基本配置

在 .vuepress目錄下新建一個config.js,他導出一個對象

一些配置能夠參考官方文檔,這裏我配置經常使用及必須配置的

網站信息

module.exports = { title: '遊魂的文檔', description: 'Document library', head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], ], }

導航欄配置

module.exports = { themeConfig: { nav: [ { text: '主頁', link: '/' }, { text: '前端規範', link: '/frontEnd/' }, { text: '開發環境', link: '/development/' }, { text: '學習文檔', link: '/notes/' }, { text: '遊魂博客', link: 'https://www.iyouhun.com' }, // 下拉列表的配置 { text: 'Languages', items: [ { text: 'Chinese', link: '/language/chinese' }, { text: 'English', link: '/language/English' } ] } ] } }

如圖：

image

側邊欄配置

能夠省略.md擴展名,同時以 / 結尾的路徑將會被視爲 */README.md

module.exports = { themeConfig: { sidebar: { '/frontEnd/': genSidebarConfig('前端開發規範'), } } }

上面封裝的genSidebarConfig函數

function genSidebarConfig(title) { return [{ title, collapsable: false, children: [ '', 'html-standard', 'css-standard', 'js-standard', 'git-standard' ] }] }

支持側邊欄分組(能夠用來作博客文章分類) collapsable是當前分組是否展開

module.exports = { themeConfig: { sidebar: { '/note': [ { title:'前端', collapsable: true, children:[ '/notes/frontEnd/VueJS組件編碼規範', '/notes/frontEnd/vue-cli腳手架快速搭建項目', '/notes/frontEnd/深刻理解vue中的slot與slot-scope', '/notes/frontEnd/webpack入門', '/notes/frontEnd/PWA介紹及快速上手搭建一個PWA應用', ] }, { title:'後端', collapsable: true, children:[ 'notes/backEnd/nginx入門', 'notes/backEnd/CentOS如何掛載磁盤', ] }, ] } } }

如圖：

成品圖

默認主題修改

主題色修改

在.vuepress目錄下的建立一個override.styl文件

$accentColor = #3eaf7c // 主題色 $textColor = #2c3e50 // 文字顏色 $borderColor = #eaecef // 邊框顏色 $codeBgColor = #282c34 // 代碼背景顏色

自定義頁面類

有時須要在不一樣的頁面應用不一樣的css,能夠先在該頁面中聲明

--- pageClass: custom-page-class ---

而後在override.styl中書寫

.theme-container.custom-page-class { /* 特定頁面的 CSS */ }

PWA設置

設置serviceWorker爲true,而後提供Manifest 和 icons,能夠參考我以前的《PWA介紹及快速上手搭建一個PWA應用》

module.exports = { head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], //增長manifest.json ['link', { rel: 'manifest', href: '/manifest.json' }], ], serviceWorker: true, }

部署上線

設置基礎路徑

在config.js設置base
例如：你想要部署在https://foo.github.io 那麼設置base爲/,base默認就爲/,因此能夠不用設置
想要部署在https://foo.github.io/bar/,那麼 base 應該被設置成 "/bar/"

module.exports = { base: '/documents/', }

base 將會自動地做爲前綴插入到全部以 / 開始的其餘選項的連接中,因此你只須要指定一次。

構建與自動部署

用gitHub的pages或者coding的pages均可以,也能夠搭建在本身的服務器上。
將dist文件夾中的內容提交到git上或者上傳到服務器就好

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

另外能夠弄一個腳本,設置持續集成,在每次 push 代碼時自動運行腳本

deploy.sh

#!/usr/bin/env sh # 確保腳本拋出遇到的錯誤 set -e # 生成靜態文件 npm run docs:build # 進入生成的文件夾 cd docs/.vuepress/dist # 若是是發佈到自定義域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 若是發佈到 https://<USERNAME>.github.io # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master # 若是發佈到 https://<USERNAME>.github.io/<REPO> git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages cd -

注意事項(坑)

把你想引用的資源都放在.vuepress目錄下的public文件夾
給git倉庫綁定了獨立域名後,記得修改base路徑
設置側邊欄分組後默認會自動生成上/下一篇連接
設置了自動生成側邊欄會把側邊欄分組覆蓋掉
設置PWA記得開啓SSL