附錄 A：大學教師的 GitHub Pages 架站與版本管理入門

從檔案總管的概念理解 Repository、Commit、Main 與 Commit to Main

1 附錄 A：大學教師的 GitHub Pages 架站與版本管理入門

這份附錄以彼得潘在 Medium 上的〈使用 GitHub Pages 架設網站初體驗〉作為入門情境：先用 AI 做一個 HTML，接著建立 GitHub repository，把 HTML 上傳，最後用 GitHub Pages 讓它變成公開網站。那篇文章的優點是把流程講得很直覺：做網頁、建立 repository、上傳檔案、打開 Pages、補上 index.html 首頁。

這裡要做的，是把那個流程更新成目前 GitHub 官方文件所建議的說法，並補上教師最容易卡住的管理概念：Repository 是什麼？Commit 是什麼？Main 是什麼？「Commit to main」到底是在做什麼？這些詞如果不先理解，後面的操作會看起來像一堆工程師黑話。

1.1 一、先用「檔案總管」理解 GitHub

多數老師熟悉 Windows 檔案總管或 macOS Finder。你知道一門課可以有一個資料夾，裡面放課綱、投影片、圖片、學生作業、講義 PDF。GitHub 可以先理解為「有版本管理能力的雲端資料夾」。

差別在於，GitHub 不只是存放檔案。它還會記錄每一次重要變更，知道誰改了什麼、什麼時候改、為什麼改。當你把一個課程網頁放到 GitHub 上，GitHub Pages 還能把這個資料夾中的 HTML 變成公開網站。

檔案總管概念 GitHub / Git 概念 管理上的意義
一個課程資料夾 Repository 一個可追蹤、可協作、可發布的專案空間
儲存一個檔案 Commit 對一組變更做正式版本紀錄
資料夾的主要版本 Main branch 對外採用的正式版本
建立副本試改 Branch 不影響正式版的實驗版本
把本機資料夾上傳雲端 Push 把本機版本送到 GitHub
把雲端最新版抓回本機 Pull 把 GitHub 上的新版本帶回電腦
網頁首頁檔案 index.html 使用者進入網站時預設看到的頁面
公開網址 GitHub Pages 將 repository 內容變成可瀏覽網站

這樣看，GitHub 的核心其實不是程式，而是「把知識作品的版本、發布與協作流程制度化」。

1.2 二、幾個必要名詞

1.2.1 1. Repository

Repository 常被簡稱為 repo。對教師來說，可以把它想成「一門課或一個教材專案的總資料夾」。裡面可以放 HTML、圖片、CSS、PDF、Markdown、課程資料、學生版講義等。

Repository 比一般雲端資料夾多一件事：它會保留版本歷史。也就是說，當你修改 syllabus、替換圖片或新增課程卡片時，GitHub 可以知道這些變更是在哪一次 commit 中加入的。

1.2.2 2. Commit

Commit 是一次正式的版本紀錄。它不是單純按下「儲存」，而是把目前一組變更包成一個可追溯的節點。

如果用課程管理來比喻，commit 像是在課程文件上寫下：「這一版新增了第 7 週的課前作業，並修正期末評分比例。」日後你要查為什麼課綱變了，就可以回到這筆 commit。

Commit 通常有一段訊息，例如：

Add CM108G 1151 syllabus and course cards

這段訊息的管理意義是：讓未來的自己和共同作者知道這一次改動的目的。

1.2.3 3. Main

Main 是 repository 的主要分支，也就是正式版本所在的路線。以前很多專案使用 master，現在多數新 repository 預設使用 main。

對教師來說，可以把 main 想成「目前正式對外發布的版本」。你可以有草稿分支，也可以在本機試改，但如果 GitHub Pages 設定從 main 發布，那麼推送到 main 的內容就會成為網站的來源。

1.2.4 4. Branch

Branch 是分支。它像是在正式課程資料夾旁邊開一份實驗稿。你可以在 branch 上大幅改版，等確認沒問題後，再把它合併回 main。

對不熟 Git 的老師來說，初期可以先不用 branch，只要使用 main。但要理解它的管理價值：branch 讓你能保留正式版，同時進行實驗。

