創(chuàng)建 VuePress + GithubPages + TravisCI 在線文檔

[TOC]

最新博客鏈接

VuePress 在線文檔鏈接_Github Pages

VuePress 在線文檔鏈接_博客服務(wù)器（如果上面進(jìn)不去，可以進(jìn)這個，服務(wù)器在阿里云）

Github鏈接

最終效果

最終效果鏈接

思路

總體

VuePress 在本地完成項目的源文件，推送至 Github 觸發(fā) Travis CI 自動構(gòu)建目標(biāo)文件，完成后自動部署到另一個 Github 分支，此分支作在線文檔使用。

在Github上創(chuàng)建兩個分支master和gh-pages，master用于上傳源文件和觸發(fā) Travis CI 自動執(zhí)行構(gòu)建、部署腳本，gh-pages用于保存 Github Pages 的最終頁面。

完成上述操作之后就只需修改文本源文件Markdown里面的內(nèi)容，推送到Github。Travis CI 便可自動構(gòu)建、部署，使其工作流程簡化。

過程

  1. 在本地創(chuàng)建配置 VuePress 工程上傳到master分支
  2. 上傳成功后觸發(fā) TravisCI 開始自動構(gòu)建
  3. 構(gòu)建完成后將最終頁面推送到gh-pages分支

用到的東西

  • SSH密鑰鏈接Github
  • VuePress目錄文件結(jié)構(gòu)
  • VuePress配置文件
  • TravisCI自動構(gòu)建配置文件

相關(guān)

  • VuePress:

    每一個由 VuePress 生成的頁面都帶有預(yù)渲染好的 HTML，也因此具有非常好的加載性能和搜索引擎優(yōu)化（SEO）。同時，一旦頁面被加載，Vue 將接管這些靜態(tài)內(nèi)容，并將其轉(zhuǎn)換成一個完整的單頁應(yīng)用（SPA），其他的頁面則會只在用戶瀏覽到的時候才按需加載。

  • GitHub Pages:

    您可以使用 GitHub Pages 直接從 GitHub 倉庫托管關(guān)于自己、您的組織或您的項目的站點

    GitHub Pages 是一項靜態(tài)站點托管服務(wù)，它直接從 GitHub 上的倉庫獲取 HTML、CSS 和 JavaScript 文件，（可選）通過構(gòu)建過程運行文件，然后發(fā)布網(wǎng)站。

  • Travis CI

    Travis CI 提供的是持續(xù)集成服務(wù)（Continuous Integration，簡稱 CI）。它綁定 Github 上面的項目，只要有新的代碼，就會自動抓取。然后，提供一個運行環(huán)境，執(zhí)行測試，完成構(gòu)建，還能部署到服務(wù)器。

    持續(xù)集成指的是只要代碼有變更，就自動運行構(gòu)建和測試，反饋運行結(jié)果。確保符合預(yù)期以后，再將新代碼"集成"到主干。

    持續(xù)集成的好處在于，每次代碼的小幅變更，就能看到運行結(jié)果，從而不斷累積小的變更，而不是在開發(fā)周期結(jié)束時，一下子合并一大塊代碼。

創(chuàng)建Github倉庫

創(chuàng)建Github倉庫

在Github官網(wǎng)上創(chuàng)建一個新的倉庫（我倉庫的名字叫VuePress-GithubPages-TravisCI）

SSH密鑰鏈接Github

生成SSH密鑰
$ ssh-keygen
Generating public/private rsa key pair.
# 輸入準(zhǔn)備存放密鑰的位置，公鑰和私鑰放在同一個文件夾
Enter file in which to save the key (/home/tsanfer/.ssh/id_rsa): /home/tsanfer/.ssh/test_key
# 輸入口令，不需要口令就直接回車，這里我不需要口令，直接回車
Enter passphrase (empty for no passphrase):
# 確認(rèn)口令，跟上面一樣
Enter same passphrase again:
# 顯示私鑰位置
Your identification has been saved in /home/tsanfer/.ssh/test_key.
# 顯示公鑰位置，下一步需要添加公鑰到Github中
Your public key has been saved in /home/tsanfer/.ssh/test_key.pub.
Github添加SSH密鑰

在Github頭像旁邊的菜單中 Settings --> SSH and GPG keys --> SSH keys 中的右上角點擊 New SSH key

