專案指南

開源專案的 GitHub README 範本

實用的 GitHub README 能迅速回答四個問題:專案做什麼、適合誰、如何試用,以及去哪裡求助?以下方 Markdown 範本為起點,再用已核對過的專案資訊取代每個預留文字。

GitHubStart 編輯團隊 · 更新日期

複製這份 Markdown README 範本

這是編寫好的入門範本,不是可運作的軟體範例。請替換方括號中的文字,確認引用的檔案存在,並移除不適用的章節。下方安裝與執行內容均為註解,避免意外執行預留指令。

# [專案名稱]

[用一句話說明:問題、適用對象及成果。]

## 範例
[展示一組簡短輸入及預期輸出,或加入螢幕截圖。]

## 快速開始
需求:[執行環境/版本及必要服務]。

```sh
# 替換成已驗證的安裝指令。
# 替換成能產生有用結果的最簡指令。
```

預期結果:[讀者應該看到的內容]。

## 設定
[必要設定、安全的範例值,以及儲存機密資訊的位置。]

## 適用情境
- [一個具體使用情境]
- [第二個使用情境]

## 限制
[不支援的輸入、成熟度、效能或平台限制。]

## 文件與協助
[提供文件連結,並說明在哪裡提問。]

## 參與貢獻
請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)。
透過儲存庫的 Issues 分頁回報可重現的問題。

## 授權條款
請參閱 [LICENSE](LICENSE)。

依儲存庫類型調整範例

對命令列工具,展示輸入檔案、指令及簡短輸出。對函式庫,展示最精簡且完整的匯入與呼叫範例,包含預期回傳值。對網頁應用程式,展示主要操作流程,並說明是否有線上展示或本機安裝方式。

避免只用螢幕截圖說明 API:讀者應能複製程式碼。反之,視覺化應用程式適合使用截圖,並清楚描述使用者正在做什麼。請使用目前發行版本的實際範例。

  • 函式庫:安裝方式、支援的執行環境,以及一次完整的函式呼叫。
  • CLI:輸入、指令、輸出及錯誤回報方式。
  • 網頁應用程式:展示連結或本機安裝方式、設定及主要任務的截圖。
  • 資料集:來源、格式、授權及一筆簡短的範例紀錄。

分享前檢查 README

在乾淨的環境中嘗試快速開始步驟,而非已設定好開發環境的電腦。檢查是否依賴未聲明的全域套件、私人套件登錄庫或本機檔案。如果安裝需要帳號或付費服務,請在第一個指令之前說明。

從儲存庫頁面開啟文件及圖片連結。確認貢獻指南和授權檔名與儲存庫一致,並移除失效連結。簡短準確的 README,勝過外表華麗卻充滿未實現承諾的範本。

  • 移除預留文字及沒有根據的宣稱。
  • 範例中不要放入真實權杖、密碼或私人網址。
  • 確認預期輸出與已發布的版本一致。
  • 告訴讀者回報問題時應提供哪些資訊。

將 README 用作發布簡介的基礎

完成範本後,擷取一段簡短介紹:一句說明問題的話、一個成果範例,以及一個試用連結。這就能成為社群貼文的起點。保留原始 README 作為詳細資訊來源,並針對各類讀者調整介紹,而不是在所有地方重複同一段宣傳文。

常見問題

這是儲存庫 README 還是個人檔案 README?

這份範本適用於軟體儲存庫。個人檔案 README 用來介紹個人,需要不同章節,例如作品及偏好的聯絡方式。

應該在頂端加入星標徽章嗎?

只有對讀者有幫助時才加入。讓用途及快速開始保持醒目。徽章不能取代對專案功能的說明。

私人專案可以使用這份範本嗎?

可以。將公開支援連結換成團隊實際使用的求助管道,說明存取要求,並避免將憑證放入文件。

參考資料