$ readme --profil
README de profil GitHub
Choisissez un modèle, remplissez le formulaire, et récupérez le Markdown à coller dans le dépôt qui porte votre pseudo. L'aperçu est à côté du formulaire, parce qu'un générateur dont on ne voit pas le résultat avant de le coller ne sert à rien.
Le README de profil a ses règles propres, et elles ne sont écrites nulle part en entier : GitHub filtre certaines balises, en affiche d'autres en clair, n'exécute aucun script et ne résout pas les adresses relatives. Chaque document produit ici est donc relu, et ce qu'il en restera est dit avant que vous colliez.
Gratuit, sans compte, et rien ne part vers un serveur : tout est assemblé dans votre navigateur.
01Le modèle
Ils ne diffèrent pas par la décoration, mais par le lecteur visé.
02Le contenu
L’aperçu se met à jour à chaque frappe. Rien n’est obligatoire sauf votre pseudo et votre nom.
L’en-tête
La première chose que l’on voit, et souvent la seule que l’on lit.
Sert au nom du dépôt à créer et aux liens du pied de page.
Deux lignes au plus. Elle est lue, le reste est survolé.
Adresse complète, https:// inclus. Laissez vide pour un titre en texte.
Facultatif. Sans elle, la même image sert aux deux thèmes.
Les badges d’en-tête
Trois suffisent. Au-delà, plus personne ne les lit.
Image servie par un tiers, qui voit donc qui consulte votre profil.
Une par ligne, « texte | couleur hexadécimale ».
La présentation
Ce que vous faites, et ce que vous cherchez.
Une ligne par élément.
Les technologies
Celles que vous pratiquez, pas celles dont vous avez lu le nom.
Technologies
Le rond marque les technologies dont shields.io ne dessine plus l'icône. Le badge sort alors sans logo, sans la moindre erreur.
Une par ligne. Rendues en badge gris, sans logo.
Les projets
Trois au plus, les mieux finis.
Une par ligne, « nom | adresse | description ».
Les statistiques
Images produites par un service tiers, à partir de votre activité publique.
Une image unique sera illisible dans l’autre thème.
Le pied de page
Où vous joindre, et ce que vous assumez de rendre public.
Liens
03Ce que GitHub en fera
Aucune note globale : un README dont le seul défaut est une image en chemin relatif s’affiche cassé, quel que soit le reste.
10
sur 12 contrôles
1
sur 12 contrôles
1
sur 12 contrôles
Le dépôt qui portera ce fichier
à revoirpseudo manquantSans votre pseudo GitHub, impossible de dire quel dépôt créer, et les liens du pied de page restent incomplets.
Le nom du dépôt doit reproduire le pseudo au caractère près, la casse comprise.
Images en adresse absolue
correct0 imageAucune image, donc rien à casser de ce côté.
C’est la seule forme qui fonctionne partout : sur le profil, dans un agrégateur, ou dans un aperçu de partage.
Aucun script, et rien qui s’affiche en clair
correctrien à échapperAucune balise script, style ou iframe. GitHub n’exécute rien dans un README, et affiche en clair ce genre de balise plutôt que de la retirer.
Une animation, un compteur ou un graphique dans un README est donc toujours une image, jamais du code qui tourne.
Balises retirées sans avertissement
correctaucuneLe document n’emploie que des balises que GitHub conserve : titres, paragraphes, div, img, a, picture, table, details, kbd.
La liste des balises acceptées est courte, et center comme font n’y figurent pas, malgré leur présence dans beaucoup de modèles qui circulent.
Attributs conservés par GitHub
correctalign, width, heightLe document s’en tient aux attributs que GitHub laisse passer.
Les styles en ligne sont retirés sans exception : un README ne se met pas en couleur, sauf par le biais d’images.
Pas de Markdown dans un bloc HTML
correctaucun mélangeLes blocs HTML du document ne contiennent que du HTML, et le Markdown reste dehors.
C’est le piège le plus courant des modèles centrés : un gras ou un lien écrit en Markdown dans un paragraphe centré s’affiche avec sa ponctuation de balisage.
Un texte alternatif par image
correctaucune imagePas d’image, donc pas d’alternative à écrire.
C’est ce qui s’affiche quand le service tiers ne répond pas, et ce qui est lu à voix haute le reste du temps.
Lisible en thème clair comme en thème sombre
correctrien à adapterAucune image dont le rendu dépende du thème.
Près de la moitié des visiteurs de GitHub sont en thème sombre, et ce sont eux qui voient les en-têtes mal préparés.
Logos réellement dessinés par shields.io
correcttous vérifiésLes slugs de logo employés ici ont été essayés un par un contre shields.io, et renvoient bien une icône.
Le badge LinkedIn est le cas typique : son icône a disparu du jeu, et le badge sort donc sans logo. Celui-ci est produit sans logo, volontairement.
Services tiers appelés par votre profil
à savoiraucunVotre profil ne dépend d’aucun service extérieur pour s’afficher.
Un README qui s’appuie sur quatre services s’affiche de travers le jour où l’un des quatre est lent. C’est l’argument du modèle sobre.
Un seul titre de premier niveau
correct1 titresUn seul h1, et aucun niveau sauté : le plan du document se tient.
GitHub construit un sommaire à partir de ces titres, et un lecteur d’écran les annonce comme tel.
Longueur du fichier
correct34 signes, 2 lignesLe fichier tient dans une longueur qui se parcourt d’un regard.
Un profil n’est pas une documentation : c’est la page que l’on ouvre pour savoir en dix secondes à qui l’on a affaire.
04Questions fréquentes
- Où faut-il placer ce fichier pour qu’il devienne mon profil ?
- Dans un dépôt public dont le nom reproduit exactement votre pseudo GitHub, casse comprise, avec le fichier nommé README.md à la racine. GitHub affiche alors son contenu en haut de votre page de profil. Dans tout autre dépôt, c’est le README d’un projet ordinaire.
- Pourquoi mon texte centré affiche-t-il des astérisques ?
- Parce que le Markdown n’est pas interprété à l’intérieur d’une balise HTML sur la même ligne. Un gras écrit en Markdown dans un paragraphe centré ressort avec ses astérisques visibles. Il faut soit écrire la mise en forme en HTML, soit laisser des lignes vides à l’intérieur de la balise, ce qui relance l’interprétation du Markdown.
- Est-ce que je peux animer mon README avec un script ?
- Non, et l’échec est bruyant. GitHub n’exécute aucun JavaScript dans un README, mais il ne retire pas pour autant la balise script : il l’échappe, donc votre code s’affiche en clair dans la page. Tout ce qui bouge dans un README est une image, produite ailleurs puis servie à l’affichage.
- Pourquoi mon image ne s’affiche-t-elle pas ?
- Dans la plupart des cas, parce que son adresse est relative. GitHub relaie les images absolues par son propre proxy, mais laisse les adresses relatives telles quelles : une adresse commençant par une barre oblique est résolue contre github.com, pas contre votre dépôt. L’adresse doit être complète, protocole inclus.
- Pourquoi mon badge LinkedIn sort-il sans logo ?
- Parce que cette icône ne fait plus partie du jeu de simple-icons que shields.io utilise. Le badge est renvoyé avec un code 200 et sans image, donc rien ne signale le problème. Le générateur produit ce badge sans logo, volontairement, plutôt que de demander une icône qui n’arrivera pas.
- Mes réponses sont-elles enregistrées quelque part ?
- Non. Tout se fait dans votre navigateur, aucune requête ne part vers un serveur, et rien n’est conservé en quittant la page. Le fichier téléchargé est fabriqué sur votre machine à partir de ce qui est affiché.
- Les statistiques et les compteurs posent-ils un problème ?
- Ils marchent, mais ils ont un coût. Ce sont des images produites par des services tiers, et votre profil ne s’affiche correctement que si ces services répondent. Le contrôle en bas de page compte combien de domaines votre README sollicite, précisément pour que vous le sachiez avant de coller.
Ce que cet outil ne fait pas, et autant le dire. Il ne regarde pas votre compte GitHub, donc il ne sait rien de vos dépôts ni de vos langages : les cartes de statistiques sont des images produites par un service tiers, à partir de votre activité publique, et ce service peut tomber. Il ne vérifie pas qu'une adresse d'image répond, seulement qu'elle est complète. Il ne crée pas le dépôt à votre place.
Les règles qu'il applique ont été mesurées en envoyant un document d'essai au moteur de rendu de GitHub, pas lues dans une documentation. Les slugs de logo proposés ont été essayés un par un contre shields.io, ce qui est la seule façon de repérer ceux qui répondent sans dessiner d'icône.