使用 hugo 來建立部落格

3-minute read
david
blog
golang • hugo

hugo 是 golang 寫的一個部落格框架，支援 markdown 語法，透過生成靜態網頁，靜態網頁可以快速的透過瀏覽器下載並呈現，大幅提升讀取速速，現在就來教學如何建立一個 Hugo 的部落格

安裝 Installation

Step 1: 安裝 Hugo

如果是 mac 的使用者，可以透過 homebrew 來安裝 hugo

brew install hugo
hugo version # 確認版本

Step 2: 建立一個新的網站 

hugo new site sitename # 替代 sitename 為自己想要的名字

Step 3: 加入一個 theme

Hugo 可以客製自己想要的版型， 這邊 有非常多的版型可以挑選，找到喜歡的版型之後可以透過 git submodule 來加入版型的模組，若之後有更新的版本可以直接透過 submodule 來 update 版本

cd sitename
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Step 4: 開始我們第一篇文章

Hugo 提供指令可以直接產生一篇文章框架

hugo new posts/my-first-post.md

範例：

---
title: "My First Post"
date: 2021-01-16T09:56:12+08:00
draft: true
---

Step 5: 啟動 Hugo server

直接在本地端啟動 server 來看成果如何

hugo server -D

應該會看到類似以下面結果顯示

Start building sites …

                   | EN
-------------------+-----
  Pages            |  1
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  5
  Sitemaps         |  1
  Cleaned          |  0

Built in 60 ms
Watching for changes in /Users/pqteru/app/blog/instacoding/{archetypes,content,themes}
Watching for config changes in /Users/pqteru/app/blog/instacoding/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

預設通常會是 http://localhost:1313/，在瀏覽器開啟之後就會出現我們的網站了

Step 6: 客製化版型及設定

在編輯器開啟 config.toml 檔案，填入最基本的設定

baseURL = "https://example.org/" # 替代成自己的網域，如果是放在 Github Pages 的話，就會是 `<USERNAME>.github.io`
languageCode = "en-us" # 預設為 en-us 若是中文可改成 zh-tw
title = "My New Hugo Site" # 網站名稱
theme = "ananke" # 使用的版型

Step 7: 產生靜態網頁

最後就是讓 hugo 來產生出靜態網頁，預設會產生一個 public 的 folder，裡面就會放我們在本機上看到的網頁所需要的靜態檔案，通常就是一堆 html, css, js 檔案等

hugo -D 
# -D, --buildDrafts include content marked as draft

hugo command 的參照

Hosting on GitHub Pages

使用 Github Pages 的服務把網站放到 <USERNAME>.github.io 上

  1. 首先到 github 上面開兩個 repositories

    • 一個是放 project 的地方，建立一個 <YOUR-PROJECT> 的 repo，可以是 private
    • 另一個則是放 hugo 產生的靜態網頁的地方，需要是 public，repo 名稱需要命名為 <USERNAME>.github.io

  2. 把建立好的 <USERNAME>.github.io repo，透過 git submodule 來加入模組

    如果已經存在 public 目錄的話，需要先把它刪除 rm -rf public

    git submodule add -b main https://github.com/pqteru/pqteru.github.io.git public

    檢測我們目前的設定是否有兩個 submodules

    git submodule status

# output
# 360acf1b71db6fa3f500161d1f0e8e8d345499a2 public (heads/main) // 指向 `<USERNAME>.github.io` repo
# dbe21a7fdf0d5556de5b2f2f8bdf4f64228ca241 themes ... // 指向 theme 的 repo

  3. 執行 hugo 指令在 public 產生靜態網站，確認 config.toml 的 baseURL 是否有指向正確的網域位置 <USERNAME>.github.io

寫 script 來自動化執行更新

直接在專案內建立一支 deploy.sh 的 script，把權限設定為可執行權限 chmod +x deploy.sh

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# 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)"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin main

在終端機上執行

./deploy.sh "Your optional commit message"

會把更新的 commits 直接 push 到 <USERNAME>.github.io repo 上，因為我們有兩個 repo，這支 script 只更新 public 這個 submodule repo，自己專案 <YOUR-PROJECT> 的 repo 也別忘了 commit & update 囉

大功告成，最後直接連線到 https://<USERNAME>.github.io 就能看到我們的部落格了，如果網站尚未更新，有可能是瀏覽器的 cache 可以開無痕模式或清空 cache 來檢視。

comments powered by Disqus