README.md 怎麼寫?GitHub README 格式與範本

打開一個 GitHub 專案,第一眼看到的就是 README.md。寫得好的 README 能讓人在 30 秒內知道:這是什麼、怎麼安裝、怎麼使用。這篇整理 README 的標準結構、常用寫法,最後附上可以直接複製的範本。

邊看邊寫的話,可以打開 Markdown 線上編輯器,左邊寫、右邊即時看到效果。

README 應該包含什麼?

一份好 README 通常依序包含:

  1. 專案名稱與一句話介紹:讓人立刻知道它在解決什麼問題。
  2. 截圖或示範:一張圖勝過千言萬語。
  3. 功能特色:條列 3 到 6 個重點。
  4. 安裝方式:複製貼上就能執行的指令。
  5. 使用方式:最簡單的範例。
  6. 設定說明:環境變數、設定檔(若有)。
  7. 貢獻方式:如何回報問題、提交修改。
  8. 授權:例如 MIT、Apache-2.0。

小專案可以只寫 1、4、5、8,重點是讓第一次來的人能順利跑起來。

常用寫法

標題與介紹

# Moread

> 免安裝的 Markdown 閱讀器,檔案不上傳。

一份 README 只用一個 # 大標題,其餘用 ## 分段。語法細節可以參考 Markdown 語法教學。

安裝指令放在程式碼區塊

```bash
git clone https://github.com/you/project.git
cd project
npm install
```

標註語言(bash、python、javascript)能讓 GitHub 顯示語法高亮。

截圖

![主畫面截圖](docs/screenshot.png)

圖片放在專案裡的 docs/ 或 assets/ 資料夾,用相對路徑引用,搬移專案也不會壞掉。

徽章(Badges)

很多 README 開頭會有一排小徽章,顯示版本、授權、建置狀態:

![License](https://img.shields.io/badge/license-MIT-green)

徽章是加分項目,不需要放太多。

表格整理選項

| 參數 | 預設值 | 說明 |
| --- | --- | --- |
| `port` | `3000` | 伺服器埠號 |
| `debug` | `false` | 是否顯示除錯訊息 |

表格更多技巧請看 Markdown 表格教學。

用 Mermaid 畫架構圖

GitHub 支援 Mermaid,可以直接在 README 畫流程或架構圖:

flowchart LR
    A[使用者] --> B[前端] --> C[API] --> D[資料庫]

詳細語法見 Mermaid 圖表教學。

README 範本(可直接複製)

# 專案名稱

一句話說明這個專案解決什麼問題。

![截圖](docs/screenshot.png)

## 功能

- 功能一
- 功能二
- 功能三

## 安裝

```bash
npm install your-package
```

## 使用方式

```javascript
import { hello } from 'your-package';
hello('world');
```

## 設定

| 參數 | 預設值 | 說明 |
| --- | --- | --- |
| `option` | `true` | 說明這個選項 |

## 貢獻

歡迎提交 Issue 與 Pull Request。

## 授權

MIT

把範本貼到線上編輯器,改成你的內容,再按 Ctrl + S 下載成 README.md。

寫好 README 的小技巧

  • 先寫「怎麼跑起來」:大多數人只想知道怎麼安裝和使用。
  • 指令要能直接複製:不要在指令裡混入說明文字。
  • 保持更新:程式改了,README 也要跟著改。
  • 長文件加目錄:段落很多時,在開頭列出各段連結。
  • 多語系:可以另外提供 README.zh-TW.md,並在開頭互相連結。

寫完之後,把 README.md 拖進墨閱檢查一次排版,確認標題、表格和圖表都正確再推上 GitHub。