起頭並不難：用 Hugo 架站的第一步
目錄
誰適合讀這篇 #
這是給
- 會一點程式操作跟 git
- 只需要靜態網頁或前端（client side）動態的功能
- 已經決定要用 Hugo 架站，但連第一步怎麼開始都不知道
而不是給
- 沒有程式概念的
- 需要複雜後端互動像是後端資料庫、運算之類的
Hugo 架站概念 #
- 在本地 local 架 Hugo，寫好網站內容
- 放到 Github 上
- 找網路主機商去抓你的 Github，那邊也有裝 Hugo 把你的內容部署成網站
網域 domain (非必要) #
每年花點小錢買個屬於自己的網域，不但能架站建立自己的品牌，也可能可以建立其他的服務。我是用 Cloudflare Registrar，不過當然也可以選其他的網域註冊商
話說回來，網路主機商像是 Cloudflare Pages 等等也都提供他們自己的域名，免費，所以不在意的話也是不用自己的！
Github Repo #
Hugo 眾多特性之一是挑選好佈景主題以後，你就專心寫內容寫 Markdown 純文字文件。不是手刻 html，也不是被綁在某資料庫或藏在某圖形介面的背後而摸不著搬不走
因此，大家自然想要用 Github 維護自己的內容做版本控制。只要在 Github 開一個新的 repository，就算是私人的也沒問題，就可以把內容放在上面，讓 Netlify 或 Cloudflare Pages 之類的去讀你的內容，建立好網站
Hugo - 本地端 #
安裝 Hugo 跟 git #
在自己的電腦照著 https://gohugo.io/installation/ 上面說的安裝即可
挑 theme 佈景主題 #
網路上有很多大家寫好的 theme (佈景主題)，他們把排版外觀都設計好了，你只要挑一個套用就可以
https://themes.gohugo.io/ 列了很多主題，以 Github Stars 排序（就想成熱門度吧）。如果點右邊的分類，裡面的列表則是以最後更新日期排序。每個點進去或多或少有截圖甚至實際長相的 demo。我覺得文件齊全度很重要，然後外觀挑個順眼的就好。
這個網站目前是用 Congo，我有另一個網站像文件型的用 Docsy，還有像 Doks 也都是不錯的選擇
建立網站框架 #
安裝 Hugo 以後，用 hugo 指令建一個網站的目錄架構（自己 mkdir 也是沒問題…）
$ hugo new site <新目錄名字>
他單純幫你建一些空的目錄，跟最最基本的設定檔
$ ls
archetypes assets content data hugo.toml layouts static themes
$ cat hugo.toml
baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
安裝 theme #
Hugo theme 有三種安裝方式
- 直接 copy theme 檔案：以後很難升級，但想自己魔改的話很容易
- 用 Git submodules 拉進來：能追蹤 theme 的升級，也算是能自己改動
- 當作 Hugo Module (一個 Go Module) 安裝：升級 theme 比較容易，不過就無法改動內部的程式
一個好的 theme 應該有挖洞讓你不用改他的程式碼，而是用新增檔案或蓋掉的方式去客製化。我自己目前是用 Hugo module 的方法。如果想看 git submodule 的方法可以看 Hugo 官方文件
以 Hugo Module 方法安裝 theme 的步驟如下（根據 https://gohugo.io/hugo-modules/use-modules/ ）
準備動作
$ cd <剛建的網站目錄>
# 可以先 init，不一定要先創 repo
$ hugo mod init github.com/<你的github帳號名>/<repo名>
在設定檔 hugo.toml 加下面內容；你選擇的佈景主題應該要提供給你 path
[module]
[[module.imports]]
path = 'github.com/jpanther/congo/v2'
跑一次 hugo server，這時 theme 會下載，同時在本地架好站
$ hugo server
go: no module dependencies to download
hugo: downloading modules …
go: downloading github.com/jpanther/congo v1.6.4
go: downloading github.com/jpanther/congo/v2 v2.7.6
go: added github.com/jpanther/congo/v2 v2.7.6
hugo: collected modules in 6452 ms
...
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
就像上面說的，你可以在你的電腦開瀏覽器，開自己本地端 (http://localhost:1313) 就可以看到網站囉！
網站設定檔 #
雖然有非常非常多的設定可調，不過在最一開始至少把 hugo.toml 裡的內容 baseURL 改成你的網域名。例如：
baseURL = 'https://ywctech.net/'
之後的設定在 Hugo 的 https://gohugo.io/getting-started/configuration/ ，還有佈景主題也可能有自己的設定
推上 Github repo #
先在 Github 創一個 repository (就算是 private 也可以)，然後就是正常 github 操作，把本地端的目錄 git 化，之後能 push 上去
在 push 之前，建議先加 .gitignore 檔案，內容如下
# hugo site
resources/
.hugo_build.lock
然後把本地目錄 git 化
$ git init
$ git add .
$ git commit -m "Initialize a hugo site"
$ git branch -M main
# 可在你的 Github repo 頁面找到
$ git remote add origin [email protected]:<你帳號名>/<repo 名>.git
$ git push -u origin main
部署網站到服務商 #
有一些服務商能把你的網站 host 在他們那邊，免費！因為是靜態的網頁對他們來說負擔比較小。當然也有些限制，不過還滿寬鬆的。例如 Cloudflare pages 就提供流量無上限，一個月讓你更改 500 次
https://gohugo.io/hosting-and-deployment/ 這一頁列了很多選擇。我自己是選 Cloudflare Pages，下面的解釋就會以這個為例子（當然他們會改版，這是 2024 一月的例子，保險起見還是看 cloudflare 的官方文件 ）
建立新的 “Pages” #
在 https://dash.cloudflare.com/ Sign up 建立帳號後，在那裡選 Worker & pages > Create application > Pages > Connect to git
“Connect to git” 按下去，連結 Github，然後你會被 Github 問是否要授權給 Cloudflare Pages 讀你的 repo
設定部署 #
選擇好 github repo 以後，下一步是告訴 Cloudflare Pages 你的網站是用什麼架的 – 不是只有 Hugo 才能產生網站
所以選擇 git repo branch 是 main (除非你要其他的 branch)，然後下面選擇 Hugo 框架，把指令改成 git fetch --unshallow && hugo --minify
再進到下一步，他會根據你的指令，去你的 Github repo 抓資料下來建立網站。在那一頁待一下看看有沒有成功
成功的話，之後在 Workers & pages > Overview 就有你的網站專案，每次 github repo 更新，cloudflare 會跟著自動更新你的網站，不用做任何事情！
你在專案列表點 “Visit site” 就可以看到你的網站！不過網址是 .page.dev 結尾，可能不是你要的？
自訂網域 #
在專案裡面你可以選 “Custom Domains” 把你的網域接到這網站
- 如果你的網域註冊商也是 Cloudflare，填網域按按下一步，過一會就有了
- 如果不是的話就照著 https://developers.cloudflare.com/pages/configuration/custom-domains/
如果一切順利，你的網站已經上線囉！不過現在應該只是個空殼
接下來就是 加頁面 / 目錄結構，favicon / opengraph，sitemap，Google search console / SEO，Google Analytics 等等
頁面內容跟目錄架構在 theme 的文件應該會有，也可參考 Hugo 萬用的 https://gohugo.io/content-management/