使用vuepress搭建GitHub pages靜態博客頁面

vuepress官網 vuepress是尤大開發來寫文檔的靜態頁面。能夠用Markdown 語法，而且也可使用vue模塊化的方式開發頁面。

vuepress-theme-reco 是另外的開發者開發的 vuepress主題。本文將介紹依賴這個主題，構建GitHub pages靜態博客的詳細過程

 

提早說明：本過程比較詳細，至關於手把手的教，針對於不熟悉vuepress的人介紹的，大佬不喜勿噴。

 

第一步：新建一個GitHub倉庫

1. 倉庫名隨便取，不用以 username.github.io 這種方式。

2. 倉庫不要選 private ，否則不能發佈爲GitHub pages。

3. 選擇添加一個README文件，雖然沒什麼做用，由於後面要覆蓋。

 

第二步：克隆新建倉庫的git地址，初始化項目

　　1.  cmd 中執行 git clone 剛纔複製的 git 地址 

　　2.  推薦使用yarn 來進行安裝，否則有可能會有其它不可未知的錯誤 

　　3.  執行 yarn global add @vuepress-reco/theme-cli  安裝全局主題腳手架。安裝完成後：

 

 　　4. 執行  theme-cli init  而後會提示你選擇一些東西：

注意：最後一個讓選擇主頁是什麼樣式的時候，有三種主題 blog，doc，afternoon-grocery。

我三個都試了一下，

• blog與doc感受基本上同樣
• afternoon-grocery 目錄和vuepress標準的目錄一致，文章都放到view文件夾裏
• 和前兩個相比，多了選擇顏色主題的功能（並不是明暗）；可是首頁右邊分類 我的認爲沒有 blog或者doc的好看。
• 還多了個全屏的功能　

因此我選擇了blog 主題。怎麼選擇就看你本身了。 

注意：若是 yarn 過程出現錯誤，好比相似的：

 須要先把 yarn.lock 刪掉 再從新安裝。那裏面的庫路徑有問題。 

　　5. 若是是安裝的blog或者doc，那麼安裝完成以後，若是package.json中的dev項有  --open --host localhost ，要改爲 vuepress dev . 否則運行不起。注意有個點，不過這個點無關緊要。 

　　6. 改完以後，執行 yarn dev  等待編譯完成，就能看到本地運行的 url 地址，打開便可看到頁面了

 

第三步：推到GitHub 自動轉換成GitHub pages。步驟是blog主題

在上傳代碼到GitHub以前，須要改一些代碼，否則上傳上去 在GitHub pages裏顯示的就是404

1. 修改代碼，push代碼

（1） 根目錄 .vuepress 下的config.js 中的dest項去掉，使用默認的打包後的路徑，及： .vuepress/dist 。不過這項不重要，用自定義的也能夠，後面新建腳本的時候，路徑對上便可

（2） 在config.js 中 和剛纔去掉的dest同級的地方加上  「base」:」/Blogs/」   這個Blogs 不能亂取，必須是你當前GitHub倉庫名，而且先後都有 / 斜槓！！！否則打包後靜態資源路徑會有問題。

（3） 推送代碼到GitHub倉庫中：

git add . 
git commit -m’init’
git push

2. 新建分支

（1） 這時候，能夠在GitHub的倉庫中，看到最新提交的代碼，而後切換到setting選項

 

（2） 下拉到下面 GitHub Pages 項，若是這時候Soure裏面是none，切換成master。點擊save便可。

 

（3） 頁面自動刷新後，再拉到這個地方，就能看到已經自動發佈好了

 

（4） 可是這時候點擊連接，打開的倒是404，這是什麼緣由呢？仔細看404頁面提示的緣由，原來是GitHub pages 必需要有index.html，因爲vuepress是Markdown語法沒有html，因此顯示不了。

（5） 咱們知道打包以後的靜態文件項目就有html文件，因此只須要用另外的分支用來存放打包後的靜態文件，html文件符合GitHub pages的規則，這樣就能正確的顯示了。

（6） GitHub上 點擊master分支，輸入新分支名並create branch 這時候會自動切換到blogs分支上，而且內容和master同樣。blogs分支名隨便取，只要後面發佈的時候，腳本里面的分支名對應上便可

 

 3.  新建腳本，自動推送到blog分支

（1）本地master分支新建一個 deploy.sh文件 名字隨意，後面執行的時候名稱一致便可，後綴是shell的後綴名 .sh ;

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

# 生成靜態文件
yarn build

# 進入生成的文件夾，這裏是默認的路徑，能夠自定義
cd .vuepress/dist

