Github Pages + Hugo 搭建個人博客

零、效果

本次配置最終效果圖：

快速搭建方式，直接下載修改后的模板改也是可以的：https://github.com/zz2summer/blog-hugo-theme-LoveIt

完成步驟一、二、三，然后下載上述文件到 blog 目錄下就可以跳過第四步了。

一、創(chuàng)建 Github 庫

1. 打開 Github ，新建一個庫。

   

2. 輸入項目名，要與 Github 用戶名一致。比如我的是 zz2summer，那么輸入的 Repository name 就是 zz2summer.github.io，README 也一并勾選上。

   

二、安裝 Hugo 和 Git

1. 查閱 Hugo 安裝指南：Install Hugo | Hugo，找到對應(yīng)系統(tǒng)的安裝操作。

   基本上都是使用各個包工具安裝，本人 Win10，比較嫌麻煩就直接下載使用。

2. 打開 Github 中的 Hugo 庫，打開右側(cè)的 Realeases，下載最新的版本，本次下載為：hugo_extended_0.82.0_Windows-64bit.zip

   下載 extened 版本是因為有些主題的需要利用進行 SCSS/SASS 構(gòu)建，如果下普通版就可能會報錯顯示： you need the extended version to build SCSS/SASS

3. 解壓后，將其中的 hugo.exe 放到指定的安裝目錄，比如 D:\softwares\Hugo\bin，然后將該目錄添加到系統(tǒng)環(huán)境變量（win+R → sysdm.cpl → 高級 → 環(huán)境變量 → 系統(tǒng)變量 Path）的 Path 下。

4. 打開命令行，輸入 hugo version，顯示版本號即為安裝成功

   

5. 本地下載 Git ，Win10直接下載 exe ，點擊下一步就好了。

三、新建 Hugo 網(wǎng)站

1. 新建一個目錄，用于存放 Hugo 網(wǎng)站的文件，比如：H:\HugoWebsite

2. 打開命令行，切換到該目錄，執(zhí)行命令新建一個 Hugo 網(wǎng)站

   # blog 是網(wǎng)站文件夾名
   hugo new site blog
   

   

四、選擇 Hugo 主題

1. 打開 hugo theme 的網(wǎng)站，選擇合適的主題，以Tranquilpeak 舉例。

   Hugo Themes: https://themes.gohugo.io

2. 將選中的主題下載到本地

   # 進入網(wǎng)站目錄 blog
   cd blog
   # 進入 themes 目錄，一般默認有，如果沒有自行創(chuàng)建：mkdir -p themes
   cd themes
   # 下載主題到 tranquilpeak 文件夾下
   git clone https://github.com/kakawait/hugo-tranquilpeak-theme.git tranquilpeak
   

   

3. 此處建議選擇的這個主題相較適合第一次嘗試，配置文件比較詳細明了。待熟悉后，可以自行選擇主題。

   Hugo主題庫：https://themes.gohugo.io，個人推薦主題：https://github.com/dillonzq/LoveIt.git

4. 在 Hugo 網(wǎng)站的根目錄下（上文提及的 HugoWebsite）配置 config.toml

   詳細配置參考：hugo-tranquilpeak-theme/user.md at master · kakawait/hugo-tranquilpeak-theme

5. 當(dāng)前工作目錄：H:\HugoWebsite\blog，備份 config.toml 原文件，然后將 themes/tranquilpeak/exampleSite/config.toml 復(fù)制過來覆蓋原文件，打開 config.toml 閱讀并修改配置

   簡單講就是利用已經(jīng)配置好的主題配置文件進行修改。

五、新建文章

1. 進入網(wǎng)站文件夾根目錄：H:\HugoWebsite\blog，鼠標(biāo)右鍵選擇 Git Bash Here

2. 新建文章：first-post.md，**注意區(qū)分主題的要求，有些主題新建文章的目錄是 posts **

   hugo new post/first-post.md
   

3. 編輯文章內(nèi)容，保存。

4. 啟動 Hogo server

   hugo server -D
   

   

5. 打開網(wǎng)址 http://localhost:1313/ 可以進行預(yù)覽

   

   如果發(fā)現(xiàn)預(yù)覽效果不滿意，可以 編輯 config.toml 文件

六、部署到 Github

1. 構(gòu)建 Hugo 網(wǎng)站

   在 Hugo 網(wǎng)站文件夾的根目錄（H:\HugoWebsite\blog）下執(zhí)行 hugo 命令構(gòu)建

   

   Hugo 會將構(gòu)建的網(wǎng)站內(nèi)容默認保存至網(wǎng)站根目錄下的 public/ 文件夾下。

