À 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.
Liens de section dans les fichiers README et les pages d’objets blob
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.
Pour plus d’informations sur les liens de section, consultez « Liens de section ».
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 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
- « Ajout d’un fichier à un référentiel »
- « 5 conseils pour rendre votre page de profil GitHub accessible » dans le blog de GitHub