AnyBot/docs/readme-style.md

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。

這份 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 圖、兩三段簡介，然後才是安裝。

自己檢查渲染

不需要推上去才知道有沒有跑版：

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