Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.
GitHub AE est actuellement en version limitée.

À propos des README

Vous pouvez ajouter un fichier README à votre référentiel pour expliquer aux autres personnes pourquoi votre projet est utile, ce qu’elles peuvent faire avec votre projet et comment elles peuvent l’utiliser.

À propos des README

Vous pouvez ajouter un fichier README à un référentiel pour communiquer des informations importantes sur votre projet. Un fichier README, ainsi qu’une licence de dépôt, fichier de citation, pour communiquer les attentes de votre projet et vous aider à gérer les contributions.

Pour plus d’informations sur la fourniture de recommandations pour votre projet, consultez "Configuration de votre projet pour des contributions saines. »

Un README est souvent le premier élément qu’un visiteur verra lors de la consultation de votre référentiel. Les fichiers README incluent généralement des informations sur :

  • Ce que le projet fait
  • Pourquoi le projet est utile
  • Prise en main du projet par les utilisateurs
  • Où les utilisateurs peuvent obtenir de l’aide sur votre projet
  • Qui maintient et contribue au projet

Si vous placez votre fichier README dans le répertoire .github caché, racine ou docs de votre référentiel, GitHub AE reconnaît et présente automatiquement votre fichier README pour les visiteurs du référentiel.

Si un référentiel contient plusieurs fichiers README, le fichier affiché est choisi parmi les emplacements suivants dans cet ordre : répertoire .github, puis répertoire racine du dépôt et enfin répertoire docs.

Page principale du référentiel github/scientist et son fichier README

Fichier README sur votre référentiel nom d’utilisateur/nom d’utilisateur

Table des matières générée automatiquement pour les fichiers README

Pour l’affichage rendu d’un fichier Markdown dans un référentiel, y compris les fichiers README, GitHub AE génère automatiquement une table des matières en fonction des titres de section. Vous pouvez afficher la table des matières d’un fichier README en cliquant sur l’icône de menu en haut à gauche de la page rendue.

README avec table des matières générée automatiquement

Liens de section dans les fichiers README et les pages d’objets blob

Vous pouvez accéder directement à une section d’un fichier affiché en pointant sur le titre de section pour exposer le lien :

Lien de section dans le fichier README pour le dépôt github/scientist

Liens relatifs et chemins d’accès aux images dans les fichiers README

Vous pouvez définir des liens et des chemins d’image relatifs dans vos fichiers affichés pour aider les lecteurs à accéder à d’autres fichiers de votre dépôt.

Un lien relatif est relatif par rapport au fichier actuel. Par exemple, si vous avez un fichier README à la racine de votre dépôt et que vous avez un autre fichier dans docs/CONTRIBUTING.md, le lien relatif vers CONTRIBUTING.md dans votre fichier README peut ressembler à ceci :

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub AE transforme automatiquement votre lien ou votre chemin d’image relatif en fonction de la branche où vous vous trouvez, pour que le lien ou le chemin fonctionne toujours. Le chemin du lien sera relatif au fichier actif. Les liens commençant par / seront relatifs à la racine du dépôt. Vous pouvez utiliser tous les opérandes de lien relatif, comme ./ et ../.

Les liens relatifs sont plus pratiques pour les utilisateurs qui clonent votre dépôt. Les liens absolus peuvent ne pas fonctionner dans les clones de votre dépôt. Nous vous recommandons d’utiliser des liens relatifs pour référencer d’autres fichiers au sein de votre dépôt.

Wikis

Un README doit contenir uniquement les informations nécessaires pour que les développeurs commencent à utiliser et à contribuer à votre projet. Les documentations plus longues sont mieux adaptées aux wikis. Pour plus d’informations, consultez « À propos des wikis ».

Pour aller plus loin