天天看點
傳回

建立 VuePress + GithubPages + TravisCI 線上文檔

目錄

  • 最終效果
  • 思路
    • 總體
    • 過程
    • 用到的東西
    • 相關
  • 建立Github倉庫
      • SSH密鑰連結Github
        • 生成SSH密鑰
        • Github添加SSH密鑰
        • 測試SSH密鑰
  • 配置VuePress
    • 安裝VuePress
      • 安裝yarn
        • Debian / Ubuntu
        • Windows
        • 更換國内的源
      • VuePress目錄結構
    • 配置依賴和腳本
      • 配置package.json
    • 頁面的設定
      • 首頁
      • 文檔屬性
      • markdown擴充
      • 預設主題設定
        • 導航欄
        • 側邊欄
        • Git倉庫
        • 其他
      • 插件
      • config.js所有内容
  • TravisCI生成和釋出
    • 建立gh-pages分支
    • deploy.sh部署檔案
    • Travis CI 部署檔案
    • 生成和使用 Token
      • 生成Token
    • Travis CI 綁定和配置
      • 綁定 Github 賬号
      • 添加 Token
    • 推送到Github
    • 完成
最新部落格連結
VuePress 線上文檔連結_Github Pages
VuePress 線上文檔連結_部落格伺服器（如果上面進不去，可以進這個，伺服器在阿裡雲）
Github連結

最終效果連結

建立 VuePress + GithubPages + TravisCI 線上文檔

VuePress 在本地完成項目的源檔案，推送至 Github 觸發 Travis CI 自動建構目标檔案，完成後自動部署到另一個 Github 分支，此分支作線上文檔使用。

在Github上建立兩個分支

master

和

gh-pages

，

master

用于上傳源檔案和觸發 Travis CI 自動執行建構、部署腳本，

gh-pages

用于儲存 Github Pages 的最終頁面。

完成上述操作之後就隻需修改文本源檔案Markdown裡面的内容，推送到Github。Travis CI 便可自動建構、部署，使其工作流程簡化。

  1. 在本地建立配置 VuePress 工程上傳到

    master

     分支
  2. 上傳成功後觸發 TravisCI 開始自動建構
  3. 建構完成後将最終頁面推送到

    gh-pages

  • VuePress目錄檔案結構
  • VuePress配置檔案
  • TravisCI自動建構配置檔案

  • VuePress:

    每一個由 VuePress 生成的頁面都帶有預渲染好的 HTML，也是以具有非常好的加載性能和搜尋引擎優化（SEO）。同時，一旦頁面被加載，Vue 将接管這些靜态内容，并将其轉換成一個完整的單頁應用（SPA），其他的頁面則會隻在使用者浏覽到的時候才按需加載。

  • GitHub Pages:

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

    GitHub Pages 是一項靜态站點托管服務，它直接從 GitHub 上的倉庫擷取 HTML、CSS 和 JavaScript 檔案，（可選）通過建構過程運作檔案，然後釋出網站。

  • Travis CI

    Travis CI 提供的是持續內建服務（Continuous Integration，簡稱 CI）。它綁定 Github 上面的項目，隻要有新的代碼，就會自動抓取。然後，提供一個運作環境，執行測試，完成建構，還能部署到伺服器。

    持續內建指的是隻要代碼有變更，就自動運作建構和測試，回報運作結果。確定符合預期以後，再将新代碼"內建"到主幹。

    持續內建的好處在于，每次代碼的小幅變更，就能看到運作結果，進而不斷累積小的變更，而不是在開發周期結束時，一下子合并一大塊代碼。

在Github官網上建立一個新的倉庫（我倉庫的名字叫

VuePress-GithubPages-TravisCI

）

