用HUGO和github製作靜態網站

動態網站雖然互動性極高，但很多時候網頁只是單純拿來乘載資訊，沒那麼多互動性其實也沒關係。這裡簡單介紹可以用markdown格式，直接利用HUGO製作成網頁，再利用github免費託管網頁的方法

安裝HUGO

MAC用戶直接用brew install。這裡介紹linux，以及透過windows subsystem linux 2 (WSL2)的安裝方法，尤其windows用戶，WSL2真的是好東西啊。

簡單說，參考原廠說明 Linux |Hugo (gohugo.io) ，有兩種安裝方法，分別是簡易版、與純手工安裝版

簡易版

sudo apt install hugo

純手工安裝

pre-required: GCC

記得要有gcc，不太挑版本，Ubuntu預設的就可以。但WSL2的Ubuntu通常沒有，所以需先更新apt，再自己裝:

# 更新apt
sudo apt update
# 裝gcc
sudo apt install build-essential

pre-required: GO

手動裝的方法: 下載、解壓縮、把路徑加入.bashrc、在.bashrc設定 GOPATH 與 GOBIN ，這樣才知道透過GO 裝的東西會裝去哪裡 (未來透過 GO 安裝的執行檔就在 GOBIN 的位置)

# 下載
wget https://go.dev/dl/go1.19.4.linux-amd64.tar.gz

# 解壓縮
tar zxvf go1.19.4.linux-amd64.tar.gz

# 修改.bashrc
cd 
vim .bashrc

# 把路徑加入.bashrc
PATH=${PATH}:/home/XXXXXXXX/software/GO/1.19.4/bin

# add GOPATH and GOBIN PATH to .bashrc
GOPATH="/home/XXXXXXXX/go"
GOBIN="/home/XXXXXXXX/go/bin"

# 改完之後記得source .bashrc 才會生效
source .bashrc

安裝HUGO

我選擇透過 GO 安裝:

go install -tags extended github.com/gohugoio/hugo@v0.109.0

安裝完畢之後，執行檔會在上面設定的 GOBIN (/home/XXXXXXXX/go/bin)裡面，記得把HUGO執行檔再加入PATH裡:

# 修改.bashrc
cd 
vim .bashrc

# 把路徑加入.bashrc
PATH=${PATH}:/home/XXXXXXXX/go/bin

# 改完之後記得source .bashrc 才會生效
source .bashrc

然後在terminal 輸入

$ hugo version
hugo v0.109.0+extended linux/amd64 BuildDate=unknown

看到顯示 hugo v0.109.0+extended linux/amd64 BuildDate=unknown 就是成功啦

設定github SSH key

建議使用ssh key來連接，別再暴露自己的密碼啦!!

# 雙引號裡面填入自己的github email
ssh-keygen -t ed25519 -C "寫入你的github註冊email"

# PS. ed25519 是加密的方法，不是帳號也不是密碼

產生出來的公鑰與私鑰通常會放在 /home/XXXXXXXXXXX/.ssh/id_ed25519.pub ，記得把這串公鑰貼到github上面，這樣未來就不用透過密碼連接了。

開啟一個github repository

原則上只要建立一個名字叫做 <USERNAME>.github.io 的repository 來盛放 HUGO 做好的網頁資料就好。記得這個命名原則有限制，好像不能亂取名字? HUGO 官方的說法是有兩種做法，第一種就是用使用者名稱，第二種可以利用USERNAME與project名稱:

