# 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 用 `
` 收起來；重點是「一句話 + 一行指令 + 一張圖」。 會跑的 README 通常把 GIF 放最上面。我們目前只有靜圖，录屏方法見 [demo/README.md](demo/README.md)。 ## 這份 README 之前跑版的原因 1. **安裝表**。三欄表裡塞 `curl -fsSL https://…/install.sh | sh` 這種超長 inline code：URL 沒有空格，無法斷詞，表格被撐寬，整頁出現橫向捲動。這是最大的一項。 2. **程式碼區塊太寬**。Windows 手腳那一行 1414px，區塊自己出現捲軸，看起來像壞掉。 3. **圖片用 HTML 寬度**。``：Gitea 的 sanitizer（bluemonday UGC）會留 `width`，但 `

` 沒有 `align` 就靠左，寬度也是寫死的，換螢幕就不對。 4. **文字層級**。開頭三行就進安裝表，沒有 logo、徽章、語系列，看起來不像一個「產品」。 ## 這支 README 的寫法（保持這樣就不會跑版） - 安裝一律用 fenced code block（`sh` / `powershell`），**不用表格**。一行超過 90 字就斷行加 `\`（sh）或換行（PowerShell）。 - 表格最多兩欄，格子的文字要短，格子裡**不放長 URL**、不放入行程式碼。 - 截圖先照 2x 拍，再壓到 960px 寬存檔，`

`。Gitea 的欄寬約 980px，压過的圖在 Retina 上也清楚。 - 只用 Gitea 留得下來的 HTML：`

`、`

`、``、`
`。`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。三項都過，就不會跑版。