# 若是是發佈到自定義域名
# echo 'www.isunbeam.cn' > 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:<BranchName>
git push -f git@github.com:isunbeam/Blogs.git master:blogs

cd -

# 最後發佈的時候執行 bash deploy.sh

（2） 注意 git push 的時候，分支名必定要和GitHub上新建的分支名同樣。

（3） 執行  bash deploy.sh  。執行完成，到GitHub的倉庫裏，切換到setting，而後拉到GitHub Pages 這時候已經發布了，可是打開連接仍是404，緣由就是做爲github pages的分支不正確，默認是master，下面切換成blogs，點擊save便可

（4）等待頁面刷新後，再次打開便可看到。若是仍是沒有，強制刷新一下 ctrl + f5。可能有緩存。

 

到此，你的博客已經正常發佈到GitHub pages了。\(^o^)/~

 

下面介紹怎麼發表博客：

先說說目錄：該目錄是選擇的blog主題

 

（1） dist 是打包後的靜態文件

（2） public 是存放圖片等內容的

（3） config.js 是最重要的，主題的配置項

（4） blogs 是發表博客文章的地方，第二級目錄表示分類，第三級目錄表示年份，應該是用來作時間線用的，應該不能改爲其它的內容。而後年份裏面就是真正的博客頁面，是 xxx.md 通常是以時間來命名文件的。

　　好比我如今要新建一個博客：

　　（a）在blogs 裏新建一個 2020 名稱的文件夾，裏面再新建一個 090801.md  的md文檔，01表示0908號第一篇，02表示第二篇依此類推。寫好了以後保存，直接刷新頁面或者重啓項目，便可看到新增的博客。

　　 （b）在寫的 md 裏面的 date 日期項，感受不能精確到時分秒，否則時間軸 文章的日期就會多一天。好比date 是寫的 2020-09-08 18:08:08 ，時間軸中就會被解析成 2020年的9月9號發表的。因此建議不用時分秒。

　　 （c）若是想寫的博客有摘要，在正文前加上  <!-- more -->  這以上的代碼就會被解析成摘要。相似下面的文章摘要

 

（5） docs 是寫文檔的地方，至關因而 左邊是大標題，右邊是大標題對應的描述內容。第二級目錄表示文檔分類，和大標題的第一個內容，裏面的README.md就是內容詳情。而後裏面的其他 .md 文檔是另外的大標題的詳情，而後要想新增後生效

　　好比我如今要新建一個文檔說明：

　　（a）docs下面新建一個文件夾testdoc，在這個文件夾裏再新建一個READEME.md做爲大標題1的內容頁，再建一個test1.md表示大標題2的內容頁

　　（b）每一個內容頁裏隨意編寫內容，可是頂部須要有Front Matter配置，而後再寫md文檔。寫好後，在 config.js 中去配置

　　（c）Docs配置項的items裏面加上 

{
    "text": "test",
    "link": "/docs/testdoc/"
}

　　（d）sidebar的配置項里加上 。數組第一項要爲空

"/docs/testdoc/": [
    "",
    "test1"
]

（6） 配置完以後，會自動構建代碼，而後強制刷新一下頁面 ctrl + f5 。若是未生效，就從新啓動一下項目就能夠看到最新的文檔了。

 

自定義域名

 若是有人還想用本身的域名，不用 <username>.github.io/Blogs/ 這種域名，那麼能夠按下面的步驟來實現

第一步：把  config.js 中的 base 項註釋掉，這樣默認靜態文件根目錄是  / ，否則發佈以後會出現靜態文件路徑不正確的問題

第二步：把 deploy.sh 的 echo 'xxx'  > CNAME 這一項放開，而且 把 xxx 換成 本身的域名，好比我是 www.isunbeam.cn 就是 echo 'www.isunbeam.cn' > CNAME

第三步：保存。而後從新構建項目 bash deploy.sh 便可

第四步：域名解析

　　（1） 新建一個 主機值爲www，記錄類型爲 CNAME，記錄值爲 <username>.github.io 的解析

第五步： 在 GitHub 倉庫的 setting 中，GitHub pages選項裏 有一個Custom domain，把它更新爲你剛纔 CNAME解析的   www.xxx.xx 。點擊save便可。

 

到此，自定義域名的靜態博客就完整搭建成功了，其他的就剩看 vuepress-theme-reco的文檔啦。O(∩_∩)O哈哈~

若是有想本身折騰的，也能夠本身用組件的方式，自定義主題。(#^.^#)