資訊2026/8/23 更新

貢獻

為什麼要開源？

新生懶人包最大的敵人，往往不是「寫不出來」，而是「沒人維護」。校內制度年年改、連結年年壞，如果只靠少數幾個人盯著，只要兩三年沒有更新，就會淪為過期資訊。

為了讓專案的存續不依賴特定個人，確保學長姐畢業後，學弟妹依然能接手傳承，本站從一開始便以 GitHub 公開專案的形式運作：

  1. 內容即檔案：每篇文章都是一個獨立檔案，改內容就像改文件，不需要申請後台帳號。
  2. 人人能提案：任何在校生都能提出修改，補一句話、改一個錯字都大歡迎。
  3. 品質有把關：提案不會直接上線，經維護者確認後才會併入，確保資訊正確性。
  4. 歷史全保留：誰在什麼時候改了什麼皆有紀錄，不小心改壞了隨時能還原。

你可以貢獻什麼？

只要是對學弟妹有幫助的資訊，我們都歡迎：

  • 回報錯誤：內容寫錯、連結失效、資訊已過期。
  • 補充內容：某個主題講得不夠清楚，或缺少了某些環節。
  • 各系專屬資訊：系學會運作、選課慣例、必修避雷，特別歡迎在校生現身說法。
  • 經驗分享：你曾經踩過的坑，就是下一屆最需要的避險指南。
  • 技術改善：版面優化、無障礙設計、網站效能調整。

讓 AI Agent 幫你改

不會寫程式也沒關係。打開你的 AI Agent（Claude Code 之類），使用我們提供的 skill，把想做的事講出來，它就會把整套流程跑完。

  1. 把專案抓下來：git clone https://github.com/NTUST-OpenSource/freshman.git，在專案資料夾裡開你的 AI Agent。
  2. 登入 GitHub CLI：跑一次 gh auth login，之後開 Issue 與 PR 都靠它。
  3. 講出你想改什麼：輸入 /rookie 加上敘述，用中文講就好，不用管專有名詞。
/rookie 住宿篇的地址範例寫「台北市」，全站用字應該是「臺北市」
/rookie 交通篇的 YouBike 費率好像是舊的，我不確定正確數字是多少
/rookie 選課篇「加簽」那段講得太簡略，可以寫得更清楚

它會照這個順序走：

  1. 先開 Issue：不管你要不要自己動手，它都會先把問題記錄下來，附上檔案位置與影響範圍。
  2. 問你要不要順手修：說不要就停在 Issue，之後由維護者接手；說要就繼續往下。
  3. 開分支改檔：從 dev 開新分支，改完在本機建置一次，確認沒有踩到語法地雷。
  4. 本機先審一輪：開 PR 之前先在本機跑一次程式碼審查，抓得到的問題當場修掉。
  5. 建立 PR：目標分支自動設成 dev，關聯剛剛那則 Issue，並指定審查者與標籤。
  6. 盯審查結果：PR 開好之後會自動觸發線上程式碼審查。

只知道有問題、不知道正確答案也沒關係，直接講，它會停在 Issue 不會亂猜著改。

三種參與方式

看你手上有多少資訊、想改多大，選個選項做修改即可：

你的情況走哪一種
發現問題，但不確定正確答案，或不方便自己動手方式一：開 Issue
錯字、失效連結、過期的日期或金額方式二：在網頁上直接改
新增整篇文章、處理圖片、調整網站功能方式三：把專案抓到本機

要新增整篇文章、大幅重寫，或動到網站底層功能，先開 Issue 講一下方向再動手。這不是流程刁難，是避免你花兩小時寫完，才發現那個主題早就被併進另一篇了。

方式一：開 Issue

