/brag-more
你已經把它做出來了。現在讓 repo 也會炫耀吧。README 是任何人在 GitHub 上看到的第一個東西;把它變成一個在五秒內就能推銷專案的首頁,並讓陌生人在一分鐘內從零開始執行。
無論是什麼專案,成果都應該像一個備受喜愛的開源專案的 README:自信、易於掃讀、視覺化、且真實。頁面上不應該有任何不值得存在的東西。
使用方式:/brag-more [options]。選項(標誌或自然語言):
| 選項 | 預設值 |
|---|---|
--style clean|bold|minimal|showcase | 根據專案推斷(參見款式) |
--preview | 關閉:直接寫入 README.md。啟用時,只寫入 brag-output/repo/,保留 README.md 不變 |
--no-banner | 橫幅開啟 |
--no-video | 關閉:如果專案沒有宣傳影片,先製作一個(參見影片) |
--no-demo | 當有東西可展示時,示範開啟 |
工作檔案放在 brag-output/repo/ 中(如果 brag-output/ 已存在且不是來自本次執行,則使用時間戳 brag-output-YYYY-MM-DD-HHmmss/repo/)。README 引用的資源放在 repo 的 .github/readme/ 中,以便隨專案一起發佈。
1. 檢查
讀取專案,而不僅僅是舊的 README:
- 現有的 README,每一行。這是使用者的撰寫。保留所有真實且有用的內容(安裝步驟、設定表格、致謝、授權條款、贊助連結、鳴謝);重新設計樣式,不要丟棄。
- 識別身份: 來自樣式表或主題設定的精確品牌色彩和字型、標誌或 favicon、任何現有的英雄圖像或 OG 圖像。
- 它是什麼: 套件清單(
package.json、pyproject.toml、Cargo.toml、go.mod……)中的名稱、描述、版本、授權、二進位檔和腳本;入口點和主要路由或命令,以了解真實功能。 - 如何執行: 來自清單腳本、
Makefile、justfile、Dockerfile 或 CI 工作流程的實際安裝和啟動命令。注意專案鎖定的執行時期版本。 - 徽章的訊號:
LICENSE、.github/workflows/*、套件是否已發佈(npm、PyPI、crates.io——檢查清單中的名稱和private標誌)、git 遠端(git remote get-url origin)以取得owner/repo。 - 現有的 brag 輸出: 如果
brag-output*/brag.mp4和brag.jpg存在,它們是機器上最好的示範素材。使用最新的。如果沒有,你將在下一個步驟中製作。
跳過建置輸出、鎖定檔案、.git/、環境和秘密檔案(.env、.env.*)、金鑰和憑證資料,以及 .gitignore 因這些原因排除的任何內容。
在寫入之前,回答:它用一句話就能讓陌生人理解是什麼?它是給誰用的?它比替代方案做得更好的那一件事是什麼?視覺鉤子是什麼——截圖、GIF 或橫幅,能讓人停止滾動?3–5 個真實功能是什麼?從 clone 到執行的最短路徑是什麼?
README 是公開的。絕不要將秘密、權杖、內部主機名稱、真實客戶或使用者名稱、電子郵件地址或其他個人資料帶入其中或其圖像中。如果截圖顯示了此類資料,請替換成合理的虛構替代品。
影片(在計劃之前,當還沒有時)
README 最好的示範是專案的啟動影片,所以 brag-more 在缺少時會製作它。當設定了 --no-demo 或 --no-video,或者 brag-output*/brag.mp4 已存在時,跳過此步驟。
- 如果已安裝
/brag技能(檢查技能列表),透過 Skill 工具為此專案執行它,並傳遞任何--tone或格式需求。用一行話告訴使用者:「還沒有啟動影片,所以我先用 /brag 製作一個。」 - 否則讀取
<skill-dir>/video.md(這裡附帶的精簡影片工作流程,來自 brag-slim)並遵循它。它只需要機器上已有的工具。 - 完成時,影片、海報和分享文案都在
brag-output/中。繼續使用它們作為示範來完成 README。
如果製作影片失敗或使用者不想等待,則不使用它繼續進行,並使用示範下的備用方案。
2. 計劃
寫入 brag-output/repo/readme-plan.md:一句話介紹、選擇的款式、章節順序、你要製作哪些視覺效果以及它們各展示什麼、哪些徽章是有正當理由的(以及每個徽章的證據),以及你要從舊 README 中保留什麼。
形狀: 一個起始形狀,不是一個範本。刪除任何會是空或填充的章節。
- 英雄區 — 動畫 SVG 英雄區(參見建置),然後置中:一句話介紹、一行簡短徽章、以及一個導覽連結列(示範 · 安裝 · 文件 · …)。
- 示範 — 使用中的產品,就在英雄區下方,加上邊框:宣傳影片循環、真實 UI 的 GIF、或終端機錄製。一個大的視覺元素。
- 為什麼 — 2–4 句話:它為使用者做什麼以及它與眾不同的地方,用專案自己的話來說。對於開發者工具,一段 3–5 行的程式碼區塊作為賣點勝過一段文字(
bun run index.tsx # TS and JSX out of the box)。 - 功能展示 — 3–6 個真實功能,每個都有自己的一個小視覺元素:真實 UI 的裁切截圖、每個指令的終端機 GIF、或一段程式碼片段及其輸出。視覺上豐富的以並排卡片方式佈局(參見建置)。純文字功能有一個粗體引導句和一行描述。
- 快速入門 — 可複製貼上,依序,每個指令都根據專案驗證過。先列出先決條件。
- 使用方式 — 一或兩個真實範例:一個指令及其輸出、一段程式碼片段、或一個設定區塊。
- 運作方式 — 可選。當架構是有趣的部分時,用一個簡短段落或 Mermaid 圖表。
- 舊 README 中的其他內容 — 設定、常見問題、路線圖、貢獻、致謝 — 整理好,當內容較長時折疊到
<details>中。 - 頁尾 — 授權行,加上結尾的藝術條(參見建置)。
README 法則
- 真實。 每一個宣稱、數字、功能和徽章都必須有專案支援。沒有虛構的星數、下載量、基準測試、推薦或「被用於」的標誌。徽章只有在它所指向的內容存在時才會出現(已發佈的套件、真實的工作流程、授權檔案)。
- 可執行。 快速入門和使用方式中的每個指令都如撰寫般存在於專案中。如果可以安全地執行(安裝、建置、
--help、測試),請執行它。如果某個步驟需要秘密或付費服務,請直接說明,而不是隱藏它。 - 五秒測試。 從推文點進 repo 的人,知道它是什麼,看到它正在運作,並且無需滾動超過第一個畫面就能找到安裝指令。
- 展示產品。 示範展示的是真實產品的使用情況,而不是標誌動畫或抽象藝術。重複使用真實的 UI、真實的 CSS、真實的文案。
- 說明 repo 是什麼。 如果 repo 是產品的網站、登陸頁面或示範頁面,請在一句話介紹中說明;不要暗示人們可以下載一個 repo 沒有提供的應用程式或安裝一個套件。
- 具體。 必須感覺是為這個特定專案撰寫的。「快如閃電」、「無縫」、「次世代」、「簡化你的工作流程」是被禁止的,除非專案確實值得使用這些詞。
- 易於掃讀。 簡短的段落、有資訊量的標題、每個要點一個想法。只有在專案自己的語氣使用 emoji 時,才能在標題中使用,而且要節制(
showcase款式是例外:每個章節標題一個 emoji,這是刻意的設計)。 - 兩種主題。 GitHub 的讀者使用淺色和深色模式。每張圖像在
#ffffff和#0d1117上看起來都要好:具有可見邊緣的透明 PNG,或使用<picture>並為每種主題提供一個prefers-color-scheme來源。 - 符合欄寬。 README 欄在桌面上約 830px 寬,在手機上更窄。橫幅文字在手機寬度下仍可閱讀;表格的欄數要少;不要使用會在行動裝置上中斷的寬原始 HTML 佈局。
- 每個連結都可解析。 相對連結指向存在的檔案;錨點對應真實的標題。
款式
| 款式 | 感覺 | 使用時機 |
|---|---|---|
clean | 動畫英雄區,動作克制,有邊框的示範,整齊的卡片 | 大多數專案;預設值 |
bold | 以品牌色彩全出血的英雄區,有更大的動畫時刻,強而有力的一句話介紹,示範放在最前面和中心 | 消費者應用、有趣的專案、發表 |
minimal | 小動畫標誌鎖定 + 名稱 + 一句話介紹,樸素的章節 | 函式庫、CLI、基礎設施、嚴肅的工具 |
showcase | 密集、emoji 分節的技術 README(想想獲勝的黑客松或研究專案):頂部有產品的真實截圖、獎項或狀態行、然後每個主題一個 emoji 引導的章節 | 黑客松、研究、機器學習、資料或科學專案;任何有深度可以展示的內容。當使用者要求「像 Find My Shark 那樣的東西」或一個詳細、文件風格的 README 時選擇它 |
showcase 配方
以擁有者的 Find-My-Shark README 為模型。保留使其有效的部分,並修正無效的部分:
- 標題帶一個 emoji 和成就行 在下面(「NASA Space Apps 2025, Galactic Impact Winner」),只有在專案真正獲得時才使用。詢問或從舊 README 中讀取;絕不要虛構。
- 真實截圖或示範 GIF 直接放在標題下方,加上邊框(參見示範,有邊框)。只有當動畫英雄區能增加價值時才保留它;在這裡,真實產品才是主角。
- 一個 2-3 行的介紹和「為什麼重要」行,然後是每個由一個 emoji 引導的章節:功能、區域/範圍或輸入、資料來源(表格)、運作方式或數學模型、快速入門(安裝、基本用法、API 用法)、專案結構(附註解的樹狀圖)、設定(真實的設定)、輸出檔案、命令列選項、背景、未來擴展、測試、日誌記錄、結尾標語。
- 只包含專案有真實內容的章節。黑客松等級的深度是重點,所以保留細節:參數、公式、閾值、資料集名稱和專案樹狀圖。
- 修正常見的疏漏: 使用真實的 clone URL(絕不要用
your-username),將專案樹狀圖程式碼區塊中過時的條目替換為實際存在的內容,在章節超過六個時添加目錄或快速連結行,將長的參考章節(CLI 選項、完整設定、科學背景)包裹在<details>中,為真實的技術棧(Python 版本、授權、關鍵函式庫)添加徽章,並在交付時使用<picture>或有邊框的截圖來支援兩種主題,並設定 repo 描述和主題。 - 帶 emoji 的錨點: GitHub 會從標題的 slug 中移除 emoji,但保留連字號,所以
## 🚀 Quick Start是#-quick-start,不是#quick-start。以這種方式撰寫每個導覽連結和徽章連結,並檢查每個連結是否對應到其標題。<details>的 summary 不是標題,也沒有錨點。 - 仍然遵循每一條 README 法則(真實、可執行、兩種主題)和檢查步驟。
3. 建置
GitHub 上最好的 README(Excalidraw、Scalar、Supabase、Charm、Rich、Bun)都共享幾個技巧。全部使用它們;這就是讓這個 README 能讓人停止滾動的原因。
英雄區:一個動畫 SVG
這是簽名檔。一個靜態橫幅看起來像個範本;一個會動的英雄區——使用專案自己的色彩、字型和 UI——看起來就像為這個專案量身打造。GitHub 在 <img> 標籤中渲染 SVG,並執行其中的 CSS @keyframes,因此英雄區可以動畫化,而沒有 GIF 的條帶或體積問題。
建置 .github/readme/hero.svg(viewBox 約 1600×800,以 width="100%" 渲染):
- 場景就是產品。 用 SVG 形狀重現專案的真實英雄區或關鍵畫面:其背景圖像、以自己字型呈現的標題、以及一個正在執行工作的真實 UI 元素(一張卡片滑動、一個指令打字、一個圖表繪製、一個 Toast 通知)。一個想法,一個循環。
- 動畫: SVG 內部的
<style>區塊中的 CSS@keyframes,只作用於transform和opacity,任何會縮放或旋轉的元素都要加上transform-box: fill-box; transform-origin: center。一個 6–10 秒的循環,能無縫回到起始畫面,進入動作交錯,每個文字行停留足夠長的時間以供閱讀。在背景上加入一個緩慢的飄移(在循環中從 1.0 縮放到 1.05),使畫面永遠不會感覺靜止。CSStransform會取代元素的 SVGtransform屬性,所以使用外層的<g transform=…>定位,並動畫內層元素。 - 減少動畫: 將 keyframes 包裹在
@media (prefers-reduced-motion: no-preference)中,這樣選擇退出的讀者會看到已完成、靜止的畫面。靜止的畫面必須能單獨發布並展示產品,所以任何只在循環過程中出現的東西(一個匹配覆蓋層、一個 Toast)都應以opacity="0"屬性隱藏開始,並僅由其 keyframes 揭示。 - 自包含。 透過
<img>載入的 SVG 無法取得任何東西:無法透過 URL 取得網頁字型、無法取得外部圖像、無法執行腳本。將字型嵌入為 base64@font-face(Google Fonts 的latin檔案已經約 20 KB,可以完整嵌入;使用pyftsubset … --text="…" --flavor=woff2子集化其他字型,這需要一個較新的 fontTools),或將文字轉換為路徑。將照片嵌入為 base64 JPEG,並調整大小為英雄區所需的大小。避免使用<foreignObject>(Safari 在<img>內部不會渲染它)。保持檔案小於 ~1.5 MB。 - 兩種主題。 如果英雄區是全出血且不透明的,它在兩種主題下都有效;否則也製作
hero-dark.svg,並使用<picture>或#gh-dark-mode-only/#gh-light-mode-onlyURL 片段進行切換。 - 文字: 專案名稱和一句話介紹,要大(英雄區在手機上會縮小到約 40%)。不要放其他東西。
<p align="center">
<a href="<site or demo link>"><img src=".github/readme/hero.svg" alt="<Project> — <one-liner>" width="100%"></a>
</p>
也將靜止畫面以 1280×640 的大小捕捉到 .github/readme/social-preview.png(不透明),作為 repo 的社交卡片;在一個啟用減少動畫的無頭瀏覽器中渲染 SVG。
如果專案沒有值得動畫化的視覺識別(一個沒有 UI 的函式庫),則改為製作一個動態文字標誌:以合適字型呈現的名稱,一個能說明其功能的動作(一個值通過管道的流動、文字被格式化、測試變綠)。
示範,有邊框
按偏好順序:
- 宣傳影片。 在檢查步驟中找到或在影片步驟中製作的。如果
brag.mp4存在,從其最精彩的 4–8 秒製作一個循環預覽 GIF 或動畫 WebP。
…
(完整內容因篇幅限制截斷)