$ ssh-keygen
Generating public/private rsa key pair.
# 輸入準備存放密鑰的位置，公鑰和私鑰放在同一個檔案夾
Enter file in which to save the key (/home/tsanfer/.ssh/id_rsa): /home/tsanfer/.ssh/test_key
# 輸入密碼，不需要密碼就直接回車，這裡我不需要密碼，直接回車
Enter passphrase (empty for no passphrase):
# 确認密碼，跟上面一樣
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頭像旁邊的菜單中 Settings --> SSH and GPG keys --> SSH keys 中的右上角點選 New SSH key

下面要填入資訊：

  • Title：随便填
  • Key：公鑰檔案裡的所有内容（

    ~/.ssh/test_key.pub

測試一下密鑰

ssh -T [email protected]

設定Github賬号的位址

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

# 比如
git config --global user.name "Tsanfer"
git config --global user.email "[email protected]"

如果成功的話

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

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

# 選一個檔案夾克隆倉庫
# 比如家目錄
cd ~
git clone [email protected]:{Username}/{Repo}.git

# 比如
# cd ~
# git clone [email protected]:Tsanfer/VuePress-GithubPages-TravisCI.git
           
# 克隆完之後的目錄
~/VuePress-GithubPages-TravisCI/

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

也可以安裝npm

在 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

直接下安裝包，然後在CMD或者Powershell裡運作

先看一下目前的源

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

更換阿裡淘寶的源

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

# 先進入安裝目錄，就是剛剛克隆的倉庫
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生成的網頁的位址

或者建構靜态檔案

# 建構靜态檔案
vuepress build .

但會因為路徑不對，網頁的樣式顯示不出來

官方給的結構