Issue 就像是專案的「留言板」。當你發現網站有問題，但不知道正確答案，或者不方便自己動手改時，只要把問題說清楚即可。

  1. 前往 Issues 頁面，點擊右上方 New issue。
  2. 有符合狀況的模板就挑一個，沒有的話直接開空白的也沒關係。
  3. 標題請寫出具體問題（例如：「住宿篇的報修表單連結已失效」），避免只寫「有問題」。
  4. 內文請明確指出是哪一篇、哪一段出錯；若知道正確資訊，也請一併附上。
  5. 送出！後續的處理進度都會在該則 Issue 底下進行討論。

方式二：在網頁上直接改

錯字、失效連結、補一兩句話，用這個就夠了。什麼軟體都不用裝，有 GitHub 帳號就能開工。

  1. 切到 dev 分支：進入 GitHub 專案頁，把左上角的分支選單從 main 切成 dev。
  2. 找到檔案：文章網址的最後一段就是檔名，例如 /article/dorm/ 對應 src/content/articles/dorm.md。
  3. 進入編輯：打開該檔案，點右上角的鉛筆圖示（Edit this file）。第一次操作時 GitHub 會自動幫你建立一份副本（fork），照提示繼續即可。
  4. 修改內容：直接改文字，改完把檔案最上方的 updated: 換成今天的日期。
  5. 填寫說明：捲到下方的 Commit changes，標題用英文一句話寫清楚改了什麼，例如 fix(Content): update the broken dorm repair form link。
  6. 建立 PR：選 Create a new branch for this commit and start a pull request，按 Propose changes。
  7. 確認目標分支：在 PR 頁面檢查 base 是不是 dev，不是的話按 Edit 改掉。
  8. 補充理由並送出：說明欄寫出改了哪一篇、哪一段、為什麼要改，有官方公告或截圖請一併附上，然後按 Create pull request。

送出之後會自動跑一次建置。萬一不小心打壞了語法，PR 上會出現紅色叉叉，點進去看訊息就知道哪裡出錯。不用緊張，改一改再推上去就好。

方式三：把專案抓到本機

要新增整篇文章、處理圖片或動到版面，就得把專案抓下來跑。需要 Node 22.12 以上，開始前先 fork 一份到自己帳號。

GitHub 專案頁原始碼、Issue 與 PR 都在這裡，README 有更完整的開發說明github.com 
git clone git@github.com:<你的帳號>/freshman.git
cd freshman
npm ci
npm run dev

打開終端機顯示的那個網址，就是本機版的網站。改 src/content/articles/ 底下的檔案，畫面會馬上跟著變。

分支：從 dev 開，也推回 dev

不要直接在 main 或 dev 上動手，從 dev 拉一個新分支出來：

git fetch origin
git switch -c fix/dorm-repair-link origin/dev

分支名長成 <type>/<簡短英文說明> 這樣，後半用小寫英文加連字號。<type> 和 commit 訊息共用同一組：feat（新功能、新文章）、fix（修正錯誤與過期資訊）、docs（文件）、refactor（重構）、perf（效能）、chore（雜項）、ci（自動化設定）。

Commit 訊息

一律寫英文，格式是 type(Scope): short description，需要交代細節就在下面補條列。一件事 commit 一次就好，不要把三四項修改全部塞進同一筆。

fix(Content): update the dorm repair form link

- the old Google Form returns 401 and is no longer reachable
- point to the housing office page instead

送出

推上去之前，先在本機建置一次，確定沒有踩到語法地雷：

npm run build
git push -u origin fix/dorm-repair-link

然後到 GitHub 開 PR，base 記得選 dev，說明欄寫清楚改了什麼、依據是什麼。

內容撰寫規範

文章檔案與中繼資料

每篇文章是 src/content/articles/ 底下的一個 .md 檔，檔名即網址（dorm.md 對應 /article/dorm/）。檔案開頭的區塊是這篇文章的中繼資料：

