Que fait brag-more ?
Tu l'as construit. Maintenant, fais en sorte que le dépôt en parle aussi. Le README est la première chose que quiconque voit sur GitHub ; transforme-le en une page d'accueil qui vend le projet en cinq secondes et emmène un inconnu de zéro à l'exécution en une minute.
Quel que soit le projet, le résultat doit ressembler au README d'un projet open-source bien aimé : confiant, scannable, visuel et vrai. Rien sur la page qui ne mérite pas sa place.
Usage : /brag-more [options]. Options (drapeaux ou langage naturel) :
| Option | Défaut |
|---|---|
--style clean|bold|minimal|showcase | déduit du projet (voir Styles) |
--preview | désactivé : écrit README.md sur place. Avec, écrit uniquement dans brag-output/repo/ et laisse README.md intact |
--no-banner | bannière activée |
--no-video | désactivé : si le projet n'a pas de vidéo, en créer une d'abord (voir La vidéo) |
--no-demo | démo activée quand il y a quelque chose à montrer |
Les fichiers de travail vont dans brag-output/repo/ (horodaté brag-output-YYYY-MM-JJ-HHmmss/repo/ si brag-output/ existe déjà et ne vient pas de cette exécution). Les ressources référencées par le README vont dans le dépôt, dans .github/readme/, pour qu'elles voyagent avec lui.
1. Inspection
Lis le projet, pas seulement l'ancien README :
- Le README existant, chaque ligne. C'est l'écriture de l'utilisateur. Garde tout ce qui est vrai et utile (étapes d'installation, tableaux de configuration, crédits, notes de licence, liens de sponsors, remerciements) ; restyle-le, ne le jette pas.
- Identité : couleurs et polices exactes de la marque depuis les feuilles de style ou la configuration du thème, le logo ou favicon, toute image de héros existante ou image OG.
- Ce que c'est : manifestes de paquets (
package.json,pyproject.toml,Cargo.toml,go.mod, …) pour le nom, la description, la version, la licence, les binaires et scripts ; le point d'entrée et les routes ou commandes principales pour les vraies fonctionnalités. - Comment l'exécuter : les commandes réelles d'installation et de démarrage depuis les scripts de manifeste,
Makefile,justfile, Dockerfile, ou workflow CI. Note les versions d'exécution que le projet impose. - Signaux pour les badges :
LICENSE,.github/workflows/*, si le paquet est publié (npm, PyPI, crates.io — vérifie le nom et le flagprivatedu manifest), le dépôt distant git (git remote get-url origin) pourpropriétaire/dépôt. - Sortie existante de brag : si
brag-output*/brag.mp4etbrag.jpgexistent, ce sont les meilleurs matériaux de démo sur la machine. Utilise les plus récents. S'il n'y en a pas, tu les créeras à l'étape suivante.
Ignore la sortie de build, les fichiers de verrouillage, .git/, les fichiers de variables d'environnement et secrets (.env, .env.*), les clés et informations d'identification, et tout ce que .gitignore exclut pour ces raisons.
Avant d'écrire, réponds : Qu'est-ce que c'est (une phrase qu'un inconnu comprend) ? Pour qui est-ce ? Quelle est la seule chose qu'il fait mieux que l'alternative ? Quel est l'accroche visuelle — la capture d'écran, le GIF ou la bannière qui fait arrêter de défiler ? Quelles sont les 3 à 5 vraies fonctionnalités ? Quel est le chemin le plus court du clone à l'exécution ?
Le README est public. N'y emporte jamais de secrets, jetons, noms d'hôtes internes, vrais noms de clients ou d'utilisateurs, adresses e-mail ou autres données personnelles, ni dans ses images. Si une capture d'écran montre de telles données, remplace-les par des substituts fictifs plausibles.
La vidéo (avant le plan, quand il n'y en a pas encore)
La meilleure démo du README est la vidéo de lancement du projet, donc brag-more la crée quand elle manque. Saute cette étape quand --no-demo ou --no-video est défini, ou quand un brag-output*/brag.mp4 existe déjà.
- Si la compétence
/bragest installée (vérifie la liste des compétences), exécute-la pour ce projet via l'outil Compétence, en transmettant toute demande de--toneou de format. Dis à l'utilisateur en une ligne : « Pas encore de vidéo de lancement, donc j'en crée une avec /brag d'abord. » - Sinon, lis
<répertoire-compétence>/video.md(le workflow vidéo léger fourni ici, de brag-slim) et suis-le. Il ne nécessite que des outils déjà sur la machine. - Quand il se termine, la vidéo, l'affiche et la copie de partage sont dans
brag-output/. Continue avec le README en les utilisant comme démo.
Si la création de la vidéo échoue ou si l'utilisateur ne veut pas attendre, continue sans elle et utilise les solutions de repli sous Démo.
2. Plan
Écris brag-output/repo/readme-plan.md : l'accroche, le style choisi, l'ordre des sections, quels visuels tu vas créer et ce que chacun montre, quels badges sont justifiés (et la preuve pour chacun), et ce que tu conserves de l'ancien README.
Forme : une forme de départ, pas un modèle. Supprime toute section qui serait vide ou du remplissage.
- Héros — le héros SVG animé (voir Construction), puis centré : l'accroche, une courte rangée de badges, et une ligne de navigation de liens (Démo · Install · Docs · …).
- Démo — le produit en action, juste en dessous du héros, encadré : la boucle vidéo brag, un GIF de l'interface réelle, ou un enregistrement de terminal. Un visuel, grand.
- Pourquoi — 2 à 4 phrases : ce qu'il fait pour l'utilisateur et ce qui le distingue, dans les propres mots du projet. Pour un outil de développeur, un bloc de code de 3 à 5 lignes qui est l'accroche bat un paragraphe (
bun run index.tsx # TS et JSX prêts à l'emploi). - Vitrine de fonctionnalités — 3 à 6 vraies fonctionnalités, chacune avec son propre petit visuel : une capture d'écran recadrée de l'interface réelle, un GIF de terminal par commande, ou un extrait de code et sa sortie. Dispose les visuelles sous forme de cartes côte à côte (voir Construction). Les fonctionnalités purement textuelles obtiennent une introduction en gras et une ligne.
- Démarrage rapide — copiable-collable, dans l'ordre, chaque commande vérifiée par rapport au projet. Prérequis d'abord.
- Utilisation — un ou deux exemples réels : une commande et sa sortie, un extrait de code, ou un bloc de configuration.
- Comment ça marche — optionnel. Un court paragraphe ou un diagramme Mermaid quand l'architecture est la partie intéressante.
- Tout le reste de l'ancien README — configuration, FAQ, feuille de route, contribution, crédits — rangé, plié dans
<details>quand c'est long. - Pied de page — ligne de licence, plus la bande artistique de fermeture (voir Construction).
Lois du README
- Vrai. Chaque affirmation, chiffre, fonctionnalité et badge doit être soutenu par le projet. Pas d'étoiles, téléchargements, benchmarks, témoignages ou logos « utilisé par » inventés. Un badge n'apparaît que si ce vers quoi il pointe existe (un paquet publié, un vrai workflow, un fichier de licence).
- Fonctionne. Chaque commande dans Démarrage rapide et Utilisation existe dans le projet telle qu'écrite. Si tu peux l'exécuter en toute sécurité (installer, construire,
--help, tests), fais-le. Si une étape nécessite des secrets ou un service payant, dis-le clairement au lieu de le cacher. - Test des cinq secondes. Quelqu'un qui atterrit sur le dépôt depuis un tweet sait ce que c'est, le voit fonctionner, et trouve la commande d'installation sans défiler au-delà du premier écran.
- Montre la chose. La démo montre le vrai produit en action, pas une animation de logo ou un art abstrait. Réutilise l'interface réelle, le CSS réel, le texte réel.
- Dis ce qu'est le dépôt. Si le dépôt est le site web, la page d'atterrissage ou la démo pour un produit, dis-le dans l'accroche ; n'implique pas que les gens peuvent télécharger une application ou installer un paquet que le dépôt ne fournit pas.
- Spécifique. Il doit sembler écrit pour ce projet exact. « Ultra-rapide », « transparent », « nouvelle génération », « rationalisez votre flux de travail » sont interdits, sauf si le projet les mérite mesurablement.
- Scannable. Paragraphes courts, titres qui disent quelque chose, une idée par puce. Émojis dans les titres seulement si la propre voix du projet les utilise, et alors avec parcimonie (le style
showcaseest l'exception : un émoji par titre de section, par conception). - Les deux thèmes. Les lecteurs GitHub utilisent le mode clair et le mode sombre. Chaque image a un bon rendu sur
#ffffffet sur#0d1117: PNG transparents avec une bordure visible, ou<picture>avec une sourceprefers-color-schemepar thème. - S'adapte à la colonne. La colonne README fait environ 830 px de large sur desktop et beaucoup moins sur téléphone. Le texte de la bannière reste lisible lorsqu'il est réduit à la largeur du téléphone ; les tableaux ont peu de colonnes ; pas de grandes mises en page HTML brutes qui cassent sur mobile.
- Chaque lien résout. Les liens relatifs pointent vers des fichiers qui existent ; les ancres correspondent aux titres réels.
Styles
| Style | Sensation | Quand l'utiliser |
|---|---|---|
clean | Héros animé avec mouvement retenu, démo encadrée, cartes soignées | La plupart des projets ; le défaut |
bold | Héros à fond perdu dans les couleurs de la marque avec un moment animé plus grand, accroche percutante, démo au premier plan | Applications grand public, projets ludiques, lancements |
minimal | Petit logo animé + nom + accroche, sections simples | Bibliothèques, CLI, infrastructure, outils sérieux |
showcase | Le README technique dense avec sections émojies (pense à un hackathon gagnant ou un projet de recherche) : une vraie capture d'écran du produit en haut, une ligne de prix ou de statut, puis une section menée par un émoji par sujet | Hackathon, recherche, ML, données, ou projets scientifiques ; tout ce qui a une vraie profondeur à montrer. Choisis-le quand l'utilisateur demande « quelque chose comme Find My Shark » ou un README détaillé de style documentation |
La recette showcase
Modélisé sur le README Find-My-Shark du propriétaire. Garde ce qui le fait fonctionner, et corrige ce qui ne fonctionne pas :
- Titre avec un émoji et la ligne de réussite en dessous (« NASA Space Apps 2025, Galactic Impact Winner »), seulement si le projet l'a vraiment mérité. Demande ou lis-le depuis l'ancien README ; n'en invente jamais un.
- Une vraie capture d'écran ou le GIF démo directement sous le titre, encadré (voir Démo, encadré). Garde le héros animé seulement s'il ajoute quelque chose ; ici, le vrai produit est la star.
- Un pitch de 2 à 3 lignes et la ligne « pourquoi c'est important », puis des sections chacune menée par un émoji : Fonctionnalités, Région/Portée ou Entrées, Sources de données (tableau), Comment ça marche ou Modèle mathématique, Démarrage rapide (installation, utilisation de base, utilisation de l'API), Structure du projet (arbre annoté), Configuration (la vraie config), Fichiers de sortie, Options de ligne de commande, Contexte, Extensions futures, Tests, Journalisation, tagline de clôture.
- Inclus seulement les sections pour lesquelles le projet a un contenu réel. La profondeur de niveau hackathon est le but, donc garde les spécificités : paramètres, formules, seuils, noms d'ensembles de données et arbre du projet.
- Corrige les erreurs habituelles : utilise l'URL de clone réelle (jamais
votre-nom-utilisateur), remplace les entrées obsolètes du bloc de code de l'arbre du projet par ce qui existe, ajoute une table des matières ou une ligne de liens rapides quand il y a plus de six sections, enveloppe les longues sections de référence (options CLI, configuration complète, contexte scientifique) dans<details>, ajoute des badges pour la pile réelle (version Python, licence, bibliothèques clés) et une<picture>ou une capture d'écran encadrée pour les deux thèmes, et définis la description et les sujets du dépôt à la livraison. - Ancres avec émoji : GitHub supprime l'émoji du slug d'un titre mais garde le trait d'union, donc
## 🚀 Démarrage rapidedevient#-démarrage-rapide, pas#démarrage-rapide. Écris chaque lien de navigation et lien de badge de cette façon et vérifie chacun par rapport à son titre. Le résumé<details>n'est pas un titre et n'a pas d'ancre. - Suis toujours chaque loi du README (Vrai, Fonctionne, Les deux thèmes) et l'étape Vérification.
3. Construction
Les meilleurs README sur GitHub (Excalidraw, Scalar, Supabase, Charm, Rich, Bun) partagent quelques astuces. Utilise-les toutes ; c'est ce qui fait que celui-ci arrête le défilement.
Le héros : un SVG animé
C'est la signature. Une bannière statique se lit comme un modèle ; un héros qui bouge — dans les propres couleurs, polices et interface du projet — se lit comme fait pour ce projet. GitHub rend un SVG dans une balise <img> avec son CSS @keyframes en cours d'exécution, donc le héros peut animer sans les bandes ou le poids d'un GIF.
Construis .github/readme/hero.svg (viewBox environ 1600×800, rendu à width="100%") :
- La scène est le produit. Recrée le vrai héros du projet ou l'écran clé en formes SVG : son image de fond, son titre dans sa propre police, et un élément d'interface réel faisant son travail (une carte glissant, une commande tapant, un graphique se dessinant, un toast atterrissant). Une idée, une boucle.
- Mouvement : CSS
@keyframesdans un bloc<style>à l'intérieur du SVG, seulement surtransformetopacity, avectransform-box: fill-box; transform-origin: centersur tout ce qui se met à l'échelle ou tourne. Une boucle de 6 à 10 s qui revient à son image de départ de manière transparente, entrées décalées, chaque ligne de texte installée assez longtemps pour être lue. Ajoute une dérive lente sur le fond (une échelle de 1,0 à 1,05 sur la boucle) pour que l'image ne donne jamais l'impression d'être figée. UnetransformCSS remplace l'attributtransformSVG d'un élément, donc positionne les choses avec un<g transform=…>extérieur et anime un élément intérieur. - Mouvement réduit : enveloppe les keyframes dans
@media (prefers-reduced-motion: no-preference)pour que les lecteurs qui optent pour moins d'animation voient l'image terminée et stable. L'image stable doit pouvoir être publiée seule et montrer le produit, donc tout ce qui n'apparaît qu'au milieu de la boucle (une superposition de correspondance, un toast) commence caché avec un attributopacity="0"et n'est révélé que par ses keyframes. - Autonome. Un SVG chargé via
<img>ne peut rien récupérer : pas de polices web par URL, pas d'images externes, pas de scripts. Incorpore les polices en base64@font-face(les fichierslatinde Google Fonts font déjà ~20 Ko et peuvent être incorporés en entier ; sous-ensemble d'autres polices avecpyftsubset … --text="…" --flavor=woff2, ce qui nécessite une version récente de fontTools), ou convertis le texte en chemins. Incorpore les photos en base64 JPEG, redimensionnées à ce dont le héros a besoin. Évite<foreignObject>(Safari ne le rendra pas à l'intérieur d'<img>). Garde le fichier sous ~1,5 Mo. - Les deux thèmes. Si le héros est à fond perdu et opaque, il fonctionne sur les deux ; sinon, crée aussi
hero-dark.svget échange avec<picture>ou les fragments d'URL#gh-dark-mode-only/#gh-light-mode-only. - Texte : le nom du projet et l'accroche, en grand (le héros rétrécit à ~40 % sur téléphone). Rien d'autre.
<p align="center">
<a href="<lien site ou démo>"><img src=".github/readme/hero.svg" alt="<Projet> — <accroche>" width="100%"></a>
</p>
Capture aussi l'image stable à 1280×640 vers .github/readme/social-preview.png (opaque) pour la carte sociale du dépôt ; rends le SVG dans un navigateur sans tête avec mouvement réduit activé.
Si le projet n'a pas d'identité visuelle digne d'être animée (une bibliothèque sans interface), fais plutôt un mot-symbole animé : le nom dans une police appropriée, un mouvement qui dit ce qu'il fait (une valeur circulant dans un tuyau, du texte formaté, un test devenant vert).
Démo, encadrée
Par ordre de préférence :
- La vidéo brag. Celle trouvée lors de l'Inspection ou créée à l'étape La vidéo. Si un
brag.mp4existe, fais un GIF de prévisualisation en boucle ou un WebP animé à partir de ses 4 à 8 secondes les plus fortes, redimensionné à une largeur de 800 px, limité à 30 ips et à une palette de 256 couleurs. Pour la capture d'écran vidéo, utilise l'imagebrag.jpgla plus récente existante ou la dernière image de la vidéo, redimensionnée à 1280×720, opacifiée sur un fond de la couleur de fond du dépôt (#ffffffou#0d1117) pour que la transition de thème soit propre en<picture>, et stockée dans.github/readme/demo-preview.png. - Une vraie capture d'écran du produit. Ouvrir l'URL du projet ou le serveur de développement, capturer la fenêtre du navigateur à 1280×800 (image fixe, pas de GIF), recadrer pour supprimer les chrome du navigateur, superposer une légère bordure du trait de la couleur de la marque, et
… [tronqué pour la traduction]
README Lois (suite)
- Fonctionne. Chaque commande dans Démarrage rapide et Utilisation existe dans le projet telle qu'écrite. Si tu peux l'exécuter en toute sécurité (installer, construire,
--help, tests), fais-le. Si une étape nécessite des secrets ou un service payant, dis-le clairement au lieu de le cacher. - Test des cinq secondes. Quelqu'un qui atterrit sur le dépôt depuis un tweet sait ce que c'est, le voit fonctionner, et trouve la commande d'installation sans défiler au-delà du premier écran.
- Montre la chose. La démo montre le vrai produit en action, pas une animation de logo ou un art abstrait. Réutilise l'interface réelle, le CSS réel, le texte réel.
- Dis ce qu'est le dépôt. Si le dépôt est le site web, la page d'atterrissage ou la démo pour un produit, dis-le dans l'accroche ; n'implique pas que les gens peuvent télécharger une application ou installer un paquet que le dépôt ne fournit pas.
- Spécifique. Il doit sembler écrit pour ce projet exact. « Ultra-rapide », « transparent », « nouvelle génération », « rationalisez votre flux de travail » sont interdits, sauf si le projet les mérite mesurablement.
- Scannable. Paragraphes courts, titres qui disent quelque chose, une idée par puce. Émojis dans les titres seulement si la propre voix du projet les utilise, et alors avec parcimonie (le style
showcaseest l'exception : un émoji par titre de section, par conception). - Les deux thèmes. Les lecteurs GitHub utilisent le mode clair et le mode sombre. Chaque image a un bon rendu sur
#ffffffet sur#0d1117: PNG transparents avec une bordure visible, ou<picture>avec une sourceprefers-color-schemepar thème. - S'adapte à la colonne. La colonne README fait environ 830 px de large sur desktop et beaucoup moins sur téléphone. Le texte de la bannière reste lisible lorsqu'il est réduit à la largeur du téléphone ; les tableaux ont peu de colonnes ; pas de grandes mises en page HTML brutes qui cassent sur mobile.
- Chaque lien résout. Les liens relatifs pointent vers des fichiers qui existent ; les ancres correspondent aux titres réels.
4. Vérification
Relis le README modifié avec un regard neuf. Résout-il chaque loi du README ? Es-tu prêt à le défendre face à l'utilisateur ?
- Le README est vrai. Pas de distorsion. Pas de fonctionnalité manquante comme expédiée. Pas de badge de constructeur de communauté pour un projet solo. Vérifie chaque badge contre sa source : le paquet est-il sur PyPI (
pip install nom-paquetfonctionne), npm (npm view nom-paquetretourne un JSON), crates.io, etc. ? Le workflow de test a-t-il une mauvaise note ? - Il tourne. Relis chaque commande que tu as écrite. Vérifie le message de validation le plus récent pour le répertoire de travail du projet : est-ce que l'installation réussit ? Les tests passent-ils ? Les chemins de fichiers sont-ils exacts ?
- L'image de héros se charge dans un
<img>SVG (pas d'images externes, pas de<foreignObject>, pas de polices à récupérer). - Les thèmes clair et sombre. Les images transparentes ont une légère bordure ou un arrière-plan pour être lisibles dans les deux thèmes, ou utilise
<picture>. - Les ressources sont engagées. Les images et le SVG dans
.github/readme/sont engagés dans le dépôt avant de livrer le README. - Le plan est complet.
brag-output/repo/contientreadme-plan.md, le README révisé (README.md), et chaque ressource visuelle (.github/readme/hero.svg,hero-dark.svg,social-preview.png,demo-preview.gifou.webp,demo-preview.png, et toutes les images de vitrine de fonctionnalités).
Configuration du dépôt
Avant de finaliser, ajuste les métadonnées du dépôt pour qu'elles correspondent au nouveau README :
- Description : l'accroche, en une phrase (max 350 caractères).
- Sujets : 3–8 sujets pertinents (langage, framework, cas d'usage, nom de l'outil).
- Site web : l'URL du site ou de la page de démo (pas le dépôt lui-même).
- Image sociale :
.github/readme/social-preview.png.
5. Livraison
Écris le README finalisé dans README.md (ou dans brag-output/repo/README.md si --preview).
Confirme dans la sortie :
- Le nom du projet
- Un résumé de la structure : « Héros animé · Démo · Fonctionnalités (N) · Démarrage rapide · Pied de page »
- Les badges ajoutés et leur justification (par exemple « Badges : la licence MIT a un fichier → badge », « npm publié → badge de version et de téléchargements », « Workflow CI → badge de build passant »)
- Les ressources créées : les chemins de fichiers vers le SVG du héros et l'image de démo (relatifs à la racine du dépôt)
- Ce qui est conservé de l'ancien README : sections, notes de licence, crédits, etc.
- Changer l'angle du concept si l'accroche originale était trompeuse
- Toute vidéo ou démo créée, où elle a été placée, et comment l'utiliser ultérieurement
Pour que le dépôt soit aussi beau que le projet qu'il contient.