下面要填入信息：

  • Title：隨便填
  • Key：公鑰文件里的所有內(nèi)容（~/.ssh/test_key.pub）
測試SSH密鑰

測試一下密鑰

ssh -T git@github.com

設(shè)置Github賬號的地址

git config --global user.name "username"
git config --global user.email "useremail"

# 比如
git config --global user.name "Tsanfer"
git config --global user.email "a1124851454@gmail.com"

如果成功的話

Hi Tsanfer! You've successfully authenticated, but GitHub does not provide shell access.

用SSH的方式克隆倉庫到本地

# 選一個文件夾克隆倉庫
# 比如家目錄
cd ~
git clone git@github.com:{Username}/{Repo}.git

# 比如
# cd ~
# git clone git@github.com:Tsanfer/VuePress-GithubPages-TravisCI.git

# 克隆完之后的目錄
~/VuePress-GithubPages-TravisCI/

配置VuePress

安裝VuePress

請確保你的 Node.js 版本 >= 8。

安裝yarn

也可以安裝npm

Debian / Ubuntu

在 Debian 或 Ubuntu 上，需要用yarn的 Debian 包倉庫來安裝 Yarn。 首先需要配置倉庫：

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

更新庫和下載yarn

sudo apt-get update && sudo apt-get install yarn

運行命令來測試 Yarn 是否安裝：

$ yarn --version
1.22.4
Windows

直接下安裝包，然后在CMD或者Powershell里運行

更換國內(nèi)的源

先看一下當(dāng)前的源

$ yarn config get registry
https://registry.yarnpkg.com

更換阿里淘寶的源

yarn config set registry https://registry.npm.taobao.org

安裝VuePress

# 先進(jìn)入安裝目錄，就是剛剛克隆的倉庫
cd ~/VuePress-GithubPages-TravisCI
# 安裝
sudo yarn global add vuepress # 或者：npm install -g vuepress

然后試一下看是否安裝成功

# 新建一個 markdown 文件
echo '# Hello VuePress!' > README.md

# 開始寫作
vuepress dev .

? ?wds?: Project is running at http://0.0.0.0:8081/
? ?wds?: webpack output is served from /
? ?wds?: Content not from webpack is served from /mnt/k/Git_Bash/VuePress-GithubPages-TravisCI/.vuepress/public
? ?wds?: 404s will fallback to /index.html
success [00:00:17] Build 471ee0 finished in 8465 ms!
> VuePress dev server listening at http://localhost:8081/

# 生成的地址 http://localhost:8081/

用瀏覽器打開vuepress生成的網(wǎng)頁的地址

或者構(gòu)建靜態(tài)文件

# 構(gòu)建靜態(tài)文件
vuepress build .

但會因為路徑不對，網(wǎng)頁的樣式顯示不出來

VuePress目錄結(jié)構(gòu)

官方給的結(jié)構(gòu)

VuePress 遵循 “約定優(yōu)于配置” 的原則，推薦的目錄結(jié)構(gòu)如下：

