À 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.

Dans cet article

À 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 et des recommandations de contribution, pour communiquer les attentes de votre projet et vous aider à gérer les contributions.

Pour plus d’informations sur l’offre 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 Enterprise Server 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.

Lorsque votre README est consulté sur GitHub, tout contenu dépassant 500 Kio sera tronqué.

Si vous ajoutez un fichier LISEZMOI à la racine d’un référentiel public portant le même nom que votre nom d’utilisateur, ce fichier LISEZMOI apparaît automatiquement sur votre page de profil. Vous pouvez modifier votre fichier LISEZMOI avec GitHub Flavored Markdown pour créer une section personnalisée sur votre profil. Pour plus d’informations, consultez « Gestion de votre README de profil ».

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 Enterprise Server 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.

Capture d’écran d’un fichier README pour un référentiel. Dans le coin supérieur gauche, un menu déroulant, marqué d'une icône de liste, est développé pour afficher une table des matières.

Vous pouvez créer un lien direct vers n’importe quelle section comportant un titre. Pour afficher l’ancre générée automatiquement dans un fichier rendu, survolez le titre de la section pour faire apparaître l’icône et cliquez sur l’icône pour afficher l’ancre dans votre navigateur.

Capture d’écran d’un fichier README pour un référentiel. À gauche d'un titre de section, une icône de lien est indiquée en orange foncé.

Pour plus d’informations sur les liens de section, consultez Liens de section.

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 Enterprise Server 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 ../.

Votre texte de lien doit se trouver sur une seule ligne. L’exemple ci-dessous ne fonctionnera pas.

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

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