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

遊魂Andy發表於2019-03-04
Vue

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

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

更新：coding倉庫

Vuepress介紹

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

類似hexo一個極簡的靜態網站生成器,用來寫技術文件不能在爽。當然搭建成部落格也不成問題。

Vuepress特點

  • 響應式,也可以自定義主題與hexo類似
  • 內建markdown(還增加了一些擴充套件),並且可以在其使用Vue元件
  • Google Analytics 整合
  • PWA 自動生成Service Worker

快速上手

安裝

初始化專案

yarn init -y
# 或者 npm init -y
複製程式碼

安裝vuepress

yarn add -D vuepress
# 或者 npm install -D vuepress
複製程式碼

全域性安裝vuepress

yarn global add vuepress
# 或者 npm install -g vuepress
複製程式碼

新建一個docs資料夾

mkdir docs
複製程式碼

設定下package.json

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
複製程式碼

寫作

yarn docs:dev # 或者：npm run docs:dev
複製程式碼

也就是執行開發環境,直接去docs檔案下書寫文章就可以,開啟http://localhost:8080/可以預覽

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

構建

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' }
        ]
      }
    ]
  }
}
複製程式碼

如圖：

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

側邊欄配置

可以省略.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

相關文章