1.2.5 5. Commit to main

「Commit to main」的意思是：把目前變更做成一筆 commit，並且放在 main 這條正式分支上。

如果你是在 GitHub 網頁介面上按下 Commit changes，並且目標分支是 main，那就等於把這次檔案變更正式記錄到 main。若你的 GitHub Pages 設定是從 main 的根目錄或 /docs 發布，這筆 commit 之後通常會觸發網站重新部署。

這句話的管理意義是：你不是隨手改檔案，而是在正式版本線上留下新的制度紀錄。

1.2.6 6. Push

Push 是把本機電腦上的 commit 送到 GitHub。若你只在自己的電腦 commit，但沒有 push，GitHub 網站看不到這次變更，GitHub Pages 也不會更新。

可以把 push 理解為「把本機正式版本同步到雲端正式庫」。

1.2.7 7. GitHub Pages

GitHub Pages 是 GitHub 提供的靜態網站發布功能。GitHub 官方文件說明，GitHub Pages 可以從新的或既有 repository 建立網站；你需要有 repository，並建立入口檔案，例如 index.html、index.md 或 README.md。GitHub 也提醒，Pages 網站會公開在網路上，因此不要把敏感資料放進要發布的 repository。

1.3 三、目前官方流程：用 GitHub Pages 發布一個靜態網站

以下流程適合老師發布課程介紹頁、個案講義、學生作業說明、工作坊材料、公開成果展示。

1.3.1 步驟 1：準備你的網頁資料夾

你至少需要：

my-course-site/
  index.html
  assets/
    hero.png
    style.css

index.html 是首頁。沒有它，使用者打開網站根目錄時很容易看到 404。這也是 Medium 文章中特別提到的重點：網站要有首頁，就需要 index.html。

管理意義：首頁是對外承諾。它告訴學生或讀者，這個網站的入口、課程定位與導覽方式是什麼。

1.3.2 步驟 2：建立 GitHub repository

登入 GitHub 後，按右上角 +，選擇 New repository。GitHub 官方文件說明，如果使用 GitHub Free，要用 GitHub Pages 發布一般 repository，repository 通常需要是 public；若是 Pro、Team、Enterprise 等方案，私有 repository 也可依方案使用 Pages。

Repository 命名有兩種常見方式：

類型 Repository 名稱 網址型態 適用情境
使用者或組織首頁 <username>.github.io https://<username>.github.io/ 個人首頁、實驗室首頁
專案網站 任意專案名，例如 cm108g-1151 https://<username>.github.io/<repo>/ 單一課程、講義、活動頁

教師若只是要發布一門課，通常用專案網站就足夠。

1.3.3 步驟 3：把檔案放進 repository

有兩種做法。

第一種是用 GitHub 網頁介面：

  1. 進入 repository。
  2. 點 Add file。
  3. 選 Upload files。
  4. 把 index.html 和 assets 裡的檔案上傳。
  5. 在下方填寫 commit message。
  6. 選擇 commit 到 main。
  7. 按 Commit changes。

第二種是用 Codex 或本機 git：

git add index.html assets/
git commit -m "Add course site"
git push

對不熟 git 的老師，第一次可以用網頁介面。之後若檔案多、圖片多、HTML 需要反覆修正，使用 Codex 協助 git 流程會比較穩定。

1.3.4 步驟 4：設定 GitHub Pages 發布來源

進入 repository：

  1. 點 Settings。
  2. 在左側找到 Pages。
  3. 在 Build and deployment 的 Source 選擇 Deploy from a branch。
  4. 在 Branch 選 main。
  5. Folder 選 / (root) 或 /docs。
  6. 按 Save。

GitHub 官方文件指出，如果你不需要特殊建置流程，從某個 branch 與 folder 發布是建議做法。你可以指定來源 branch，也可以指定根目錄 / 或 /docs 作為發布來源。只要變更被 push 到該來源，GitHub Pages 就會發布來源資料夾中的內容。

1.3.5 步驟 5：等待部署並檢查網址

