用 Hugo + Coding 搭建靜態博客

更新：CODING 雖好但有費用，建議用 Gitee 搭建免費博客。

適宜讀者

了解 Git 的基本用法，能看懂簡單的 Shell Script。

介紹

Hugo

Static Site Generator (SSG). The world’s fastest framework for building websites.

Pronunciation of Hugo: H EW G OH

Definition of Hugo by Merriam-Webster / Official Video Tutorials

Coding

是一個面向開發者的 雲端開發平台，提供 Git/SVN 代碼托管、任務管理、在線 WebIDE、Cloud Studio、開發協作、文件管理、Wiki 管理、提供個人服務及企業版本的服務。

選擇 Hugo + Coding 的原因

雖然有很多其它靜態網站生成器和代碼托管平台，但 Hugo + Coding 的優勢明顯：

• Hugo 構建速度最快
• Hugo 主題多，其中很火的 Academic 主題也是我最喜歡的
• Coding 在國內訪問速度快
• Coding 平台更先進好用，比如
  • 代碼多倉庫：一個項目下可以新建多個倉庫，大大提高代碼的管理效率。
  • Cloud Studio：為開發者提供了一個永不間斷的雲端工作站。離開本地環境時可利用 Cloud Studio 輕松寫博客。

搭建 Hugo + Coding

安裝軟件

• Git：通常 Linux 平台默認已安裝，對於其他平台參見 安裝 Git。
• Hugo：到 GitHub 下載最新版 Hugo Extended 進行安裝。

Coding 上創建代碼倉庫

先注冊 Coding（填團隊名稱時請三思而后行）。

然后，創建 BLOG 項目：

• 【創建項目】>【模板-代碼托管項目】> 項目名：BLOG >【完成創建】。（blog 倉庫用於存放 Hugo 生成的網頁文件）

再創建一個倉庫用來存放 Hugo 站點：

• 【代碼倉庫】>【創建代碼倉庫】> 倉庫名稱：hugo >【確定】。

將 Hugo 站點和 Hugo 生成的網站文件分開存放。最直接的原因就是避免源代碼泄露。

本地創建 Hugo 站點

先將 hugo 倉庫克隆到本地：

cd /DATA/Writing
git clone [e-mail]:NAME/blog/hugo.git
cd hugo

再將 blog 倉庫添加為 submodule：

git submodule add [e-mail]:NAME/blog.git public

這里使用 Academic 主題：

1. 下載 解壓 Academic Kickstart，將 academic-kickstart-master 中的內容復制到 hugo。
2. 下載 解壓 Academic theme，將 hugo-academic-master 中的內容復制到 themes/academic/。

本地 Hugo 站點創建完畢，使用下面命令實時預覽站點 http://localhost:1313/：

hugo server --gc -D

使用 hugo server --help 查看參數的含義。

限於篇幅，Hugo 和 Academic 的使用請參考各自的官方文檔：

• Hugo 官方文檔
• Academic Theme 官方文檔

將博客發布到 Coding

配置 Git 以及 SSH 公鑰

通常使用 SSH 協議進行 Git 的遠程推送，所以推送前確保已完成下面兩件事情：

第一，配置個人的用戶名稱和電子郵件地址。

$ git config --global user.name "[name]"
$ git config --global user.email "[email address]"
$ git config --global color.ui auto
$ git config --global core.autocrlf false # Linux

第二，配置 SSH 公鑰。

查看是否存在公鑰：

cat ~/.ssh/id_rsa.pub

不存在，則生成公鑰（一路回車）：

ssh-keygen -t rsa -b 4096 -C "[e-mail]"

登錄 CODING ，點擊右上角【個人設置】，選擇菜單【SSH 公鑰】，點擊【新增公鑰】按鈕。

將 id_rsa.pub 中的內容填寫到【公鑰內容】一欄，公鑰名稱按需填寫即可。

將站點推送到 Coding

為了方便，新建一個簡單的部署腳本，gedit deploy.sh：

#!/usr/bin/env bash
# Filename: deploy.sh
#

#### Action 1 ####

echo -e "\n\033[0;34;1m1) Building web pages... [HTML]\033[0m"
# Build the project.
hugo --config ./config/_default/config.toml --gc --minify


#### Action 2 ####

echo -e "\n\033[0;32;1m2) Upload pages to CODING... [HTML]\033[0m\n"
# Go To Repository folder
cd public
# ----------------------------------------------
# Add changes to git.
git add .
# Commit changes.
msg="Update $(date +"[%x %T]")"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
# ----------------------------------------------
# Come Back up to the Project Root
cd ..