VuePress 遵循 “約定優于配置” 的原則，推薦的目錄結構如下： 
.
├── docs
│   ├── .vuepress (可選的)
│   │   ├── components (可選的)
│   │   ├── theme (可選的)
│   │   │   └── Layout.vue
│   │   ├── public (可選的)
│   │   ├── styles (可選的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可選的, 謹慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可選的)
│   │   └── enhanceApp.js (可選的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

這裡用到的結構

.
├── README.md     // Github項目展示檔案
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心内容的檔案夾
│   │   ├── public     //存放靜态檔案，如圖檔等
│   │   └── config.js     //設定頂部導航欄、側邊導航欄等項目配置的核心檔案
│   ├── pages      //存放markdown頁面的檔案
│   ├── README.md     //vuepress首頁展示用的markdown檔案
├── deploy.sh     //用于編寫TravisCI上傳、釋出的腳本檔案
├── LISENSE     //許可證檔案
├── package.json     //Node.js項目描述檔案
└── .travis.yml	//Travis CI 自動部署檔案

在

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

/docs/README.md

 
---
home: true
heroImage: https://cdn-image.tsanfer.xyz/img/vuepress_githubpages_travisCI.svg
actionText: 快速上手 →
actionLink: /pages/思路.md
features:
- title: 簡潔至上
  details: 以 Markdown 為中心的項目結構，以最少的配置幫助你專注于寫作。
- title: Vue驅動
  details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 元件，同時可以使用 Vue 來開發自定義主題。
- title: 高性能
  details: VuePress 為每個頁面預渲染生成靜态的 HTML，同時在頁面被加載的時候，将作為 SPA 運作。
footer: MIT Licensed | Copyright © 2020 Tsanfer
---

/docs/.vuepress/config.js

 
module.exports = {
    base: '/VuePress-GithubPages-TravisCI/',    //目錄根位址，應與Github倉庫名字相同
    title: 'VuePress + GithubPages + TravisCI',    // 顯示在左上角的網頁名稱以及首頁在浏覽器标簽顯示的title名稱
    description: '建立 VuePress + GithubPages + TravisCI 線上文檔',    // meta 中的描述文字，用于SEO
    head: [
        ['link', 
            { rel: 'icon', href: '/gamepad_game_128px.ico' }   //浏覽器的标簽欄的網頁圖示,基位址/docs/.vuepress/public
        ],  
    ],
}

/docs/.vuepress/config.js

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

/docs/.vuepress/config.js

 
module.exports = {
	themeConfig: {
		nav: [
            //連結頁面連結的根位址為/docs
            { text: '思路', link: '/pages/思路.md' },
            { text: '建立Github倉庫', link: '/pages/建立Github倉庫.md' },
            { text: '配置VuePress', link: '/pages/配置VuePress.md' },
            { text: '建立分支和Github pages', link: '/pages/建立分支和Github pages.md' },
            { text: 'TravisCI生成和釋出', link: '/pages/TravisCI生成和釋出.md' },
            { text: '部落格', link: 'https://tsanfer.xyz' },
        ],
	},
}

/docs/.vuepress/config.js

 
module.exports = {
	themeConfig: {
        sidebarDepth: 2,    //側邊欄深度
        sidebar: [
            ['/pages/思路.md', '思路'],
            ['/pages/建立Github倉庫.md', '建立Github倉庫'],
            ['/pages/配置VuePress.md', '配置VuePress'],
            ['/pages/建立分支和Github pages.md', '建立分支和Github pages'],
            ['/pages/TravisCI生成和釋出.md', 'TravisCI生成和釋出'],
        ],
	},
}

/docs/.vuepress/config.js

 
module.exports = {
	 themeConfig: {
		// 假定是 GitHub. 同時也可以是一個完整的 GitLab URL
        repo: 'Tsanfer/VuePress-GithubPages-TravisCI',
        // 自定義倉庫連結文字。預設從 `themeConfig.repo` 中自動推斷為
        // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
        repoLabel: 'Github',
        // 以下為可選的編輯連結選項
        // 假如文檔不是放在倉庫的根目錄下：
        docsDir: 'docs/pages',
        // 假如文檔放在一個特定的分支下：
        docsBranch: 'master',
        // 預設是 false, 設定為 true 來啟用
        editLinks: true,
        // 預設為 "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',  //網頁加載進度條
        '@vuepress/plugin-back-to-top', //傳回頁面頂部按鈕
    ]
}
到這裡其實已經完成配置了，可以執行

yarn docs:dev

 來浏覽配置的頁面，隻是由于沒有對應的 md 檔案，打開的連結都會404 

module.exports = {
    base: '/VuePress-GithubPages-TravisCI/',    //目錄根位址，應與Github倉庫名字相同
    title: 'VuePress + GithubPages + TravisCI',    // 顯示在左上角的網頁名稱以及首頁在浏覽器标簽顯示的title名稱
    description: '建立 VuePress + GithubPages + TravisCI 線上文檔',    // meta 中的描述文字，用于SEO
    head: [
        ['link', 
            { rel: 'icon', href: '/gamepad_game_128px.ico' }   //浏覽器的标簽欄的網頁圖示,基位址/docs/.vuepress/public
        ],  
    ],

    //markdown擴充
    markdown: {
        lineNumbers: true,  //是否在每個代碼塊的左側顯示行号
    },

    //預設主題配置
    themeConfig: {
        //導航欄
        nav: [
            //連結頁面連結的根位址為/docs
            { text: '思路', link: '/pages/思路.md' },
            { text: '建立Github倉庫', link: '/pages/建立Github倉庫.md' },
            { text: '配置VuePress', link: '/pages/配置VuePress.md' },
            { text: 'TravisCI生成和釋出', link: '/pages/TravisCI生成和釋出.md' },
            { text: '部落格', link: 'https://tsanfer.xyz' },
        ],
        sidebarDepth: 2,    //側邊欄深度
        //側邊欄
        sidebar: [
            ['/pages/思路.md', '思路'],
            ['/pages/建立Github倉庫.md', '建立Github倉庫'],
            ['/pages/配置VuePress.md', '配置VuePress'],
            ['/pages/TravisCI生成和釋出.md', 'TravisCI生成和釋出'],
        ],

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

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

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

建立 VuePress + GithubPages + TravisCI 線上文檔

這時Github已經自動部署gh-pages分支為Github pages的生成源

建立 VuePress + GithubPages + TravisCI 線上文檔

每當 Github 倉庫更新時，會觸發 Travis CI 執行

deploy.sh

腳本

建立一個如下的

deploy.sh

檔案（請自行判斷去掉高亮行的注釋）:

在項目根目錄下建立

.
├── README.md     // Github項目展示檔案
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心内容的檔案夾
│   │   ├── public     //存放靜态檔案，如圖檔等
│   │   └── config.js     //設定頂部導航欄、側邊導航欄等項目配置的核心檔案
│   ├── pages      //存放markdown頁面的檔案
│   ├── README.md     //vuepress首頁展示用的markdown檔案
├── deploy.sh     //用于編寫TravisCI上傳、釋出的腳本檔案
├── LISENSE     //許可證檔案
├── package.json     //Node.js項目描述檔案
└── .travis.yml	//Travis CI 自動部署檔案
           
#!/usr/bin/env sh

# 確定腳本抛出遇到的錯誤
set -e

# 生成靜态檔案
yarn 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 [email protected]:<USERNAME>/<USERNAME>.github.io.git master

# 如果釋出到 https://<USERNAME>.github.io/<REPO>
git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
# 比如
# git push -f [email protected]:Tsanfer/VuePress-GithubPages-TravisCI.git master:gh-pages

cd -

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

建立 VuePress + GithubPages + TravisCI 線上文檔

在項目的根目錄建立一個名為

.travis.yml

的檔案

.
├── README.md     // Github項目展示檔案
├── docs     //vuepress項目根目錄
│   ├── .vuepress      //存放核心内容的檔案夾
│   │   ├── public     //存放靜态檔案，如圖檔等
│   │   └── config.js     //設定頂部導航欄、側邊導航欄等項目配置的核心檔案
│   ├── pages      //存放markdown頁面的檔案
│   ├── README.md     //vuepress首頁展示用的markdown檔案
├── deploy.sh     //用于編寫TravisCI上傳、釋出的腳本檔案
├── 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 的項目設定頁面進行配置，設定為 secure variable
  keep_history: true
  on:
    branch: master #這裡指的是部署前的源檔案分支

上面的 github_token 需要在 Github 上生成

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

建立 VuePress + GithubPages + TravisCI 線上文檔
建立 VuePress + GithubPages + TravisCI 線上文檔
建立 VuePress + GithubPages + TravisCI 線上文檔
下面的密碼隻出現一次，需及時儲存
建立 VuePress + GithubPages + TravisCI 線上文檔

在 Travis CI 裡面 Settings ---> Repositories 點選 Manage repositories on GitHub

建立 VuePress + GithubPages + TravisCI 線上文檔

選擇給權限的倉庫，為了友善也可以把所有倉庫的權限都給了

建立 VuePress + GithubPages + TravisCI 線上文檔

在項目的 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 的項目設定頁面進行配置，設定為 secure variable
  keep_history: true
  on:
    branch: master #這裡指的是部署前的源檔案分支
  • NAME : GITHUB_TOKEN （剛剛的

    github_token: $GITHUB_TOKEN

     這個變量）
  • VALUE : ****剛剛的 Token****
建立 VuePress + GithubPages + TravisCI 線上文檔

git add .
git commit -m '初步完成'
git push -f [email protected]:{Username}/{Repo}.git master

# 比如
# git push -f [email protected]:Tsanfer/VuePress-GithubPages-TravisCI.git master

如果沒有 Travis CI 觸發成功，建構沒有問題的話就完成了

建立 VuePress + GithubPages + TravisCI 線上文檔
本文由Tsanfer's Blog 釋出！
TravisCI githubPages vuepress
上一篇: 哪些值可以被取位址，哪些值不可以被取位址？左值和右值
下一篇: 深入了解MySql子查詢IN的執行和優化

繼續閱讀