Comment écrire un bon README (avec exemple et générateur gratuit)

Un README est la première chose que l’on voit en ouvrant votre projet. Il doit répondre vite à trois questions : qu’est-ce que c’est, comment commencer, et ai-je le droit de l’utiliser ? Sinon, la plupart des visiteurs repartent, même si le code est excellent. Et dans six mois, la personne qui le lira sera peut-être vous.

Ce guide montre ce qu’un bon README doit contenir et dans quel ordre, avec un exemple complet. Si vous préférez ne pas partir d’une page blanche, le générateur de README gratuit l’écrit à partir d’un court formulaire.

Qu’est-ce qu’un fichier README ?

C’est un fichier texte placé dans le dossier principal d’un projet, généralement appelé README.md. Le .md signifie qu’il est écrit en Markdown, une façon simple de mettre du texte en forme. GitHub, GitLab et les sites similaires l’affichent automatiquement sur la page du projet : c’est en quelque sorte sa page d’accueil.

Que mettre dans un README, dans l’ordre

1. Nom et description en une ligne. Dites ce que le projet fait, pas comment il est construit. « Enregistrez vos recettes préférées et retrouvez-les en quelques secondes » vaut mieux que « Une application React et Node.js ».
2. Badges (facultatif). De petites étiquettes indiquant la licence, la version actuelle ou le nombre d’étoiles.
3. Sommaire. Utile dès que le README dépasse un écran.
4. À propos. Deux ou trois phrases : quel problème il résout et à qui il s’adresse.
5. Fonctionnalités. Une courte liste, pour voir d’un coup d’œil s’il répond au besoin.
6. Installation. Les commandes exactes, prêtes à copier. Testez-les vous-même sur une machine vierge : les étapes manquantes sont le problème le plus courant des README.
7. Utilisation. Le plus petit exemple qui fonctionne. Un court extrait de code en dit plus qu’une longue explication.
8. Capture d’écran. Dès qu’il y a une interface, une image évite un paragraphe.
9. Contribuer. Comment les autres peuvent aider, par exemple en ouvrant un ticket avant d’envoyer une modification.
10. Licence et auteur. Ce que l’on peut faire de votre travail, et qui l’a réalisé.

Un petit projet n’a pas besoin de tout cela. L’essentiel : nom, description, installation, utilisation et licence.

Un exemple complet de README

Voici un court README pour un petit projet, prêt à adapter :

# recipe-box

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Save your favourite recipes and find them again in seconds.

## Table of contents

- [About](#about)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

## About

A small app for people with too many recipes in too many places.
Everything is stored on your own computer.

## Features

- Search by ingredient
- Works offline
- Export to PDF

## Installation

```bash
git clone https://github.com/janedoe/recipe-box.git
cd recipe-box
npm install
```

## Usage

Start the app and open http://localhost:3000:

```bash
npm start
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

© 2026 Jane Doe

Comment en créer un avec le générateur

1. Ouvrez le générateur de README. Cliquez sur Exemple pour en voir un rempli, ou sur Effacer pour commencer le vôtre.
2. Remplissez le Nom du projet et la Description en une ligne. Ajoutez le Dépôt GitHub sous la forme propriétaire/nom et le Paquet npm si vous en avez : les badges et les liens les utilisent.
3. Remplissez les sections voulues, comme Fonctionnalités (une par ligne), Installation et Utilisation. Les sections vides ne sont pas incluses.
4. Cochez ou décochez Badges et Sommaire, et choisissez une Licence.
5. Vérifiez le résultat sous Aperçu, ou voyez le code sous Markdown, puis cliquez sur Copier ou Télécharger. Le fichier téléchargé porte une date dans son nom : renommez-le en README.md.

Vous pouvez écrire le README en anglais, espagnol, allemand ou français : Langue du README définit les titres et les phrases standard, et ce que vous saisissez reste tel quel. Les badges apparaissent comme des cadres avec leur nom dans l’aperçu, car il ne charge pas d’images d’autres sites ; sur GitHub, ils s’affichent normalement.

Quelle licence choisir ?

Sans licence, les autres n’ont pas clairement le droit d’utiliser votre code, même s’il est public. Voici les options du générateur, en bref. Il s’agit d’une information générale, pas d’un conseil juridique.

• MIT et ISC : courtes et permissives. Presque tout est permis tant que votre mention de copyright est conservée.
• Apache-2.0 : également permissive, avec une concession explicite de brevets.
• BSD-3-Clause : permissive, et personne ne peut utiliser votre nom pour promouvoir ses produits sans autorisation.
• MPL-2.0 : les modifications de vos fichiers doivent être partagées, mais ces fichiers peuvent faire partie d’un projet fermé plus grand.
• GPL-3.0 : tout ce qui est distribué à partir de votre code doit aussi être ouvert sous GPL.

Une étape que le README ne fait pas pour vous : la section Licence ne fait que mentionner la licence. Ajoutez aussi le texte complet dans un fichier nommé LICENSE. Sur GitHub, choisissez Add file, saisissez LICENSE comme nom et choisissez un modèle.

Erreurs courantes dans un README

• Commencer par la technique. Dites d’abord ce que le projet apporte au lecteur.
• Des commandes qui ne marchent pas. Exécutez-les vous-même et mettez-les à jour quand le projet change.
• Supposer des connaissances. Indiquez ce qu’il faut installer d’abord, comme Node.js ou Python, et en quelle version.
• Un mur de texte. Utilisez des titres, des listes courtes et des blocs de code.

Autres outils Markdown

• Générateur de tableaux Markdown : créez des tableaux pour votre README dans une grille, ou collez-les depuis Excel.
• Markdown en HTML : transformez votre README en page web. Voir aussi comment convertir du Markdown en HTML.

Questions fréquentes

Doit-il s’appeler README.md ?

Oui, si vous voulez que GitHub et les sites similaires l’affichent automatiquement. Placez-le dans le dossier principal du projet.

Ce que je saisis est-il envoyé ?

Non. Le README est créé dans votre navigateur : ce que vous saisissez ne quitte jamais votre appareil. Remplir le formulaire est gratuit ; copier ou télécharger le résultat compte comme une utilisation de votre quota quotidien.

Puis-je modifier le README plus tard ?

Oui. C’est un simple fichier texte : modifiez-le dans n’importe quel éditeur ou directement sur GitHub. Mettez-le à jour quand l’installation ou l’utilisation change.