52 lines
3.8 KiB
Markdown
52 lines
3.8 KiB
Markdown
|
# README 怎麼寫才不跑版
|
|||
|
|
|
|||
|
|
兩件事：高星專案的 README 長什麼樣子（2026-11 掃過一轮），以及這份 README 在 Gitea 上跑版的真實原因和做法。
|
|||
|
|
|
|||
|
|
## 高星專案的共同形狀
|
|||
|
|
|
|||
|
|
看的是 OpenClaw、ollama、Dify、AnythingLLM、Meetily、LobeHub、n8n、home-assistant 這批（3 萬到 30 萬星）。它們的順序幾乎一樣：
|
|||
|
|
|
|||
|
|
| 順序 | 內容 | 為什麼 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 1 | Logo 置中 + H1 標題就是價值（不只有名字） | 3 秒內知道這是什麼 |
|
|||
|
|
| 2 | 一行副標 + shields 徽章列（授權、平台、版本、CI、社群） | 信任感、可點 |
|
|||
|
|
| 3 | 語系列（中文 · English · …） | 多語 README 的入口 |
|
|||
|
|
| 4 | 兩三段、每段兩三行的簡介：它是什麼、給誰用、信任邊界 | 自我-hosted 專案一定在這邊講清楚資料去哪裡 |
|
|||
|
|
| 5 | 連結列：Website · Docs · Getting started · FAQ | 不想讀 README 的人有出口 |
|
|||
|
|
| 6 | Hero 圖或 GIF（會動的優先） | 一張圖勝過一段字 |
|
|||
|
|
| 7 | `## Install`：一兩段 fenced code block（sh / powershell） | 放在上面三分之一，不要埋在文件之後 |
|
|||
|
|
| 8 | `## Quick start`：裝完做什麼、會看到什麼 | 讓人在 5 分鐘內成功一次 |
|
|||
|
|
| 9 | 架構：4–6 個要點或一張圖，不寫程式碼細節 | 「它怎麼組成」 |
|
|||
|
|
| 10 | 文件索引：一個 2 欄表（你想… → 看哪份） | 長 README 的收斂點 |
|
|||
|
|
| 11 | 開發、安全、社群、授權：各一小節，每節 2–6 行 | 結尾收乾淨 |
|
|||
|
|
|
|||
|
|
共同習慣：安裝用**代碼區塊**不用表格；功能用**要點**不用大表；圖片寬度 ≤ 內容欄寬（約 980px）；長 README 用 `<details>` 收起來；重點是「一句話 + 一行指令 + 一張圖」。
|
|||
|
|
|
|||
|
|
會跑的 README 通常把 GIF 放最上面。我們目前只有靜圖，录屏方法見 [demo/README.md](demo/README.md)。
|
|||
|
|
|
|||
|
|
## 這份 README 之前跑版的原因
|
|||
|
|
|
|||
|
|
1. **安裝表**。三欄表裡塞 `curl -fsSL https://…/install.sh | sh` 這種超長 inline code：URL 沒有空格，無法斷詞，表格被撐寬，整頁出現橫向捲動。這是最大的一項。
|
|||
|
|
2. **程式碼區塊太寬**。Windows 手腳那一行 1414px，區塊自己出現捲軸，看起來像壞掉。
|
|||
|
|
3. **圖片用 HTML 寬度**。`<img width="780">`：Gitea 的 sanitizer（bluemonday UGC）會留 `width`，但 `<p>` 沒有 `align` 就靠左，寬度也是寫死的，換螢幕就不對。
|
|||
|
|
4. **文字層級**。開頭三行就進安裝表，沒有 logo、徽章、語系列，看起來不像一個「產品」。
|
|||
|
|
|
|||
|
|
## 這支 README 的寫法（保持這樣就不會跑版）
|
|||
|
|
|
|||
|
|
- 安裝一律用 fenced code block（`sh` / `powershell`），**不用表格**。一行超過 90 字就斷行加 `\`（sh）或換行（PowerShell）。
|
|||
|
|
- 表格最多兩欄，格子的文字要短，格子裡**不放長 URL**、不放入行程式碼。
|
|||
|
|
- 截圖先照 2x 拍，再壓到 960px 寬存檔，`<p align="center"><img src="…" width="960">`。Gitea 的欄寬約 980px，压過的圖在 Retina 上也清楚。
|
|||
|
|
- 只用 Gitea 留得下來的 HTML：`<p align="center">`、`<h1 align="center">`、`<img width>`、`<details>`。`style` 屬性只有 `color` / `background-color` 且只在 `span` / `p` 上活著，別指望它排版。
|
|||
|
|
- mermaid 可以用（這台 Gitea 1.21 會渲染）。要更保險就留一份純文字圖，两份都在 README 裡。
|
|||
|
|
- 開頭固定：logo、H1、副標、語系列、徽章、hero 圖、兩三段簡介，然後才是安裝。
|
|||
|
|
|
|||
|
|
## 自己檢查渲染
|
|||
|
|
|
|||
|
|
不需要推上去才知道有沒有跑版：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
npx --yes marked --gfm -i README.md -o /tmp/body.html
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
把 `/tmp/body.html` 放進一個 `max-width: 980px` 的容器（Gitea 的欄寬），用 headless Chrome 開起來，在頁面裡量：`document.documentElement.scrollWidth` 是否等於視窗寬、有沒有元素右邊超出容器內容寬、`pre` 的 `scrollWidth` 是否大於 948。三項都過，就不會跑版。
|