複製這份 Markdown README 範本
這是編寫好的入門範本,不是可運作的軟體範例。請替換方括號中的文字,確認引用的檔案存在,並移除不適用的章節。下方安裝與執行內容均為註解,避免意外執行預留指令。
# [專案名稱]
[用一句話說明:問題、適用對象及成果。]
## 範例
[展示一組簡短輸入及預期輸出,或加入螢幕截圖。]
## 快速開始
需求:[執行環境/版本及必要服務]。
```sh
# 替換成已驗證的安裝指令。
# 替換成能產生有用結果的最簡指令。
```
預期結果:[讀者應該看到的內容]。
## 設定
[必要設定、安全的範例值,以及儲存機密資訊的位置。]
## 適用情境
- [一個具體使用情境]
- [第二個使用情境]
## 限制
[不支援的輸入、成熟度、效能或平台限制。]
## 文件與協助
[提供文件連結,並說明在哪裡提問。]
## 參與貢獻
請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)。
透過儲存庫的 Issues 分頁回報可重現的問題。
## 授權條款
請參閱 [LICENSE](LICENSE)。依儲存庫類型調整範例
對命令列工具,展示輸入檔案、指令及簡短輸出。對函式庫,展示最精簡且完整的匯入與呼叫範例,包含預期回傳值。對網頁應用程式,展示主要操作流程,並說明是否有線上展示或本機安裝方式。
避免只用螢幕截圖說明 API:讀者應能複製程式碼。反之,視覺化應用程式適合使用截圖,並清楚描述使用者正在做什麼。請使用目前發行版本的實際範例。
- 函式庫:安裝方式、支援的執行環境,以及一次完整的函式呼叫。
- CLI:輸入、指令、輸出及錯誤回報方式。
- 網頁應用程式:展示連結或本機安裝方式、設定及主要任務的截圖。
- 資料集:來源、格式、授權及一筆簡短的範例紀錄。
分享前檢查 README
在乾淨的環境中嘗試快速開始步驟,而非已設定好開發環境的電腦。檢查是否依賴未聲明的全域套件、私人套件登錄庫或本機檔案。如果安裝需要帳號或付費服務,請在第一個指令之前說明。
從儲存庫頁面開啟文件及圖片連結。確認貢獻指南和授權檔名與儲存庫一致,並移除失效連結。簡短準確的 README,勝過外表華麗卻充滿未實現承諾的範本。
- 移除預留文字及沒有根據的宣稱。
- 範例中不要放入真實權杖、密碼或私人網址。
- 確認預期輸出與已發布的版本一致。
- 告訴讀者回報問題時應提供哪些資訊。
將 README 用作發布簡介的基礎
完成範本後,擷取一段簡短介紹:一句說明問題的話、一個成果範例,以及一個試用連結。這就能成為社群貼文的起點。保留原始 README 作為詳細資訊來源,並針對各類讀者調整介紹,而不是在所有地方重複同一段宣傳文。
常見問題
這是儲存庫 README 還是個人檔案 README?
這份範本適用於軟體儲存庫。個人檔案 README 用來介紹個人,需要不同章節,例如作品及偏好的聯絡方式。
應該在頂端加入星標徽章嗎?
只有對讀者有幫助時才加入。讓用途及快速開始保持醒目。徽章不能取代對專案功能的說明。
私人專案可以使用這份範本嗎?
可以。將公開支援連結換成團隊實際使用的求助管道,說明存取要求,並避免將憑證放入文件。