2. 將網(wǎng)站文件夾與 GitHub 建立聯(lián)系**（僅第一次運行需要）**

   • 進入 H:\HugoWebsite\blog\public 目錄，初始化 Git 庫

     生成的 HTML 文件保存在 “public” 目錄中，“public” 文件夾會被轉(zhuǎn)換為 Git 庫。

     git init
     

     

   • 將 Git 本地庫關(guān)聯(lián)至遠程庫

     在 H:\HugoWebsite\blog\public 目錄下，為 Git 本地庫添加遠程庫，“git@github.com:your-github-id/your-github-id.github.io.git”

     git remote add origin git@github.com:zz2summer/zz2summer.github.io.git
     

3. 提交修改

   在 H:\HugoWebsite\blog\public 目錄下，通過如下命令提交：

   # 查看當(dāng)前修改狀態(tài)
   git status
   # 添加修改過得文件，  . 表示所有，也可以指定文件
   git add .
   # ""里面的內(nèi)容就是提交內(nèi)容的說明信息
   git commit -m "first commit"
   

4. 提交修改至遠程庫

   在 H:\HugoWebsite\blog\public 目錄下，通過如下命令提交：

   git push -u origin master
   

   然后如果按照博客順序操作，第一次應(yīng)該失敗的。

   

   因為本地的 git 庫和遠程的庫并不是一致的，需要進行一次 pull 操作才能繼續(xù) push。

   第一種解決辦法就是加參數(shù) -f ，強制推送，但是這樣很危險，會導(dǎo)致其他的更新提交失敗，也就是說原來該庫下所有文件都會被刪除掉，只剩下本次提交的文件了。日常不建議這么操作，但是其實本次第一次是可以的，因為當(dāng)前庫下沒有還沒有有效文件。

   git push -u -f origin master
   

   第二種方案為：先把除 .git 文件夾外的所有文件復(fù)制到其他目錄備份，然后 git pull 當(dāng)前庫下的文件下來，然后把這些文件和自己需要的文件結(jié)合處理好（本次就是刪除這些文件，再把原文件復(fù)制回來），重新提交即可。日常推薦這種方法，養(yǎng)成好習(xí)慣。

   # 1.移動除 .git 外的文件到另一個目錄下
   # 2.pull 該庫當(dāng)前文件，最后的參數(shù)是因為合并兩個不相關(guān)的項目（即，不知道彼此存在并且提交歷史不匹配的項目）時，會發(fā)生Git錯誤：fatal: refusing to merge unrelated histories，此時出現(xiàn)記錄文件，先按住 ctrl+:，再輸入 wq 即可。
   git pull origin master --allow-unrelated-histories
   # 3.合并這些文件和第一次移動出去的文件，本次就是刪除這些文件，把那些文件移動回來就好了
   # 4.提交本地
   git add .
   git commit -m "first commit"
   # 5.提交遠程
   git push -u origin master
   

5. 好了，第一次初始化配置也就成功完成了！輸入：https://zz2summer.github.io/ 就可以訪問部署的網(wǎng)站了。

七、日常操作

1. 新建文章

# 1.新建一篇文章，在網(wǎng)站根目錄：H:\HugoWebsite\blog
hugo new post/第二篇測試博客.md
# 2.在目錄 H:\HugoWebsite\blog\content\post 下找到對應(yīng)文件進行修改
# 3.本地預(yù)覽, http://localhost:1313/ 
hugo server -D
# 4.構(gòu)建 Hugo 網(wǎng)站
hugo
# 5.切換到目錄 H:\HugoWebsite\blog\public ，提交修改至本地庫
git add .
git commit -m 'commit info'
# 6.將修改推至遠程庫
git push -u origin master

2. 修改文章

# 1.當(dāng)前工作目錄：H:\HugoWebsite\blog
# 2.在目錄 H:\HugoWebsite\blog\content\post 下找到對應(yīng)文件
進行修改
# 3.本地預(yù)覽, http://localhost:1313/ 
hugo server -D
# 4.構(gòu)建 Hugo 網(wǎng)站
hugo
# 5.切換到目錄 H:\HugoWebsite\blog\public ，提交修改至本地庫
git add .
git commit -m 'commit info'
# 6.將修改推至遠程庫
git push -u origin master

3. 刪除文章