---
title: 住宿
slug: dorm              # 路由；僅小寫英數與連字號，需與檔名一致
category: life          # course | life | info | misc，決定側邊目錄分區
tags: [住宿, 宿舍]
description: 入住流程、宿舍網路、冷氣卡與門禁的完整指南   # 用於搜尋結果與列表卡片
order: 3                # 同分區內的排序
updated: 2026-08-15     # 每次改動都要更新
draft: false            # true 時不會出現在正式站
noindex: false          # true 時上線但不進搜尋引擎
---

動過內容就把 updated: 改成當天。

正文就是一般的 Markdown，再加上本站自訂的幾個區塊語法。最常用到的是提示區塊和站內連結：

:::tip[標題]
提示區塊。型別有 info、tip、warning、danger、fatal。
:::

[[course-select]]              站內連結，方括號內填目標文章的 slug
[[course-select|選課篇]]        自訂顯示文字

其餘語法（分頁、步驟、問答、連結卡片、系別條件區塊等）都寫在 docs/spec/SPEC.md，想看實際長什麼樣就翻 src/content/articles/prototype.md。圖片一律自己託管，放在 public/images/<文章 slug>/ 並轉成 WebP，不要直接連到 imgur 之類的外站，那種連結遲早會壞。尺寸不用自己標，建置時會讀圖補上。

排版與語氣

  • 嚴禁抄襲與直接複製：本站為獨立創作，任何參考資訊都必須經過查證並用自己的話重寫，直接複製他站內容的 PR 將不予合併。
  • 排版規範：全站使用繁體中文。標點符號請用全形，數字與英文字母用半形，且中英文/數字之間需加上一個半形空白。
  • 禁用 Emoji：為維持風格統一，內容、介面與 commit 訊息皆禁止使用 emoji，請一律使用站內既有的 SVG 圖示。
  • 標註時效性：制度相關內容，請註明是「哪一學年」的規定（例如：113 學年度），方便未來核對是否適用。
  • 保持客觀保留：若遇到不確定的資訊，請寫「依當年最新公告為準」並附上官方連結，避免提供錯誤的絕對資訊。
  • 引用他人問答只留日期與泛稱：例如寫「臺科學長姐」，不要寫進原始貼文者的姓名。

會讓建置失敗的寫法

本站的語法檢查故意設定得很嚴格，寧可建置當場失敗，也不要讓壞掉的內容悄悄上線。以下幾種情況會直接被擋：

  • 打錯區塊名稱：例如把 :::tip 寫成 :::tipp
  • 壞掉的站內連結：[[slug]] 指向不存在或仍是草稿的文章
  • 中繼資料出現不存在的欄位：例如把 draft 打成 darft
  • slug 重複或格式錯誤：只允許小寫英數與連字號
  • ::card 少了 href，或 href 不是網址與站內路徑

行內語法打錯（例如 :kbdd[...]）不會擋建置，但會原封不動印在頁面上，一樣很醜。

送出前的檢查清單

  1. PR 的目標分支是 dev，不是 main
  2. npm run build 通過（在網頁上修改的話，看 PR 上的建置結果）
  3. updated: 已改成今天的日期
  4. 新增或修改的連結都實際點過，確認沒有失效
  5. 標點全形、數字與英文半形，中英之間有半形空白
  6. 沒有 emoji
  7. 制度性內容有標註學年
  8. 新增的圖片放在 public/images/<slug>/、已轉 WebP、有說明文字
  9. 內容是自己重寫的，不是複製貼上

需要協助嗎？

  • 公開討論：關於內容問題或網站錯誤，最有效率的方式是直接開 GitHub Issue 討論。
  • 加入維護團隊：如果你對長期維護專案有興趣，歡迎開 Issue 說明你想參與的部分，維護者會主動與你聯繫。
  • 私下聯絡：如果有不便公開的事項，可以到銘謝頁找到維護者的 GitHub 帳號，從個人頁面與對方聯絡。
銘謝原始團隊與貢獻者名單；你的下一個 PR 合併後，名字也會出現在上面