#### Action 3 ####

echo -e "\n\033[0;32;1m3) Upload the HUGO site...\033[0m\n"
# ----------------------------------------------
# Add changes to git.
git add .
# Commit changes.
msg="Update $(date +"[%x %T]")"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
# ----------------------------------------------

運行腳本：

chmod 755 deploy.sh
./deploy.sh

開啟靜態網站

回到 Coding 的 BLOG 項目

• 【靜態網站】>【新建靜態網站】> 網站名稱：blog > 選擇倉庫：blog > 【保存】

點擊 訪問地址 訪問網站。由於訪問地址不好記，后期可以考慮購買一個實惠的域名綁到一起。

我的博客（我更願意叫網絡筆記本）：https://www.keatonlao.run/。（看看長啥樣就行。我就是個普通人，里面很多內容沒時間整理，如果你閱讀它，可能會浪費你寶貴的時間。所以，該看書去看書，該上網課去上網課。）

Alias 簡化部署指令

利用 Alias 將重復性的命令指定別名，提高效率。sudo vi /etc/profile.d/alias.sh：

#!/usr/bin/env bash

# Common
alias via='sudo vi /etc/profile.d/alias.sh'
alias vi='vim'

# Hugo
alias gh='cd /DATA/Writing/hugo' # gohugo 快速切換至站點
alias hs='cd /DATA/Writing/hugo && hugo server --gc -D' # 快速生成預覽站點
alias hd='cd /DATA/Writing/hugo && ./deploy.sh' # hugo deploy 快速部署網站

# alias gh2='cd /DATA/Writing/secondary-site'
# alias hs2='cd /DATA/Writing/secondary-site && hugo server --gc -D'

執行 source /etc/profile.d/alias.sh 使別名生效，並將這條命令添加到 ~/.bashrc 或者 ~/.zshrc 的尾部。

使用 Typora 撰寫文章

推薦使用 Typora 撰寫 Markdown。學習 Markdown 可以參看這份筆記：A Study Note for Markdown。

利用 cloud studio 雲端寫博客

離開本地環境時，該如何更新自己的博客？除了跑到 Coding 上直接編輯源代碼，你還有另一種選擇：利用 Cloud Studio 輕松寫博客（需要會用 VS Code）。

首先進入 Coding 的 Cloud Studio 創建工作空間，預置環境選擇：Ubuntu 18.04。

將前面下載的 Hugo 安裝包放到主站點 static/files 下，並推送到 Coding：

./deploy.sh

回到 cloud studio 中，拉取更新：

git pull

然后安裝 hugo：

sudo dpkg -i static/files/hugo_extended_0.72.0_Linux-64bit.deb
hugo version

接下來就可以愉快的寫博客了。

重建 Hugo + Coding

網站用久了，很多歷史版本記錄會占用大量倉庫體積。然而對於博客，這些歷史版本根本用不到，此時需要重建網站（網站翻新）。

Coding 上重置代碼倉庫

進入 BLOG 項目，選擇【代碼倉庫】，在 blog 和 hugo 的【設置】中【重置代碼倉庫】。

重置代碼倉庫將會刪除當前倉庫下的所有代碼，包括代碼分支、合並請求、代碼版本。此操作無法恢復！

本地新建 Hugo 站點

將舊站點移到 Backup 下：

cd /DATA/Writing
mv hugo Backup/

再將 hugo 和 blog 倉庫依次克隆到本地：

git clone [e-mail]:NAME/blog/hugo.git
cd hugo
git submodule add [e-mail]:NAME/blog.git public

手動刪除原 hugo 站點下的 .git 和 public，將剩余文件全部剪貼到新 hugo 站點下。

將博客發布到 Coding

運行部署腳本，將站點推送到 Coding：

./deploy.sh

搭配 TiddlyWiki 管理知識【開外掛】

Tiddlywiki 是一個非線形的個人筆記工具，所有的內容都保存在一個 HTML 文件內。

我之所以喜歡 Academic Theme，是因為用它的 doc 管理知識點很方便。但是會遇到這樣的情況：我最近在學烹飪，但烹飪的知識點太多，使用一個 doc 不能很好的進行管理，而新建一個 courses 又沒必要。這個時候，使用 TiddlyWiki 就能很好的構建烹飪知識。