.
├── docs
│   ├── .vuepress (可選的)
│   │   ├── components (可選的)
│   │   ├── theme (可選的)
│   │   │   └── Layout.vue
│   │   ├── public (可選的)
│   │   ├── styles (可選的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可選的, 謹(jǐn)慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可選的)
│   │   └── enhanceApp.js (可選的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

這里用到的結(jié)構(gòu)

.
├── README.md     // Github項目展示文件
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心內(nèi)容的文件夾
│   │   ├── public     //存放靜態(tài)文件，如圖片等
│   │   └── config.js     //設(shè)定頂部導(dǎo)航欄、側(cè)邊導(dǎo)航欄等項目配置的核心文件
│   ├── pages      //存放markdown頁面的文件
│   ├── README.md     //vuepress首頁展示用的markdown文件
├── deploy.sh     //用于編寫TravisCI上傳、發(fā)布的腳本文件
├── LISENSE     //許可證文件
├── package.json     //Node.js項目描述文件
└── .travis.yml //Travis CI 自動部署文件

配置依賴和腳本

配置package.json

在 package.json 里加一些腳本和后面要用的依賴:

{
  "dependencies": {
    "@vuepress/plugin-active-header-links": "^1.3.1",
    "@vuepress/plugin-medium-zoom": "^1.3.1",
    "@vuepress/plugin-nprogress": "^1.3.1",
    "@vuepress/plugin-back-to-top": "^1.3.1",
    "vuepress": "^1.3.1"
  },
  "scripts": {
    "docs:build": "vuepress build docs",
    "docs:dev": "vuepress dev docs"
  }
}

加載依賴

yarn

命令

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

頁面的設(shè)置

首頁

/docs/README.md

---
home: true
heroImage: https://cdn.tsanfer.com/image/vuepress_githubpages_travisCI.svg
actionText: 快速上手 →
actionLink: /pages/思路.md
features:
- title: 簡潔至上
  details: 以 Markdown 為中心的項目結(jié)構(gòu)，以最少的配置幫助你專注于寫作。
- title: Vue驅(qū)動
  details: 享受 Vue + webpack 的開發(fā)體驗，在 Markdown 中使用 Vue 組件，同時可以使用 Vue 來開發(fā)自定義主題。
- title: 高性能
  details: VuePress 為每個頁面預(yù)渲染生成靜態(tài)的 HTML，同時在頁面被加載的時候，將作為 SPA 運行。
footer: MIT Licensed | Copyright ? 2020 Tsanfer
---

文檔屬性

/docs/.vuepress/config.js

module.exports = {
    base: '/VuePress-GithubPages-TravisCI/',    //目錄根地址，應(yīng)與Github倉庫名字相同
    title: 'VuePress + GithubPages + TravisCI',    // 顯示在左上角的網(wǎng)頁名稱以及首頁在瀏覽器標(biāo)簽顯示的title名稱
    description: '創(chuàng)建 VuePress + GithubPages + TravisCI 在線文檔',    // meta 中的描述文字，用于SEO
    head: [
        ['link', 
            { rel: 'icon', href: '/gamepad_game_128px.ico' }   //瀏覽器的標(biāo)簽欄的網(wǎng)頁圖標(biāo),基地址/docs/.vuepress/public
        ],  
    ],
}

markdown擴(kuò)展

/docs/.vuepress/config.js

module.exports = {
    markdown: {
        lineNumbers: true,  //是否在每個代碼塊的左側(cè)顯示行號
    },
}

默認(rèn)主題設(shè)置

導(dǎo)航欄

/docs/.vuepress/config.js

module.exports = {
    themeConfig: {
        nav: [
            //鏈接頁面鏈接的根地址為/docs
            { text: '思路', link: '/pages/思路.md' },
            { text: '創(chuàng)建Github倉庫', link: '/pages/創(chuàng)建Github倉庫.md' },
            { text: '配置VuePress', link: '/pages/配置VuePress.md' },
            { text: '創(chuàng)建分支和Github pages', link: '/pages/創(chuàng)建分支和Github pages.md' },
            { text: 'TravisCI生成和發(fā)布', link: '/pages/TravisCI生成和發(fā)布.md' },
            { text: '博客', link: 'https://tsanfer.com' },
        ],
    },
}
側(cè)邊欄

/docs/.vuepress/config.js

module.exports = {
    themeConfig: {
        sidebarDepth: 2,    //側(cè)邊欄深度
        sidebar: [
            ['/pages/思路.md', '思路'],
            ['/pages/創(chuàng)建Github倉庫.md', '創(chuàng)建Github倉庫'],
            ['/pages/配置VuePress.md', '配置VuePress'],
            ['/pages/創(chuàng)建分支和Github pages.md', '創(chuàng)建分支和Github pages'],
            ['/pages/TravisCI生成和發(fā)布.md', 'TravisCI生成和發(fā)布'],
        ],
    },
}
Git倉庫

/docs/.vuepress/config.js

module.exports = {
     themeConfig: {
        // 假定是 GitHub. 同時也可以是一個完整的 GitLab URL
        repo: 'Tsanfer/VuePress-GithubPages-TravisCI',
        // 自定義倉庫鏈接文字。默認(rèn)從 `themeConfig.repo` 中自動推斷為
        // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
        repoLabel: 'Github',
        // 以下為可選的編輯鏈接選項
        // 假如文檔不是放在倉庫的根目錄下：
        docsDir: 'docs/pages',
        // 假如文檔放在一個特定的分支下：
        docsBranch: 'master',
        // 默認(rèn)是 false, 設(shè)置為 true 來啟用
        editLinks: true,
        // 默認(rèn)為 "Edit this page"
        editLinkText: '在 Github 上編輯此頁', 
    },
}
其他

/docs/.vuepress/config.js

module.exports = {
     themeConfig: {
        smoothScroll: true, //頁面滾動效果
        lastUpdated: '最后更新', // string | boolean
     },
}

插件

/docs/.vuepress/config.js

module.exports = {
    plugins: [
        '@vuepress/medium-zoom',    //zooming images like Medium（頁面彈框居中顯示）
        '@vuepress/nprogress',  //網(wǎng)頁加載進(jìn)度條
        '@vuepress/plugin-back-to-top', //返回頁面頂部按鈕
    ]
}

到這里其實已經(jīng)完成配置了，可以執(zhí)行 yarn docs:dev 來瀏覽配置的頁面，只是由于沒有對應(yīng)的 md 文件，打開的鏈接都會404

config.js所有內(nèi)容

module.exports = {
    base: '/VuePress-GithubPages-TravisCI/',    //目錄根地址，應(yīng)與Github倉庫名字相同
    title: 'VuePress + GithubPages + TravisCI',    // 顯示在左上角的網(wǎng)頁名稱以及首頁在瀏覽器標(biāo)簽顯示的title名稱
    description: '創(chuàng)建 VuePress + GithubPages + TravisCI 在線文檔',    // meta 中的描述文字，用于SEO
    head: [
        ['link', 
            { rel: 'icon', href: '/gamepad_game_128px.ico' }   //瀏覽器的標(biāo)簽欄的網(wǎng)頁圖標(biāo),基地址/docs/.vuepress/public
        ],  
    ],

    //markdown擴(kuò)展
    markdown: {
        lineNumbers: true,  //是否在每個代碼塊的左側(cè)顯示行號
    },

    //默認(rèn)主題配置
    themeConfig: {
        //導(dǎo)航欄
        nav: [
            //鏈接頁面鏈接的根地址為/docs
            { text: '思路', link: '/pages/思路.md' },
            { text: '創(chuàng)建Github倉庫', link: '/pages/創(chuàng)建Github倉庫.md' },
            { text: '配置VuePress', link: '/pages/配置VuePress.md' },
            { text: 'TravisCI生成和發(fā)布', link: '/pages/TravisCI生成和發(fā)布.md' },
            { text: '博客', link: 'https://tsanfer.com' },
        ],
        sidebarDepth: 2,    //側(cè)邊欄深度
        //側(cè)邊欄
        sidebar: [
            ['/pages/思路.md', '思路'],
            ['/pages/創(chuàng)建Github倉庫.md', '創(chuàng)建Github倉庫'],
            ['/pages/配置VuePress.md', '配置VuePress'],
            ['/pages/TravisCI生成和發(fā)布.md', 'TravisCI生成和發(fā)布'],
        ],

        // 假定是 GitHub. 同時也可以是一個完整的 GitLab URL
        repo: 'Tsanfer/VuePress-GithubPages-TravisCI',
        // 自定義倉庫鏈接文字。默認(rèn)從 `themeConfig.repo` 中自動推斷為
        // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
        repoLabel: 'Github',
        // 以下為可選的編輯鏈接選項
        // 假如文檔不是放在倉庫的根目錄下：
        docsDir: 'docs/pages',
        // 假如文檔放在一個特定的分支下：
        docsBranch: 'master',
        // 默認(rèn)是 false, 設(shè)置為 true 來啟用
        editLinks: true,
        // 默認(rèn)為 "Edit this page"
        editLinkText: '在 Github 上編輯此頁',

        smoothScroll: true, //頁面滾動效果
        lastUpdated: '最后更新', // string | boolean
    },

    //插件
    plugins: [
        '@vuepress/medium-zoom',    //zooming images like Medium（頁面彈框居中顯示）
        '@vuepress/nprogress',  //網(wǎng)頁加載進(jìn)度條
        '@vuepress/plugin-back-to-top', //返回頁面頂部按鈕
    ]
}

TravisCI生成和發(fā)布

創(chuàng)建gh-pages分支

這時Github已經(jīng)自動部署gh-pages分支為Github pages的生成源

deploy.sh部署文件

每當(dāng) Github 倉庫更新時，會觸發(fā) Travis CI 執(zhí)行 deploy.sh 腳本

創(chuàng)建一個如下的 deploy.sh 文件（請自行判斷去掉高亮行的注釋）:

在項目根目錄下創(chuàng)建

.
├── README.md     // Github項目展示文件
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心內(nèi)容的文件夾
│   │   ├── public     //存放靜態(tài)文件，如圖片等
│   │   └── config.js     //設(shè)定頂部導(dǎo)航欄、側(cè)邊導(dǎo)航欄等項目配置的核心文件
│   ├── pages      //存放markdown頁面的文件
│   ├── README.md     //vuepress首頁展示用的markdown文件
├── deploy.sh     //用于編寫TravisCI上傳、發(fā)布的腳本文件
├── LISENSE     //許可證文件
├── package.json     //Node.js項目描述文件
└── .travis.yml //Travis CI 自動部署文件

#!/usr/bin/env sh

# 確保腳本拋出遇到的錯誤
set -e

# 生成靜態(tài)文件
yarn docs:build

# 進(jìn)入生成的文件夾
cd docs/.vuepress/dist

# 如果是發(fā)布到自定義域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果發(fā)布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果發(fā)布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
# 比如
# git push -f git@github.com:Tsanfer/VuePress-GithubPages-TravisCI.git master:gh-pages

cd -

上面的 git 地址其實就是倉庫的SSH地址

Travis CI 部署文件

在項目的根目錄創(chuàng)建一個名為 .travis.yml 的文件

.
├── README.md     // Github項目展示文件
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心內(nèi)容的文件夾
│   │   ├── public     //存放靜態(tài)文件，如圖片等
│   │   └── config.js     //設(shè)定頂部導(dǎo)航欄、側(cè)邊導(dǎo)航欄等項目配置的核心文件
│   ├── pages      //存放markdown頁面的文件
│   ├── README.md     //vuepress首頁展示用的markdown文件
├── deploy.sh     //用于編寫TravisCI上傳、發(fā)布的腳本文件
├── LISENSE     //許可證文件
├── package.json     //Node.js項目描述文件
└── .travis.yml //Travis CI 自動部署文件

language: node_js
node_js:
  - lts/*
install:
  - yarn install # npm ci
script:
  - yarn docs:build # npm run docs:build
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: docs/.vuepress/dist
  github_token: $GITHUB_TOKEN # 在 GitHub 中生成，用于允許 Travis 向你的倉庫推送代碼。在 Travis 的項目設(shè)置頁面進(jìn)行配置，設(shè)置為 secure variable
  keep_history: true
  on:
    branch: master #這里指的是部署前的源文件分支

上面的 github_token 需要在 Github 上生成

生成和使用 Token

生成Token

在 Settings --> Developer settings --> Personal access tokens 右上角 Generate new toekn 生成新Token 名字隨便寫，權(quán)限不清楚的可以全部選上，也可以參考我下面的配置

下面的口令只出現(xiàn)一次，需及時保存

Travis CI 綁定和配置

綁定 Github 賬號

在 Travis CI 里面 Settings ---> Repositories 點擊 Manage repositories on GitHub

選擇給權(quán)限的倉庫，為了方便也可以把所有倉庫的權(quán)限都給了

添加 Token

在項目的 Settings --> Environment Variables 中輸入 Token

language: node_js
node_js:
  - lts/*
install:
  - yarn install # npm ci
script:
  - yarn docs:build # npm run docs:build
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: docs/.vuepress/dist
  github_token: $GITHUB_TOKEN # 在 GitHub 中生成，用于允許 Travis 向你的倉庫推送代碼。在 Travis 的項目設(shè)置頁面進(jìn)行配置，設(shè)置為 secure variable
  keep_history: true
  on:
    branch: master #這里指的是部署前的源文件分支
  • NAME : GITHUB_TOKEN （剛剛的 github_token: $GITHUB_TOKEN 這個變量）
  • VALUE : ****剛剛的 Token****

推送到Github

git add .
git commit -m '初步完成'
git push -f git@github.com:{Username}/{Repo}.git master

# 比如
# git push -f git@github.com:Tsanfer/VuePress-GithubPages-TravisCI.git master

完成

如果沒有 Travis CI 觸發(fā)成功，構(gòu)建沒有問題的話就完成了

本文由Tsanfer's Blog 發(fā)布！

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容