User/Organization Pages (https://<USERNAME|ORGANIZATION>.github.io/)
Project Pages (https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/)

詳細請看: https://gohugo.io/hosting-and-deployment/hosting-on-github/

使用HUGO

Step 1. 利用HUGO開一個資料夾，放所有會用到的東西

假設想要開一個資料夾，名字是 myblog ，而且設定檔以yaml 格式顯示:

# hugo new site <name of site> -f yml
hugo new site myblog -f yml

這時候會在 myblog 資料夾裡出現這些資料夾與檔案:

archetypes		# 這是markdown的範例檔頭，請自己手工做，或複製theme做好的
assets  
config.yml		# 這是設定檔
content  		# 寫好的markdown都放這裡
data  
layouts  
public			# 這邊是hugo從content markdown做好的所有網頁資訊
resources  
static  
themes			# 放下載好的主題

Step 2. 找個喜歡的網頁主題 (theme)放進theme資料夾

可以在這裡找，看看裡面的範例喜不喜歡，看GitHub Stars數值高不高，看使用說明書寫的簡不簡單，夠選擇障礙很久了

各式各樣theme: Complete List |Hugo Themes (gohugo.io)

舉例來說，我以PaperMod |Hugo Themes (gohugo.io) 為範例:

Step 2.1 下載theme

記得在 myblog/theme 資料夾裡執行這動作，因為要把東西放進 theme 資料夾

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

這時候就可以測試看看主題是不是跟想像的一樣:

hugo server

就可以透過瀏覽器看看自己部屬的網頁對不對了。而且就算是WSL開啟網頁，也可以透過windows的瀏覽器直接看!!!!! 實際用法是打開瀏覽器，輸入http://localhost:1313/ 就可以啦。

Step 2.2 Add theme to archetypes

這是為了讓接下來的文章能按照一定的格式顯示，所以需要一個模板，所以我參考 Installation | Update | PaperMod (adityatelange.github.io) ，最後面有介紹他使用的。簡單說，在 archetypes 資料夾建立一個新的檔案 post.md ，再把下面這些東西貼上去，之後就可以直接套用了

記得也可以自己改阿!!

vim archetypes/post.md

## add following texts:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
# weight: 1
# aliases: ["/first"]
tags: ["first"]
# add tags here!!!!!
author: "Me"
# author: ["Me", "You"] # multiple authors
showToc: true
TocOpen: false
draft: false
hidemeta: false
comments: false
description: "Desc Text."
canonicalURL: "https://canonical.url/to/page"
disableHLJS: true # to disable highlightjs
disableShare: false
disableHLJS: false
hideSummary: false
searchHidden: true
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: true
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: true
cover:
    image: "<image path/url>" # image path/url
    alt: "<alt text>" # alt text
    caption: "<text>" # display caption under cover
    relative: false # when using page bundles set this to true
    hidden: true # only hide on current single page
editPost:
    URL: "https://github.com/<path_to_repo>/content"
    Text: "Suggest Changes" # edit text
    appendFilePath: true # to append file path to Edit link
---

Step 2.3 改config.yml

這是網頁的位置資訊，與使用的theme資訊、網頁名稱等等，記得要改阿。然後#之後的東西不要留

baseURL: https://xavierzheng.github.io	# 改成自己的網頁名字
languageCode: zh-tw						# 文字碼
title: Biology and computer science		# 網頁名稱
theme: PaperMod							# 使用的theme的名字

Step 3 寫markdown啦

使用以下指令，利用剛剛創好的 archetypes/post.md 當作模板，寫文章啦

hugo new --kind post posts/TEST.md

這時候會利用模板 --kind post，在 content 資料夾底下，開一個檔案 posts/TEST.md。也就是在 content 資料夾底下，會多一個posts 資料夾，裡面放想寫的markdown。

內容自己寫好貼進來吧。但檔頭部分，可以修改tags，讓之後文章好搜尋。也可以添加description或summary，這段文字會出現在主網頁內，可以當這篇文章的一句話摘要

tags: ["first", "GO", "info", "不要再寫啦"]
description: "XXXXX"
summary: "XXXXX"

Step 3.1 如果要插入圖片

hugo 預設圖片資料存在 static資料夾，所以只要把typora或其他markdown editor創造出來的圖片資料夾與圖片搬到 static 資料夾底下，就可以直接在網頁上顯示了。

這是資料夾結構

static
	|- TFBindingSite.assets/
		|- clip_image002.jpg
		|- clip_image002.png
		......

只要把markdown裡面的圖片位置改成

![String](/TFBindingSite.assets/clip_image002.jpg)

就直接可以在typora裡面顯示，也可以正確的被hugo處理成網頁能看懂的格式啦

Step 4 預覽

透過HUGO把markdown轉成網頁，並在localhost用網頁瀏覽器先看看有沒有問題。這就是HUGO最厲害的地方，編譯速度超快，通常不用1秒!!!

hugo server -D

就可以透過瀏覽器看看自己部屬的網頁對不對了。而且就算是WSL開啟網頁，也可以透過windows的瀏覽器直接看!!!!! 實際用法是打開瀏覽器，輸入http://localhost:1313/ 就可以啦。

Step 5 轉換markdown to html

只要簡單一行指令

hugo

東西就更新到public資料夾啦

Step 6. 放上github託管

上面做完的網頁資料都在 public 資料夾，所以只需要把 public 資料夾裡面的內容放進github就可以，記得不要把 public 資料夾一起放上去，只能放資料夾裡面的東西!!

# 一定要進入到public底下再開始git init
cd public

# 開始git (這個步驟只有第一次才需要做)
git init

# 加全部東西進入git
git add .

# 推到local
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:xavierzheng/xavierzheng.github.io.git
git push -u origin main

記得要改 git@github.com:xavierzheng/xavierzheng.github.io.git 阿

這樣就完成blog啦

幫我衝一下點閱率: Biology and computer science (xavierzheng.github.io)

每次寫文章只需執行Step 3、Step 4、Step 5、Step 6就可以

其餘步驟通通不用做!!

當然也可以簡單做成一個執行檔，未來直接執行它就可以啦 ./git_push.sh

#!/bin/bash

set -e -u -o pipefail

hugo

cd public # 記得改成放網頁的地方啊
git add .
git commit -m "first commit"
git branch -M main
git push -u origin main