快速掌握VuePress+GitHub Pages構建我的博客

VuePress構建我的博客

使用vuepress+github pages構建我的博客，使用官方文檔過程當中遇到不少問題，遂單獨整理

What is VuePress?

VuePress是一個靜態網站生成器。

使用Markdown書寫頁面，markdown-it將其解析成HTML。Vue、Vue-Router和webpack合做構建一個單頁應用，生成靜態網站。

What is github pages?

GitHub Pages是一個靜態站點託管服務，能夠從GitHub上獲取html、css和js文件，發佈一個網站。

快速上手

vuepress快速上手

# 建立項目目錄blog-demo
mkdir blog-demo && cd blog-demo

# 初始化項目
npm init -y

# 本地安裝VuePress
npm install -D vuepress

# 新建一個docs文件夾
mkdir docs

# 新建一個markdown文件
echo '# test' > docs/README.md

在package.json中添加

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

運行以下命令，啓動一個服務器

npm run docs:dev

默認狀況下,靜態文件生成在 .vuepress/dist，目錄相似以下所示

訪問http://localhost:8080/查看運行結果

部署

• 在github上新建項目vuepress-blog
• 在本地項目blog-demo根目錄下建立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/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
# git push origin 本地分支:遠端但願建立的分支
git push -f git@github.com:<username>/vuepress-blog.git master:gh-pages

cd -

• 運行deploy.sh腳本，查看github，生成的靜態文件上傳成功

• github上setting中設置github pages

• 訪問上圖中的地址，訪問成功即部署成功。

總體流程和最主要的功能已經完成，在此基礎上添加頁面和其餘功能。

vuepress踩坑

側邊欄和導航欄

這裏遇到的坑最多。爲了實現VuePress官網相似的側邊欄，而且在選擇不一樣的導航欄以後能夠顯示不一樣的側邊欄。

最好的例子是VuePress官方文檔自己的config.js源碼。

每一個頁面必須有且僅有一個一級標題

# 一級標題

因爲各類理由，我的不多使用一級標題，markdown文件都沒有一級標題，因而側邊欄花費了很長時間，這一點官方文檔也沒有明確說明。

導航欄中路徑不能寫徹底的路徑

nav: [{
    text: '指南',
    link: '/zh/guide/'
    <!-- link:'/zh/guide/README.md'寫法不行 -->
}]

VuePress官方文檔示例

靜態資源路徑

vuepress默認使用.vuepress/public存放靜態資源(能夠修改)，在config.js中base值會影響靜態資源引用路徑。 例如，config.js中設置了base

module.exports = {
    base:'/vuepress-blog/',
    // ……
}

靜態資源位置以下所示

引用資源路徑以下所示

<!-- .md文件 -->
<img src="/vuepress-blog/images/path.png"  >

當前能看獲得圖片，就說明成功

一個 base 路徑一旦被設置，它將會自動地做爲前綴插入到 .vuepress/config.js 中全部以 / 開始的資源路徑中。

新的分支

這個例子中使用gh-pages分支來維護靜態資源。

若是想在已有項目中增長一個說明文檔/使用文檔，使用VuePress(靜態網站生成器，hexo等生成器原理相同)生成靜態文件(.vuepress/dist文件夾中的內容)，上傳至一個新的分支gh-pages。

github pages基於該分支構建網站，與主分支master互不影響，而且須要維護的資源也少。

查看github-vuepress-blog，master分支負責維護博客源碼，gh-pages分支提供給github pages構建網站。

更新github pages

每次修改完以後，運行deploy.sh文件。該文件生成新的靜態文件，並更新至gh-pages分支，刷新網頁便可查看更新後的效果

博客源碼分支

能夠查看push.sh文件，運行該腳本更新源碼到master分支。

#!/usr/bin/env sh

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

# 上傳
git init
git add -A
git commit -m 'update'

# 上傳源碼部分到master分支
git push -f git@github.com:<USERNAME>/vuepress-blog.git master

根據實際須要增長分支