Hugo + github 搭建我的博客

前言

很早之前就有想法，搭建一個我的的博客。沒有實現的緣由：一方面我的的服務器不太安全掉線，欠費，維護起來麻煩，另外一方面，文章編輯發佈起來也不方便。

後來瞭解到 github 提供了博客的功能，也一直沒有實踐。也鑑於上次文章被刪，我也就開始實踐了起來，有一個備份總好於無。

選擇什麼程序生成

這個是我第一個糾結的地方，我當時把選擇集中在三個選項裏面：Jekyll，Hexo，Hugo。固然是必定要支持markdown。

針對選擇誰這個問題，我也是在網上查了大量的文章：

• Jekyll 由Ruby語言，三個裏面最悠久，網上有關的問題，解決辦法也比較多。官網主題較多；我的主機搭建的話，這個仍是比較好，插件比較多。
• Hexo 用Nodejs生成的。Hexo有一個相對較大的社區，但大多數是非英語人士（來自中國）。。。
• Hugo 用Go構建的靜態站點生成器。它被宣傳爲「世界上最快的網站構建框架」。屬於後起之秀，主題較少。
  

當時，我糾結了半天。最終決定使用Hugo,主要緣由有下：

1. GO語言是最新的語言；
2. hugo 是最新的生成器，功能方面也確定集成了以前其餘生成器的優勢；
3. 不用安裝，windows下須要一個exe程序，就能夠生成靜態文件了。這個是我選擇他的最關鍵緣由。

選擇HUGO主題

• 只要上面的程序肯定了，選擇主題相對就比較輕鬆了。但是選擇主題，有我的主觀審美在裏面，總會有這樣那樣的不太滿意的地方。
• 我當時在官網上，看了不少主題，都不是特別喜歡，沒有一眼就看上的那種。中文官網上更少，估計三十個主題都沒有。
• 內心盤算着，實在不能偷懶，就拿一個改改算了。

最終，我也記不清當時是怎麼搜到這個 hugo-theme-jane 主題的，印象中好像是一通亂搜。。。

Hugo生成靜態站點

其實這方面網上的文章不少，我這裏就不作全面介紹了。推薦參考 中文官方文檔

• 建議使用git submodule clone下載主題，好處就是修改子模塊以後只對子模塊的版本庫產生影響，對父項目的版本庫不會產生任何影響,
• 修改config.toml文件。至關於該站點的hugo配置文件，涉及到博客標題，分頁，做者聲明等等。
• shortcodes自定義標籤，新增themes/jane/layouts/shortcodes/collapsible.html，相似於博客園的代碼摺疊標籤。
  注意：details 和 summary 是HTML 5 中的新標籤。IE，Firefox都不支持

<details>
    <summary style="background-color:#f5f5f5;border:1px solid #ccc;padding:5px;">
        {{ with .Get 0}}{{.}}{{else}}click to expand{{ end }}
    </summary>
    {{.Inner}}
</details>

在文章編輯中使用參考, 效果

{{% collapsible "hugo代碼摺疊代碼" %}}
中間爲被摺疊的代碼
{{% /collapsible %}}

• 由於主題 jane 是由 nodejs 生成的，若是改了主題的話，須要用node從新生成一下。

我偷懶直接手動修改node生成後的文件，
themes/jane/static/dist/jane.min.css
themes/jane/static/dist/jane.min.css.map

• 圖片的路徑在static/images下面，在文章中使用路徑，不包含static，例如![show 404 page](/images/testjpg.jpg)
• 使用 hugo.exe 生成的靜態文件，在public目錄下，建議不要修改；須要修改的話，改模板文件。

自定義的 js 和 css

強烈建議把一些自定義的功能，或者樣式。按照這樣的方式修改，不要去改themes

在配置文件config.toml中，填寫上這兩個配置

# Link custom CSS and JS assets
#   (relative to /static/css and /static/js respectively)
customCSS = []        # if ['custom.css'], load '/static/css/custom.css' file
customJS = []         # if ['custom.js'], load '/static/js/custom.js' file

注意，這個是對全站點生效的，要加上必要的選擇器。

github 發佈

• github上面只有兩條規則，倉庫{帳號名稱}.github.io 和一個根目錄下的 index.html 文件
• 在個人github上面建立了三個倉庫，

hugo-theme-jane ：是直接fork的主題，有修改需求；強烈建議把修改放到/static/css/目錄下；
mrbenwang.github.io-hugo ：這個是有關於 hugo 的倉庫；
mrbenwang.github.io ：最終的展現靜態頁面，是最重要的。github 的博客主要是從這裏面來讀取的。

• 使用 git submodule 命令：我把 public 和 themes/jane 都分別作了不一樣的git目標；.gitmodules文件內容以下

[submodule "public"]
    path = public
    url = https://github.com/MrBenWang/mrbenwang.github.io.git
[submodule "themes/jane"]
    path = themes/jane
    url = https://github.com/MrBenWang/hugo-theme-jane.git

• public 或 themes/jane 要在其所在的目錄內提交，提交前必定要記得先git checkout master。參考連接

這裏的坑在於，默認 git submodule update 並不會將 submodule 切到任何 branch，因此，默認下 submodule 的 HEAD 是處於遊離狀態的 (‘detached HEAD’ state)。因此在修改前，記得必定要用 git checkout master 將當前的 submodule 分支切換到 master，而後才能作修改和提交。

若是你不慎忘記切換到 master 分支，又作了提交，能夠用 cherry-pick 命令挽救。具體作法以下：

1. 用 git checkout master 將 HEAD 從遊離狀態切換到 master 分支 , 這時候，git 會報 Warning 說有一個提交沒有在 branch 上，記住這個提交的 change-id（假如 change-id 爲 aaaa)
2. 用 git cherry-pick aaaa 來將剛剛的提交做用在 master 分支上
3. 用 git push 將更新提交到遠程版本庫中

結語

• 搭建這個時間，有一些久了，記憶有些模糊，中間過程有些遺漏和錯誤，歡迎指出。
• github 博客