Hugo+Codeberg免費架設靜態網站的使用者指南

包含個人電腦上使用Hugo靜態網站生成器的內容，以及上傳網頁程式碼到Codeberg，使用 Codeberg Pages 建立網站。

所有步驟是免費的，你將會得到一個簡單的個人網站。

1 Hugo&Codeberg Link to heading

「Hugo 」是一個由 Go語言撰寫的命令行界面靜態網站生成器，在 Apache License 2.0許可證下。

它可以輸入 Markdown 檔案生成html網頁，用於製作個人網頁。

「Codeberg」是一個德國非營利組織，營運開源軟體開發和程式碼託管服務。

2 製作網站的步驟 Link to heading

1.首先，使用文字編輯器、可以寫文章輸出MarkDown檔案的筆記軟體，例如：Obsidian。

2.執行 Hugo 命令生成和預覽網頁。

3.上傳網頁程式碼到Codeberg，使用 Codeberg Pages託管網站。

3 建立開發環境需要的工具 Link to heading

Hugo 支援 Windows、MacOS、Linux 作業系統。在安裝Hugo之前，你需要文字編輯器和 Git。我選擇 GNOME Gedit 和一個預裝 Git 的 Linux 發行版，Windows 或 MacOS 需要手動下載 Git 。

4 安裝 Hugo Link to heading

Linux

1.從 Hugo Github Releases下載 Hugo_extended 版本，在使用者目錄（舉例：/home/user）打開終端機輸入命令：

tar zxvf hugo*.tar.gz

sudo mv hugo /usr/bin

sudo chmod +x /usr/bin/hugo

2.完成安裝後，輸入 “hugo version” 指令檢查 hugo 版本。

hugo version

5 建立 Hugo 網站 Link to heading

1.添加一個新資料夾（例如：myblog）在使用者目錄，使用這個資料夾作為「Hugo 網站根目錄」，全部的原代碼和文章放在裡面。

2.打開終端機，輸入指令創建新網站： hugo new 它剛會生成 Hugo 網頁所需的基本檔案，把檔案放進 myblog 目錄。

hugo new site myblog

3.進入 myblog 目錄，初始化 Git。

cd myblog

git init

6 安裝 Hugo 主題 Link to heading

1.Hugo 主題官方網站提供許多主題，不同的主題有不一樣的界面和功能，我選擇 hugo coder 為例。

2.在 Hugo 網站根目錄 myblog 打開終端機，輸入 git submodule 命令下載 hugo coder 到theme 目錄。

bash
git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder

3.在 myblog 目錄找到 hugo.toml ，打開並編輯它添加設定：

# 使用主題
theme = "hugo-coder" # 就寫 hugo-coder，別亂動。
# 網站域名 （以我的網站為例）：
baseURL = 'https://mooncat.codeberg.page'
# 網站語言
languageCode = 'en'
defaultcontentlanguage = "en"
# 網站標題
title = 'Mooncat的個人網站'

[pagination]
pagerSize = 20

[service]

[markup.highlight] # 網站內程式碼的高亮規則
style = "github-dark"

[params]
  author = "Mooncat"
  info = "想了解我的話，就透過這個網站吧。"
  description = "Mooncat 的個人網站"
  avatarurl = "images/avatar.png" # 就是網站首頁那張圖，自己改連結，我建議放在 content/images，然後看你的檔名修改。
  #gravatar = "john.doe@example.com"

  faviconSVG = "images/favicon.png" # 網站小圖示，我也是放在 content/images
  
  since = 2025 # 網站創始年份

  enableTwemoji = true

  colorScheme = "auto"
  hidecolorschemetoggle = false

  # customCSS = ["custom.css"]
  # customSCSS = ["scss/custom.scss"]
  # customJS = ["js/custom.js"]

[taxonomies] # 這裡不要動
  category = "categories"
  series = "series"
  tag = "tags"
  author = "authors"

# Social links
# 這裡要放首頁個人圖片下面那些按鈕，怎麼寫請參考 hugo-coder 的官方文件
[[params.social]]
  name = "RSS"
  icon = "fa-solid fa-rss fa-2x"
  weight = 1
  url = "https://mastodon.social/@mooncat0.rss"
  rel = "alternate"
  type = "application/rss+xml"
[[params.social]]
  name = "Github"
  icon = "fa-brands fa-github fa-2x"
  weight = 2
  url = "https://github.com"

# Menu links
# 這裡能調整網站右上角出現的東西，weight 的數字越大越靠右（手機的話是靠下方） 
# url 就寫你給那個資料夾的命名
[[menu.main]]
  name = "文章"
  weight = 1
  url  = "articles/"
[[menu.main]]
  name = "關於"
  weight = 2
  url = "about/"
[[menu.main]]
  name = "標籤"
  weight = 3
  url = "tags/"
[[menu.main]]
  name = "聯絡我"
  weight = 4
  url = "contact/"
[[menu.main]]
  name = "連結"
  weight = 5
  url = "links/"
[[menu.main]]
  name = "本網站隱私政策"
  weight = 6
  url = "privacy/"

7 撰寫 MarkDown 文章 Link to heading

MarkDown 文章要放在 Hugo 網站根目錄 myblog 的 content 資料夾。

1.在 Hugo 網站根目錄 打開終端機輸入指令添加 index.md

hugo new /content/articles/helloworld/index.md

目錄名稱 /articles/helloworld 將變成這個文章的網址，你可以自訂目錄名稱 helloworld，裡面的 index.md 不可以重命名。

2.打開 index.md 開始編輯撰寫內容：

---
title: "我的第一個文章"
date: 2025-10-02T23:40:00+08:00
#lastmod: 2025-10-02 # 最後修改時間
draft: false

# 文章設定
toc: true         # 是否顯示目錄
math: false       # 是否啟用數學公式
code: true        # 是否有程式碼
---

Hello World!

哈囉！

最上面以分隔線圍起來的東西稱為 yaml frontmatter，你們可以自己研究要怎麼寫，分隔線下的 Markdown 文章要怎麼寫，改天我再寫一篇文章講解。

8 在本機預覽網站 Link to heading

在你的電腦上檢查網頁內容。

1.回到 Hugo 網站根目錄 myblog 打開終端機，輸入 hugo server 指令運行本機網站伺服器。

2.如果終端機顯示 Web Server is available at，意味著網站伺服器正在運行。

3.開啟瀏覽器，輸入 http://localhost:1313 可以看到網站的樣子。

4.在終端機按 CTRL+C 關掉這個測試網站。

5.如果運行指令 hugo 將會生成靜態網站在網站根目錄 myblog。

9 使用 Codeberg Pages 託管靜態網站 Link to heading

1.建立一個公開 repository 命名為 “pages” 在你的帳號。

2.上傳 Hugo 生成的靜態網頁檔案在 “pages” repository

3.訪問網址 https://{codeberg username}.codeberg.page

10 注意事項 Link to heading

建議使用不同瀏覽器去測試，避免你沒發現當使用其他瀏覽器的任何bug。