Update: January 12, 2025

在現在好像沒有自己的品牌是一件很稀有的事( 比日本製的壓縮機還要稀少 )。為了解決大家的煩惱,這是一篇帶你使用 Hugo + Github Pages 從零開始製作個人網站的教學!

那我們就直接開始!

1. 安裝 Hugo

本章節按照 Hugo 官方推薦步驟 進行安裝。

  • MacOS

    Step 1.

    使用 Homebrew 進行安裝,若還未安裝 Homebrew 請先自行安裝。進入 Terminal (終端機) 輸入以下指令:

    brew install hugo
    

    Step 2.

    輸入以下指令已檢查是否安裝成功:

    hugo --version
    

    若有出現版本資訊即代表安裝成功。

2. 套用主題

Step 1.

官方的主題網站 瀏覽並選擇自己喜歡的主題,本文以 PaperMod 為例。

Step 2.

先在本地創建一個新的 Hugo 網站。

hugo new site MyFreshWebsite --format yaml
# 將 MyFreshWebsite 替換為自己網站的名稱
  • --format yaml:將 hugo 的設定檔更改為 yaml 格式。

Step 3.

安裝 PaperMod 主題,這邊我按照最簡單的 官方的 Method 1(git clone):

  • 安裝

    在終端機中進入自己創建的網站 MyFreshWebsite 的資料夾中輸入:

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

    在終端機中進入自己創建的網站 MyFreshWebsite 的資料夾中輸入:

    cd themes/PaperMod
    git pull
    

Step 4.

最後,在網站的設定檔 config.yaml 中將 Theme 指定為 PaperMod。

theme: ["PaperMod"]

現在,只要在 Terminal 輸入下列指令,並開啟 terminal 給的網址,就可以看到預設的網站了。

hugo server -D
  • -D:代表會顯示仍為 草稿 的文章。

3. PaperMod Config 設定

當一打開網站,你會發現長的跟 PaperMod 官網顯示的完全不一樣,你可能會覺得被騙了,但其實只要花點時間設定就沒問題了!

關於 PaperMod 主題的設定,可以參考 官方的 wiki,所有 features 都是在 config.yaml 裡設定。

Home page

如果要設定一般的 Home-Info Mode 網站主頁,範例設定如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
params:
  homeInfoParams:
    Title: Hi there wave
    Content: Can be Info, links, about...

  socialIcons: # optional
    - name: "<platform>"
      url: "<link>"
    - name: "<platform 2>"
      url: "<link2>"

而如果想要將網站製作成 Portfolio ,也可以選擇更改為 Portfolio Mode

params:
  profileMode:
    enabled: true
    title: "<Title>" # optional default will be site title
    subtitle: "This is subtitle"
    imageUrl: "<image link>" # optional
    imageTitle: "<title of image as alt>" # optional
    imageWidth: 120 # custom size
    imageHeight: 120 # custom size
    buttons:
      - name: Archive
        url: "/archive"
      - name: Github
        url: "https://github.com/"

  socialIcons: # optional
    - name: "<platform>"
      url: "<link>"
    - name: "<platform 2>"
      url: "<link2>"
menu:
  main:
  - identifier: about
      name: About
      url: /about/
      weight: 10
    - identifier: blogs
      name: Blogs
      url: /blogs/
      weight: 20
    - identifier: search
      name: Search
      url: /search/
      weight: 80
    - name: Tags
      url: tags/
      weight: 90
    - identifier: archives
      name: Archives
      url: /archives/
      weight: 99
VariableDescription
identifier在 content 中資料夾或是需要的功能名稱
name在 navigation bar 所顯示的名稱
url該分頁在網址列的代表名稱
weight在 navigation bar 顯示的前後順序,數字越小越前面

Archive Layout

在 content 資料夾建立一個 archives.md 檔案,並將下列內容加入:

---
title: "Archive"
layout: "archives"
url: "/archives/"
summary: archives
---

Comment

(待更新,敬請期待)

官方範例

config.yml

4. 建立文章

方法一、

在 terminal 使用

hugo new content content/<folder_name>/post.md

方法二、

比較簡單也比較好管理,直接在 content 中要建立文章的資料夾中,建立存放該文章的資料夾,並在該資料夾建立 index.md(有點饒口)

.
├── config.yml
├── content/
│   ├── archives.md
│   └── posts/
│       └── first_post/
│           └── index.md
├── static/
└── themes/
    └── PaperMod/

5. GitHub Pages 部署

Step 1.

建立一個 GitHub repository,repository 的名字可以隨意命名

Step 2.

將你的本地檔案 push 到剛剛創建的 GiuHub repository

Step 3.

進入你的 GitHub repository,選擇 Settings > Pages

在畫面中間的 Build and Deployment 段落可以看到 Source,我們將 Source 設定為 GitHub Actions

Step 4.

在本地 repository 新增一個檔案

touch .github/workflows/hugo.yaml

並將下列內容複製貼上到你新增的.github/workflows/hugo.yaml,依照你的需求,有可能需要更改 branch namehugo version

.github/workflows/hugo.yaml
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.137.1
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - name: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
          TZ: America/Los_Angeles
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

最後,將變更提交並推送到 GitHub。

Step 5.

回到 GitHub repository 的 main menu,選擇 Actions 就會看到剛剛提交的 commit 變成一個橘色的 workflow,代表我們的網站正在交給 GitHub Pages 部署。

等到變成綠色,代表網站部署成功!

6. 自訂域名

Step 0.

購買域名,可到例如 namecheapGoDaddy 等網站購買。

Step 1.

進入網站的 GitHub repository,點選 Settings > Pages

並在 Custom Domain 中,設定購買的域名。接著,通常沒有在域名購買的網站上設定過,會顯示失敗。

Step 2.

到域名購買商的網站,幫你購買的域名設定 DNS, A record 以及 CNAME

  • A record

    host 或 record name 是 @

    185.199.108.153
    185.199.109.153
    185.199.110.153
    185.199.111.153
    
  • CNAME

    host 或 record name 是 www

    <your github account name>.github.io
    

當設定完成後,過一下 GitHub Pages 的自訂域名就設定完成了!

7. Tips

Collapsible Section

Discussion

創建 /layouts/shortcodes/details.html,並將下列加入其中:

<details>
  <summary>{{ (.Get 0) | markdownify }}</summary>
  {{ .Inner | markdownify }}
</details>

接下來就可以在文章中使用 details ,如下:

{details title="Learn More" >} <----- 每個大括號外面都要再加一個大括號
Collapsed text
{</details >}

參考資料