GitHub 官方文件提醒，push 之後網站變更最多可能需要約 10 分鐘才會發布。你可以到 Settings > Pages 點 Visit site 檢查。

如果看不到網站，先檢查：

  1. repository 是否 public，或你的方案是否允許私有 Pages；
  2. Pages 的 source 是否正確；
  3. index.html 是否在發布來源資料夾最上層；
  4. 檔名大小寫是否正確；
  5. 圖片路徑是否正確，例如 assets/hero.png；
  6. 是否剛 push，GitHub Pages 還沒部署完成。

1.3.6 步驟 6：日後更新網站

每次改課程頁時，流程都是：

  1. 修改 HTML、圖片或內容。
  2. 檢查本機頁面是否正常。
  3. commit 這次變更。
  4. push 到 GitHub。
  5. 等 GitHub Pages 重新部署。
  6. 打開線上網址檢查。

如果你對 Codex 說「commit 到 main」，意思通常是：請 Codex 把目前工作資料夾中這次相關檔案加入版本紀錄，建立 commit，放在 main 分支，必要時 push 到 GitHub。這也是本專案中 CM108G 課程頁最後發布的方式。

1.4 四、教師最容易誤解的地方

1.4.1 1. GitHub 不是 Google Drive

Google Drive 或 OneDrive 主要處理檔案同步。GitHub 處理的是版本紀錄、協作流程與發布。你可以把 GitHub 想成比較嚴謹的雲端資料夾，但它不是為了讓你隨意拖拉檔案而設計，而是為了讓每一次變更可追溯。

1.4.2 2. Commit 不等於網站已更新

Commit 只是建立版本紀錄。如果 commit 還在本機，GitHub 不會知道。要 push 到 GitHub，GitHub Pages 才可能重新部署。

1.4.3 3. Main 是正式線，不是所有草稿都該直接放進去

初學者可以先用 main，但一旦網站對學生公開，就要小心。還沒確認的版本最好先在本機或分支測試，不要直接改壞線上頁面。

1.4.4 4. GitHub Pages 只適合靜態網站

GitHub 官方文件說明，GitHub Pages 不支援 PHP、Ruby、Python 這類伺服器端語言。換句話說，它很適合課程頁、講義、個案、互動小工具、靜態圖表，但不適合需要登入系統、資料庫或後端運算的正式平台。

1.5 五、管理上的意義：GitHub 其實是一套教材治理制度

對教師來說，GitHub 的價值不只是「免費架網站」。它更像是一套教材治理工具。

GitHub 動作 管理意義
建立 repository 為一門課或一份教材建立正式工作空間
寫 README 交代專案目的、使用方式與維護規則
Commit 對每一次重要改版留下決策紀錄
Push 把本機成果同步到共同版本庫
Main 定義目前正式版本
Branch 允許試驗而不破壞正式版
Pull request 在發布前進行審查與討論
Issues 把待修項目、學生回饋、下一版需求變成工作清單
GitHub Pages 將教材變成可公開分享的網站

如果用管理學語言說，GitHub 把「教材製作」從個人桌面上的檔案活動，轉成有版本、有責任、有發布節奏的知識工作流程。

1.6 六、一個教師可以採用的最小流程

第一次使用時，不需要學完整 git。

  1. 用 Codex 或 ChatGPT 產生一個 HTML 課程頁。
  2. 確認本機打開正常。
  3. 建立 GitHub repository。
  4. 用 GitHub 網頁介面上傳 index.html 與 assets/。
  5. Commit to main。
  6. 到 Settings > Pages 設定 Deploy from a branch、main、/(root)。
  7. 等幾分鐘後，用 Visit site 檢查。
  8. 每次更新都新增 commit，不要只覆蓋檔案而不留紀錄。

等到你熟悉後，再讓 Codex 幫你處理：

請檢查這個 HTML 是否能在本機正常顯示，確認圖片路徑與手機版排版，然後只 stage 本次相關檔案，commit 到 main，最後 push 到 GitHub。

這個指令背後包含四件事：檢查、選檔、記錄、發布。這就是 Codex 能幫老師節省大量時間的地方。

1.7 七、參考資料