# 1.當(dāng)前工作目錄：H:\HugoWebsite\blog
# 2.刪除兩處文件
在目錄 H:\HugoWebsite\blog\content\post 、H:\HugoWebsite\blog\public  下找到對應(yīng)文件進行刪除
其中 public 下文件不刪除也不影響顯示，只是該文件就會一直存在，另外該目錄下即便文件（除.git)刪錯或者全部刪除也是不影響的，應(yīng)為 hugo 命令會全部重建
# 3.本地預(yù)覽, http://localhost:1313/ 
hugo server -D
# 4.構(gòu)建 Hugo 網(wǎng)站
hugo
# 5.切換到目錄 H:\HugoWebsite\blog\public ，提交修改至本地庫
git add .
git commit -m 'commit info'
# 6.將修改推至遠程庫
git push -u origin master

4.添加圖片

Hugo 的配置文件和文章中引用圖片都是從static作為根目錄的。（H:\HugoWebsite\blog\static）

也就是說首先要將圖片放置到 static 文件夾下，以 static 為相對路徑，然后進行引用，方式為：![](pic_name.png)，當(dāng)然這樣該 .md 文件中是不會顯示，本地預(yù)覽和部署后是可以看到的

正常做法：

1. 寫文章時，在該文章目錄下新建文件夾存放照片，引用時采用相對路徑。
2. 完成之后，在引用路徑前加個 /，比如原來引用方式 ![](imgs/pic_name.png) ，需要修改為 ![](/imgs/pic_name.png) 。
3. 之后將該圖片文件夾移動到 static 目錄下即可。

注意：如果該文件夾名包含空格可能會不能被顯示，支持中文，但是不支持含空格。

5. 圖片加水印

1. 找一份字體放到根目錄下（H:\HugoWebsite\blog）。

   （win10自帶字體文件目錄：C:\Windows\Fonts）

2. 創(chuàng)建 watermark.py

3. 然后每次寫完一篇文章可以運行python watermark.py postname添加水印。

   如果第一次運行要給所有文章添加水印，可以運行python watermark.py all。

# -*- coding: utf-8 -*-
import sys
import glob
from PIL import Image
from PIL import ImageDraw
from PIL import ImageFont


def watermark(post_name):
    if post_name == 'all':
        post_name = '*'
    dir_name = 'static/' + post_name + '/*'
    for files in glob.glob(dir_name):
        im = Image.open(files)
        if len(im.getbands()) < 3:
            im = im.convert('RGB')
            print(files)
        font = ImageFont.truetype('arial.ttf', max(30, int(im.size[1] / 20)))
        draw = ImageDraw.Draw(im)
        # draw.text((im.size[0] / 2, im.size[1] / 2), u'@yourname', fill=(0, 0, 0), font=font)
        text_size_x, text_size_y = draw.textsize(u'@yourname', font=font)
        draw.text((im.size[0] - text_size_x, im.size[1] - text_size_y), u'@yourname', fill=(0, 0, 0, 85), font=font)
        im.save(files)


if __name__ == '__main__':
    if len(sys.argv) == 2:
        watermark(sys.argv[1])
    else:
        print('[usage] <input>')

八、細節(jié)優(yōu)化

1.谷歌分析的配置

1. 獲取 跟蹤ID，https://analytics.google.com/

2. 添加如下代碼到 <head> 標(biāo)簽中

   <!-- Global site tag (gtag.js) - Google Analytics -->
   <script async src="https://www.googletagmanager.com/gtag/js?id=UA-xxxxxxxxx-x"></script>
   <script>
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
     gtag('js', new Date());
   
     gtag('config', 'UA-xxxxxxxxx-x');
   </script>
   

2. 添加訪問計數(shù)

參考如下代碼，添加到想要加入的位置即可。

1. 顯示單頁面訪問量

   要顯示每篇文章的訪問量，復(fù)制以下代碼添加到你需要顯示的位置。

   算法：pv的方式，單個用戶點擊1篇文章，本篇文章記錄1次閱讀量。

   <span id="busuanzi_container_page_pv">
     本文總閱讀量<span id="busuanzi_value_page_pv"></span>次
   </span>
   

2. 顯示站點總訪問量

   要顯示站點總訪問量，復(fù)制以下代碼添加到你需要顯示的位置。有兩種算法可選：

   算法a：pv的方式，單個用戶連續(xù)點擊n篇文章，記錄n次訪問量。

   <span id="busuanzi_container_site_pv">
       本站總訪問量<span id="busuanzi_value_site_pv"></span>次
   </span>
   

   算法b：uv的方式，單個用戶連續(xù)點擊n篇文章，只記錄1次訪客數(shù)。

   <span id="busuanzi_container_site_uv">
     本站訪客數(shù)<span id="busuanzi_value_site_uv"></span>人次
   </span>
   

