GitHub README 排版術：把開源專案首頁變成 landing page
本篇是「一個人做產品」系列的第 17 / 18 篇。你可以從系列總覽開始閱讀，也可以直接接著看本文。
README 的 10 秒首屏，就是你的 landing page
打開一個沒聽過的 GitHub repo，你會花多少時間決定要不要 star？
Nielsen Norman Group 多年的網頁瀏覽研究告訴我們：訪客平均在 10 秒內決定是否繼續看下去。README 的「首屏」（不用滾動就能看到的部分）就是這 10 秒的決勝點。
對開源專案來說，README 就是你的 landing page。但開源專案的 README 跟商業 landing page 不一樣。你沒有設計師、沒有 A/B 測試、也沒有複雜的 CMS。
只有 Markdown 和一點 HTML。
這篇講「用 GitHub 原生支援的 markdown 語法，把 README 排成像 landing page 的版面」。給第一次發 OSS、或一直覺得自己 README 看起來「不夠專業」的人。
一個好 README 的視覺骨架
直接看範例：
<div align="center">
<img src="logo.png" width="120" alt="Logo" />
# Project Name
**One-line tagline that explains the value**
A 1-2 sentence elevator pitch.
[](LICENSE)
[](.../releases/latest)
<img src="demo.gif" width="700" alt="Demo" />
</div>
> Optional callout: a key thing visitors should know upfront.
## How It Works
| Step | Action |
| :--: | ------ |
| **1.** | Install with `brew install ...` |
| **2.** | Run `command` |
| **3.** | See the result |
## Features
...這個結構在 GitHub 上 render 起來就是一個 hero 區塊 + 三步驟引導 + 功能介紹。完全用 markdown + 兩個 <div> 和 <img> 標籤。
接下來拆解每個元素的細節。
元素 1：Centered Hero Block
GitHub markdown 支援 <div align="center"> 把內容居中。這是排出 landing-page-style hero 的基礎。
<div align="center">
<img src="logo.png" width="120" alt="Logo" />
# Project Name
**Tagline**
</div>幾個容易踩的細節：
<div>開合之間要留空行，markdown 才會 render 裡面的#標題和**bold**<img>用width="120"屬性控制大小，不要用 inlinestyle="..."，GitHub 的 HTML sanitizer 會 strip 掉 style- 居中的
#標題在 mobile 上也會正確居中
元素 2：Badges（4 個就好）
shields.io 是事實上的標準，支援數十種服務（CI、套件庫、coverage、社群平台等）的動態 badges，再加上無限自訂的靜態 badge。
該放的 4 個：
[](LICENSE)
[](.../releases/latest)
[](.../actions)
對應訪客要判斷的 4 件事：
| Badge | 訪客在問 |
|---|---|
| License | 能不能用？商業？fork？ |
| Release version | 專案還活著嗎？最近一次更新多久前？ |
| Build status | 品質如何？CI 過得了嗎？ |
| Platform | 支援我的環境嗎？ |
不該放的：
- ❌ Downloads count、code coverage、star count，這些數字一旦停滯反而扣分
- ❌ Discord / Slack / 廣告 badges，會分散訪客注意力
- ❌ 超過 4 個，開始看起來像 CI pipeline 而不是 landing page
GitHub repo 頁面本來就有 star count，README 不用重複放。
元素 3：Hero Image / GIF / Video
視覺是 10 秒內最快傳達訊息的方式。三個選擇：
- Screenshot：靜態，但能放最高解析度
- GIF：動態 demo，相容性最好（任何 markdown viewer 都吃）
- Video：真正的播放器，但只能透過 GitHub 拖放上傳，且只在 github.com 顯示
哪個適合你的場景？我寫過一篇詳細的 《GitHub README 動態 demo 的 5 種策略：從 GIF 到自架 CDN》，附決策樹幫你選。
元素 4：一句話定位（最重要的元素）
直接看兩個對比：
<!-- ❌ 工程師寫法 -->
TypeLate is a cross-platform push-to-talk dictation app built with Tauri v2
that uses Groq Whisper for transcription and LLM-based post-processing.
<!-- ✅ User-facing 寫法 -->
**Too late to type — just speak.**
Press a hotkey to start, speak naturally, press again to stop.
Your voice becomes polished text in under 3 seconds — right where you type.兩個關鍵差別：
- 擺放位置：藏在內文第一行 vs 獨立的
**bold tagline**——訪客掃讀的第一視覺重點 - 「has feature X」vs「does Y for you」：把焦點放在「使用者得到什麼」而不是「我們做了什麼」
對 indie hacker / solo builder：tagline 要在 60 字內傳達「給誰、解決什麼、用什麼方式」。寫不出來代表產品定位還沒想清楚。
想看更多範例？Awesome README 是 GitHub 上精選的 README 範例集，找一個跟你類似的專案抄結構。
元素 5：Quick Start（30 秒能試到）
如果讀者讀到這裡還沒被勸退，他在想「我怎麼試試看」。給他最短路徑：
## Quick Start
```bash
brew install your-cli
your-cli init
your-cli run
```三行裝完三行跑。
如果你的安裝需要 10 個步驟，不要硬塞進 Quick Start。那代表你該重新設計安裝流程了。一個典型問題：「先設定環境變數、再裝依賴、再 build、再執行 migration、再啟動……」，這些都該包成單一指令（make install 或 npx create-foo）。
元素 6：章節順序模板
對小型開源工具，這個順序我用了很多次：
# Project Name (hero block 已含)
## How It Works
（一個 table 或三個 emoji bullets 講工作原理）
## Features
（4-6 個關鍵功能，每個一段話）
## Quick Start
（裝 → 用 → 看到結果）
## Documentation
（連到完整文件 / wiki / website）
## Contributing
（接受 PR 嗎？要遵守什麼規範？）
## License
（一行就好：MIT / Apache 2.0）長 README（超過 10 個章節）才需要 Table of Contents。短於 5 個章節的 README 加 TOC，反而讓 TOC 佔滿首屏、把真正的 hero 內容推到滾動線以下。
5 個常見錯誤
寫 README 的地雷：
- 一上來放安裝指令 — 訪客還不知道這是什麼就要他裝？先 hook 再裝
- 沒有視覺 — 純文字 README 就像沒有截圖的 App Store 頁面
- Badges 排了一整行 — 超過 4 個就開始看起來像 CI dashboard
- 章節順序亂跳 — 「先講安裝、再講功能、再講為什麼、再講安裝」這種輪迴看不下去
- Tagline 是「This is a tool that…」 — 直接寫 user value，不要解釋自己是什麼
兩個現成工具
如果不想從零寫：
- readme-md-generator：interactive CLI，問 10 個問題產出標準結構的 README。⚠️ 老牌但已停更（最後發布 v1.0.0 / 2019 年），在新版 Node.js 上可能有相容性問題；建議當作結構參考，或改用線上工具 readme.so
- Awesome README：GitHub 精選範例集，找類似專案抄結構
3 分鐘快速上手 readme-md-generator
注意：此工具最後一次發布是 v1.0.0（2019 年），已多年未更新，在新版 Node.js 上可能裝不起來或跑不動。以下流程僅供參考其產出結構，若安裝失敗請改用 readme.so 之類仍在維護的線上產生器。
# 安裝
npm install -g readme-md-generator
# 進入專案根目錄
cd your-project
# 啟動 interactive 模式
readme-md-generator執行後會依序問你：
- 專案名稱（自動從
package.json抓） - 描述、版本、作者
- 想包含哪些章節（Installation、Usage、Tests、Contributing…）
- 授權類型
每個問題都有預設值（直接按 Enter 就行），跑完一輪會在當前目錄生成 README.md。產出的結構不是最美但很完整，可以當骨架再手動精修。
TL;DR
把 README 排成 landing page 的 6 個元素：
- Centered hero block（logo + 標題 + tagline）
- Badges（4 個就好：license、release、build、platform）
- Hero image / GIF / video（視覺先行）
- 一句話定位（user value，不是 feature list）
- Quick Start（30 秒能試到）
- 章節順序模板（How → Features → Install → Docs）
訪客只給你 10 秒。這 6 個元素是讓那 10 秒值得的最低標準。
接下來
學會基本排版後，如果想把產品 demo 影片塞進 README：
👉 《GitHub README 動態 demo 的 5 種策略：從 GIF 到自架 CDN》 — 5 種策略決策樹，幫你選最適合的呈現方式
👉 《把 30 秒產品介紹塞進 GitHub README 的最後一哩》 — <video> 標籤的踩雷紀錄，60 秒手動操作的真相
👉 《為什麼一支 30 秒影片是 OSS 上架最大的槓桿》 — 把視覺先行的觀念延伸到 OSS 上架策略
👉 《Landing Page 與 SEO：讓產品被找到》 — landing page 核心概念從 README 延伸到完整產品曝光
