/brag-more
你构建了它,现在让仓库也炫耀一下吧。README 是任何人看到 GitHub 项目时首先映入眼帘的东西;将其转化为一个能在五秒内推销项目,并让陌生人在一分钟内从零开始运行的首页。
无论项目是什么,最终结果都应像一封来自备受喜爱的开源项目的 README:自信、可扫描、可视化且真实。页面上没有任何无用的内容。
用法:/brag-more [选项]。选项(标志或自然语言):
| 选项 | 默认值 |
|---|---|
--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 引用的资源放在仓库的 .github/readme/ 目录下,以便随项目一起提供。
1. 检查
阅读项目,而不仅仅是旧的 README:
- 现有的 README,逐行阅读。这是用户的写作。保留所有真实且有用的内容(安装步骤、配置表、致谢、许可说明、赞助商链接、鸣谢);进行重新排版,而不是直接丢弃。
- 身份标识: 来自样式表或主题配置的确切品牌颜色和字体,logo 或 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 个真实功能是什么?从克隆到运行的最短路径是什么?
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 英雄(见构建),然后居中:一行介绍、短徽章行、导航链接行(演示 · 安装 · 文档 · …)。
- 演示 — 产品正在使用中,就在英雄区下方,边框内:brag 视频循环、真实 UI 的 GIF 或终端录制。一个大的视觉元素。
- 为什么 — 2-4 句话:它为用户做什么,以及它与其他方案的区别,用项目自己的语言表达。对于开发者工具,一个 3-5 行的代码块比段落更有说服力(
bun run index.tsx # TS and JSX out of the box)。 - 功能展示 — 3-6 个真实功能,每个都有自己小的视觉元素:真实 UI 的裁剪截图、每个命令的终端 GIF,或代码片段及其输出。视觉元素排版为并排卡片(见构建)。纯文本功能有粗体引导行和一行描述。
- 快速开始 — 可复制粘贴的,按顺序排列,每个命令都已针对项目验证。先写先决条件。
- 用法 — 一个或两个真实示例:命令及其输出、代码片段或配置块。
- 工作原理 — 可选。当架构是有趣的部分时,提供简短段落或 Mermaid 图。
- 旧 README 中的其他所有内容 — 配置、FAQ、路线图、贡献、致谢 —— 整理后,长内容折叠到
<details>中。 - 页脚 — 许可证行,以及结尾的艺术条(见构建)。
README 法则
- 真实。 每个声明、数字、功能和徽章都必须有项目支持。不得编造星标、下载量、基准测试、推荐语或“被...使用”的 logo。只有指向存在的内容(已发布的包、真实的工作流、许可证文件)时,徽章才能出现。
- 可运行。 快速开始和用法中的每个命令都必须在项目中原样存在。如果可以安全运行(安装、构建、
--help、测试),就运行它。如果某个步骤需要密钥或付费服务,请明确说明而不是隐藏。 - 五秒测试。 从推文中跳转到仓库的人能在不滚动第一屏的情况下知道它是什么、看到它在工作、找到安装命令。
- 展示实物。 演示显示真实产品正在使用中,而不是 logo 动画或抽象艺术。重用真实 UI、真实 CSS、真实文案。
- 指出仓库是什么。 如果仓库是网站、登录页或产品的演示,请在一行介绍中说明;不要暗示人们可以下载应用程序或安装仓库未提供的包。
- 具体。 它必须感觉是为这个确切项目编写的。“极快”、“无缝”、“下一代”、“简化你的工作流”是被禁止的,除非项目可衡量地值得它们。
- 可扫描。 短段落、有意义的标题、每个要点一个想法。仅当项目自己的语气使用表情符号时才在标题中使用表情符号,并且要克制(
showcase风格是例外:每个章节标题一个表情符号,这是特意设计的)。 - 双主题。 GitHub 阅读器使用浅色和深色模式。每张图片在
#ffffff和#0d1117上看起来都很好:带有可见边缘的透明 PNG,或使用<picture>为每个主题提供prefers-color-scheme来源。 - 适配列宽。 README 列在桌面上约 830px 宽,在手机上更窄。横幅文字在缩放到手机宽度时仍应清晰;表格列数少;避免在移动设备上撑坏宽原始 HTML 布局。
- 每个链接都可解析。 相对链接指向存在的文件;锚点匹配真实的标题。
风格
| 风格 | 感觉 | 使用时机 |
|---|---|---|
clean | 带有克制运动的动画英雄、边框演示、整洁卡片 | 大多数项目;默认 |
bold | 使用品牌颜色的全出血英雄,带有更大的动画时刻、有力的一行介绍、演示居中 | 消费者应用、趣味项目、发布 |
minimal | 小的动画 logo 徽标 + 名称 + 一行介绍,简洁的章节 | 库、CLI、基础设施、严肃工具 |
showcase | 密集的、表情符号分节的技术 README(像获奖的黑客松或研究项目):顶部是真实产品截图、奖项或状态行,然后每个话题一个表情符号引导的章节 | 黑客松、研究、ML、数据或科学项目;任何有深度可展示的项目。当用户要求“像 Find My Shark 那样”或详细、文档风格的 README 时选择它 |
showcase 配方
以项目所有者 Find-My-Shark README 为蓝本。保留其精华,修复其缺陷:
- 带有一个表情符号的标题和下面的成就行(“NASA Space Apps 2025, Galactic Impact Winner”),仅当项目真正获得该成就时才使用。从旧 README 中询问或读取;绝不编造。
- 标题下直接放一个真实截图或演示 GIF,带边框(见演示,边框)。仅当动画英雄有额外价值时才保留它;这里真实产品才是主角。
- 2-3 行介绍和“为什么重要”行,然后每个章节由一个表情符号引导:功能、区域/范围或输入、数据源(表格)、工作原理或数学模型、快速开始(安装、基本用法、API 用法)、项目结构(带注释的树)、配置(真实配置)、输出文件、命令行选项、背景、未来扩展、测试、日志、结尾标语。
- 仅包括项目有真实内容的章节。 深度是关键,因此保持具体:参数、公式、阈值、数据集名称和项目树。
- 修复常见的失误: 使用真实的克隆 URL(绝不是
your-username)、用存在的条目替换项目树代码块中的过时条目、一旦有超过六个章节就添加目录或快速链接行、将长的参考章节(CLI 选项、完整配置、科学背景)包装在<details>中、为真实技术栈添加徽章(Python 版本、许可证、关键库)、为双主题提供<picture>或带边框的截图、在交付时设置仓库描述和话题。 - 带表情符号的锚点: GitHub 从标题的 slug 中移除表情符号但保留连字符,所以
## 🚀 Quick Start是#-quick-start,而不是#quick-start。以这种方式编写每个导航链接和徽章链接,并检查每个链接是否与其标题匹配。<details>摘要不是标题,也没有锚点。 - 仍然遵循每条 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=…>定位元素,并动画化内部元素。 - 减少动效: 将关键帧包装在
@media (prefers-reduced-motion: no-preference)中,以便选择退出的读者看到完整、稳定的帧。稳定帧必须能独立发布并展示产品,因此任何仅在循环中间出现的内容(匹配叠加、toast)都以opacity="0"属性开始隐藏,仅由其关键帧揭示。 - 自包含。 通过
<img>加载的 SVG 不能获取任何内容:不能通过 URL 使用 web 字体、不能使用外部图像、不能使用脚本。将字体作为 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="<站点或演示链接>"><img src=".github/readme/hero.svg" alt="<Project> — <one-liner>" width="100%"></a>
</p>
还要将稳定帧捕获为 1280×640 到 .github/readme/social-preview.png(不透明)用于仓库的社交卡片;在无头浏览器中渲染 SVG,开启减少动效。
如果项目没有值得动画化的视觉身份(没有 UI 的库),则制作一个动画文字标记:使用合适的字体显示名称,一个动效说明它的功能(值流过管道、文本被格式化、测试变绿)。
演示,边框内
按优先顺序:
- brag 视频。 在检查中找到或在视频步骤中制作的视频。如果存在
brag.mp4,从其最强的 4-8 秒制作一个循环预览 GIF 或动画 WebP。