Créez un README.md GitHub complet et professionnel via un formulaire simple. Badges Shields.io, installation, usage, contribution, aperçu Markdown en temps réel.
Générateur de README.md GitHub
Informations du projet
Badges
Pourquoi un bon README est crucial ?
Le README.md est la première page que voit un visiteur sur votre dépôt GitHub. C'est votre carte de visite, votre page d'accueil, votre documentation d'entrée. Un README de qualité peut faire la différence entre un projet adopté massivement et un projet ignoré.
Impact mesurable d'un bon README
- +47% d'étoiles en moyenne pour les projets avec un README structuré (GitHub Analysis 2023)
- Confiance immédiate — Les développeurs jugent la qualité d'un projet à son README en moins de 30 secondes
- Adoption accélérée — Un guide d'installation clair réduit le friction d'onboarding
- Moins d'issues — Une bonne documentation préemptive évite les questions répétitives
- Crédibilité professionnelle — Pour les recruteurs qui inspectent votre GitHub
Le README comme documentation vivante
Un README n'est pas un document figé. Il doit évoluer avec le projet. Les projets open source les plus populaires (React, Vue, Express, Laravel…) maintiennent un README à jour qui reflète fidèlement l'état actuel du projet.
Structure d'un README professionnel
Un README complet suit une structure logique qui guide le lecteur du général au particulier. Voici l'anatomie recommandée :
Sections essentielles (ordre recommandé)
| Section | Contenu | Priorité |
|---|---|---|
| En-tête + Badges | Nom, statut CI/CD, version, licence | 🔴 Obligatoire |
| Description | Résumé en 1–3 phrases, valeur ajoutée | 🔴 Obligatoire |
| Table des matières | Navigation rapide (pour les READMEs longs) | 🟡 Recommandé |
| Prérequis | Node 20+, Python 3.10+, Docker… | 🔴 Obligatoire |
| Installation | Étapes claires et copiables | 🔴 Obligatoire |
| Utilisation | Commandes, exemples de code | 🔴 Obligatoire |
| Fonctionnalités | Liste des capacités clés | 🟡 Recommandé |
| Configuration | Variables d'environnement, fichiers de config | 🟡 Selon projet |
| Contribution | Comment contribuer, conventions | 🟡 Si open source |
| Licence | Type de licence | 🔴 Obligatoire |
Template Markdown minimal
# Nom du Projet
> Description courte et percutante du projet.
[](LICENSE)
## 🚀 Installation
```bash
git clone https://github.com/user/projet.git
cd projet
npm install
```
## 📖 Utilisation
```bash
npm run dev
```
## 🤝 Contribution
Les PRs sont les bienvenues ! Voir [CONTRIBUTING.md](CONTRIBUTING.md).
## 📄 Licence
Ce projet est sous licence [MIT](LICENSE).Badges GitHub avec Shields.io
Shields.io est le service de référence pour générer des badges dynamiques pour vos READMEs GitHub. Ces badges affichent en temps réel des informations sur votre dépôt.
Syntaxe générale
Badges les plus utilisés
- Licence —
img.shields.io/github/license/user/repo - Stars —
img.shields.io/github/stars/user/repo - Version npm —
img.shields.io/npm/v/package-name - CI/CD Status —
img.shields.io/github/actions/workflow/status/... - Coverage —
img.shields.io/codecov/c/github/user/repo - Downloads npm —
img.shields.io/npm/dm/package-name - Taille du bundle —
img.shields.io/bundlephobia/min/package
?style=flat-square ou ?style=for-the-badge pour changer le style des badges. Le style for-the-badge est le plus visuellement impactant.
Astuces Markdown avancées pour GitHub
GitHub Flavored Markdown (GFM) supporte des fonctionnalités avancées au-delà du Markdown standard :
Syntaxe GitHub spécifique
<!-- Sections repliables -->
<details>
<summary>Voir plus de détails</summary>
Contenu caché ici...
</details>
<!-- Notes et avertissements (GitHub 2023+) -->
> [!NOTE]
> Information importante pour l'utilisateur.
> [!WARNING]
> Avertissement critique.
> [!TIP]
> Conseil pratique.
<!-- Alignement de tableaux -->
| Gauche | Centre | Droite |
|:-------|:------:|-------:|
| A | B | C |Liens automatiques et mentions
<!-- Lien vers un fichier du repo -->
[CONTRIBUTING.md](./CONTRIBUTING.md)
<!-- Lien vers un issue ou PR -->
Fixes #42
Resolves #123
<!-- Mention d'un utilisateur -->
Créé par @monpseudo
<!-- Badge cliquable -->
[](https://github.com/u/r/actions)Images et GIFs de démo
Ajouter des captures d'écran ou un GIF de démonstration augmente drastiquement l'attractivité d'un projet :
<!-- Image centrée -->
<p align="center">
<img src="docs/screenshot.png" alt="Démo" width="600">
</p>
<!-- GIF de démo -->
<!-- Deux images côte à côte -->
| Avant | Après |
|-------|-------|
|  |  |README selon le type de projet
La structure idéale d'un README varie selon la nature du projet :
Bibliothèque / package npm
- Badge npm version + téléchargements hebdomadaires
- Installation :
npm installouyarn add - API Reference complète avec exemples
- Tableau de compatibilité (versions Node, navigateurs)
Application web / SaaS
- Screenshot ou GIF de démo en haut du README
- Instructions Docker (
docker-compose up) - Variables d'environnement documentées
- Lien vers la démo en ligne
CLI / outil terminal
- Exemples de commandes en premier plan
- Tableau des options et flags
- Asciinema ou GIF du terminal en action
Projet de formation / portfolio
- Technologies utilisées avec badges
- Objectifs d'apprentissage
- Lien vers la démo déployée
- Ce que vous avez appris
docs/ avec CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md et SECURITY.md. Le README les référence, mais reste lui-même concis.
FAQ — Questions fréquentes
Quelle extension utiliser : .md ou .markdown ?
.md est universellement reconnu par GitHub, GitLab, Bitbucket et les éditeurs. C'est l'extension standard à utiliser.
Comment générer une table des matières automatique ?
GitHub génère automatiquement une TOC dans la sidebar depuis 2021. Pour l'inclure dans le README lui-même, utilisez l'outil doctoc :
npx doctoc README.mdComment mettre à jour automatiquement la version dans le README ?
Dans votre pipeline CI/CD GitHub Actions :
- name: Update version badge
run: |
VERSION=$(node -p "require('./package.json').version")
sed -i "s/version-[0-9.]*/version-${VERSION}/g" README.mdPeut-on utiliser HTML dans un README GitHub ?
Oui, GitHub autorise un sous-ensemble d'HTML dans les fichiers Markdown. Tags supportés : <details>, <summary>, <p align>, <img>, <br>, <kbd>, <sup>, <sub>. Les scripts et styles sont bloqués.
Comment créer un README de profil GitHub ?
Créez un repo public avec le même nom que votre pseudo GitHub (ex: monpseudo/monpseudo). Le README de ce repo s'affiche sur votre profil GitHub. Vous pouvez y inclure des stats, des badges de compétences et des projets épinglés.
Quel outil pour vérifier le rendu avant de pusher ?
- VS Code + extension "Markdown Preview Enhanced"
- Grip (Python) — rendu GitHub-fidèle en local :
pip install grip && grip README.md - GitHub.dev — appuyez sur
.dans votre repo pour ouvrir VS Code en ligne
Les emojis fonctionnent-ils dans le README ?
Oui, GitHub supporte la syntaxe :emoji: (ex: :rocket: → 🚀) et les emojis Unicode directement. Les emojis dans les titres apparaissent aussi dans la table des matières automatique de GitHub.