將 TiddlyWiki 文件放到 static/tiddlywiki/cookery.html，為了方便查看，在 Cookery doc 的首頁引用：

{{% staticref "tiddlywiki/cookery.html" "newtab" %}}cookery.html{{% /staticref %}}

具體效果參看：安裝使用 GoldenDict 查詞神器 (Windows/Mac/Linux)。這是用 TiddlyWiki 寫的軟件使用經驗，如果用一個 doc 來寫這篇經驗，效果將大打折扣。

配置主副站點

由於代碼托管平台無法對 Hugo Academic 文章進行加密，我的解決辦法是建立主副站點。將前面的站點作為副站點，再新建一個主站點，並使用 Rsync 進行主副站點之間的同步。副站點給別人看，主站點給自己用。由於主站點沒有綁定域名解析等服務，也沒有透露在任何平台，就自己知道，所以很多自己收集的材料或者學習時的筆記草稿都可以隨時上傳。當然，如果因為站點體積太大而拆分為兩個站點，也是一種思路。

新建主站點

在 BLOG 項目中新建主站點。主副站點之間的對應關系：

• main-site-html ↛ blog
• main-site → hugo

主副站點之間同步

同步的邏輯很簡單，除了 .git 和 public 兩個文件夾，副站點的內容全部來自主站點（副站點的 config 文件夾保存在主站點 scripts/secondarysiteconfig 中）。簡單的示意圖：

使用 Rsync 命令進行單向無差異同步。該命令主要有下面四種用法：

# 單項--無差異同步
rsync -avq --delete $src/dir1 $dest/

# 多項--無差異同步
rsync -avq --delete --include={sh4,sh5} --exclude=* $src/ $src/dir2

# 排除單項--無差異同步
rsync -avq --delete --exclude=dir4 $src/dir1 $dest/

# 排除多項--無差異同步
rsync -avq --delete --exclude={dir4,dir5,file4,file5} $src/ $dest/

具體的同步腳本為：

#!/usr/bin/env bash
# sync_to_public_website.sh
#
# This is a simple script. You should always create new files on the main site.
# Otherwise, you may lose data.
#

src='/DATA/Writing/main-site'
dest='/DATA/Writing/secondary-site'


#################################
##  Update secondary site      ##
#################################

echo -e "\n\033[0;31;1mUpdate secondary site\033[0m\n"
echo -e "\033[37m[directory]\033[0m"

## The root directory
# 先排除多項進行同步，再處理排除項中需要同步的文件夾
echo -e "\033[32m  root\033[0m"
rsync -avq --delete --exclude={config,content,layouts,public,resources,static,.git,.gitmodules} $src/ $dest/
rsync -avq --delete $src/scripts $dest/

## The content directory
echo -e "\033[32m  content\033[0m"
rsync -avq --delete $src/content/authors       $dest/content/
rsync -avq --delete $src/content/courses       $dest/content/
rsync -avq --delete $src/content/home          $dest/content/
rsync -avq --delete $src/content/post          $dest/content/
rsync -avq --delete $src/content/privacy.md    $dest/content/
rsync -avq --delete $src/content/terms.md      $dest/content/

## The static directory
echo -e "\033[32m  static\033[0m"
rsync -avq --delete --exclude={book,temp} $src/static $dest/


##  The secondary site config
# 副站點 config 存在則備份到主站點；不存在則從主站點恢復。
echo -e "\n\033[37m[secondarysiteconfig]\033[0m"

if [ -d "$dest/config" ]; then
    rsync -avq --delete $dest/config $src/scripts/secondarysiteconfig/ \
    && echo -e "\033[32m  Backed up\033[0m\n" \
    || echo -e "\n\033[31m  Error\033[0m Please modify \033[36msync_to_public_website.sh\033[0m\n"
else
    rsync -avq $src/scripts/secondarysiteconfig/config $dest/ \
    && echo -e "\033[32m  Updated\033[0m\n"
fi

在主站點新建 12deploy.sh，依次【同步主副站點 〉部署主站點 〉部署副站點】：

#!/usr/bin/env bash
# 12deploy.sh
#

main=/DATA/Writing/main-site
secondary=/DATA/Writing/secondary-site

bash $main/sync_to_public_website.sh

echo -e "\033[0;31;1mDeploy main site\033[0m"
bash $main/deploy.sh

echo -e "\n\033[0;31;1mDeploy secondary site\033[0m"
cd $secondary
bash $secondary/deploy.sh
cd $main

— END —