拯救懶癌文檔君 - VuePress + Travis CI + Github Pages 自動線上生成文檔

做者：codexu

_

總體思路

1.Github 建立項目，本地建立切換到 docs 分支，經過 VuePress 構建文檔項目（寫一些文檔），上傳至 Github。

2.Travis CI 自動 clone 後安裝依賴、編譯、上傳至 Github master 分支。

3.經過 GitHub Pages 功能將 master 分支上的內容展現在 web 上。

相關資料：

• 個人文檔看下效果：https://codexu.github.io/
• 個人文檔遠嗎：https://github.com/codexu/codexu.github.io
• VuePress中文文檔(1.x)：https://v1.vuepress.vuejs.org/zh/
• Travis CI：https://travis-ci.org

建立項目

1.使用 VuePress 初始化項目，只說幾點，文檔寫的十分詳細。

• 依賴安裝在 devDependencies。
• package.json script 寫運行和打包腳本，"serve": "vuepress dev docs"，"build": "vuepress build docs"。（這裏按照本身習慣，後面作持續集成要用）
• 建立 docs 文件夾，把全部 markdown 文檔存放在這裏。
• docs/.vuepress/config.js 能夠作大量配置。

2.使用 Github 建立項目 [name].github.io，例如個人文檔是 codexu.github.io，關聯到本地。

爲何用 [name].github.io ？

由於在這個項目下，能夠直接使用 https://[name].github.io/ 域名，短小精悍～

3.經過 git checkout -b docs 切換到 docs 分支，docs 分支存放文檔源碼，master 分支存放打包好的 HTML 等文件。

爲何使用 master 分支存放打包後的文件？

由於在 [name].github.io 項目下沒得選，你也能夠換個其餘倉庫，就能夠避免這個問題。

4.寫一些文檔，作一下簡單的配置，先別急着提交到 Github。

經過 Travis CI 作自動化打包及部署

1.在根目錄下建立 .travis.yml 文件，並寫入一些內容：

language: node_js
node_js:
    - 10
cache: yarn
install:
    - yarn
script:
    - yarn build
after_success:
    - cd docs/.vuepress/dist
    - git init
    - git config --global user.name "${U_NAME}"
    - git config --global user.email "${U_EMAIL}"
    - git add -A
    - git commit -m 'deploy'
    - git push --quiet --force "https://${GH_TOKEN}@${GH_REF}" master:${P_BRANCH}

• language: 語言選擇 node_js，咱們前端還有的選嗎？
• node_js: node版本，這塊也許是越高越快？
• cache: yarn 緩存，能使你構建速度更快...吧。
• install: 安裝依賴的包管理工具，使用 yarn 比 npm 快的多。
• script: 一切就緒以後經過 yarn install 安裝依賴。
• after_success: 安裝結束後，咱們作一些打包和 push 到 Github 的指令。
• 環境變量 "${***}" 這塊後面會提到。

2.這時候能夠 push 到 Github 了，由於沒有 .travis.yml Travis CI 是不會理你的項目的，同時將默認分支改成 docs。

3.Github 增長一個 Personal access tokens，位置在 Settings / Developer settings。

• Note 隨意填，填 travis-ci 就行。
• 除了 delete_repo 權限都打勾就行。

4.進入 Travis CI，使用 Github 登錄， 進入 dashboard，此時應該能夠看到你剛建立的項目。

5.啓動進入這個項目，右上角 More options 點擊 setting，配置環境變量。

• GH_REF: 項目地址（github.com/[name]/[name].github.io.git）注意去掉 https://。
• GH_TOKEN: tocken 是經過上面第三部拿到的。
• P_BRANCH: 要上傳的分支，這裏咱們要傳到 master。
• U_EMAIL: 你的 Github 郵箱。
• U_NAME: 你的 Github 用戶名。

開啓 GitHub Pages