注：本地測試時數(shù)據(jù)會任意顯示，部署后即正常

3.部署腳本

在目錄 H:\HugoWebsite\blog 新建 deploy.sh ，在 Git bash 下運行：sh deploy.sh

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace with hugo -t <YOURTHEME>

# Go To Public folder
cd public
# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date` "

echo -e "\033[0;32m$msg\033[0m"

if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back up to the Project Root
cd ..

4. 添加網(wǎng)站運行時間

在想要添加的位置（基本是 footer 文件）加入以下代碼，其中開始運行的時間需要自行修改

<script>
    function siteTime() {
        var seconds = 1000;
        var minutes = seconds * 60;
        var hours = minutes * 60;
        var days = hours * 24;
        var years = days * 365;
        var today = new Date();
        var startYear = 2021;
        var startMonth = 3;
        var startDate = 27;
        var startHour = 19;
        var startMinute = 15;
        var startSecond = 11;
        var todayYear = today.getFullYear();
        var todayMonth = today.getMonth() + 1;
        var todayDate = today.getDate();
        var todayHour = today.getHours();
        var todayMinute = today.getMinutes();
        var todaySecond = today.getSeconds();
        var t1 = Date.UTC(startYear, startMonth, startDate, startHour, startMinute, startSecond);
        var t2 = Date.UTC(todayYear, todayMonth, todayDate, todayHour, todayMinute, todaySecond);
        var diff = t2 - t1;
        var diffYears = Math.floor(diff / years);
        var diffDays = Math.floor((diff / days) - diffYears * 365);
        var diffHours = Math.floor((diff - (diffYears * 365 + diffDays) * days) / hours);
        var diffMinutes = Math.floor((diff - (diffYears * 365 + diffDays) * days - diffHours * hours) /
            minutes);
        var diffSeconds = Math.floor((diff - (diffYears * 365 + diffDays) * days - diffHours * hours -
            diffMinutes * minutes) / seconds);
        if (startYear == todayYear) {
            //document.getElementById("year").innerHTML = todayYear;
            document.getElementById("sitetime").innerHTML = "已安全運行 " + diffDays + " 天 " + diffHours +
                " 小時 " + diffMinutes + " 分鐘 " + diffSeconds + " 秒";
        } else {
            //document.getElementById("year").innerHTML = startYear + " - " + todayYear;
            document.getElementById("sitetime").innerHTML = "已安全運行 " + diffYears + " 年 " + diffDays +
                " 天 " + diffHours + " 小時 " + diffMinutes + " 分鐘 " + diffSeconds + " 秒";
        }
    }
    setInterval(siteTime, 1000);
</script>
<span id="sitetime">載入運行時間...</span>

5. 圖片放大功能

方法一：

部分主題自帶了 lightgallery 效果，在配置文件設(shè)置為 true 即可。

方法二：

1. 加載jqury和fancybox文件，在博客文件footer.html中添加下面的文件

   <script src="https://cdn.jsdelivr.net/npm/jquery@3.4.1/dist/jquery.min.js"></script>
   
   <link rel="stylesheet"  />
   <script src="https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.js"></script>
   

2. 在博客文件中需要加載圖片的地方插入下面html代碼

   <a data-fancybox="gallery" href="圖片鏈接"><img src="圖片鏈接"></a>
   

九、總結(jié)

1. 可以將主題下相關(guān)文件復(fù)制到 blog 網(wǎng)站根目錄下，因為這樣可以直接渲染網(wǎng)站效果，而又不影響主題本身的內(nèi)容。

   主要是 themes\LoveIt\exampleSite 目錄下文件

2. 發(fā)布文章如果有參數(shù) draft ，記得將值設(shè)為 false，或者刪除 draft，不然會被認定為草稿只能本地運行而不能運行到網(wǎng)站上。

3. 基本上就是安裝 Hugo ，建站，下載主題，配置主題參數(shù)，然后部署就是了。

參考文章

【1】How To Build A Personal Website with Hugo | Matteo Courthoud

【2】使用Hugo和GitHub搭建博客. 折騰了幾天博客的框架終于搭建起來了。研究了一番之后，最終還是選擇使用Hugo和G… | by Félix | Medium

【3】如何利用 GitHub Pages 和 Hugo 輕松搭建個人博客？ - 知乎

【4】把博客從 Hexo 遷移到 Hugo - jdhao’s blog