$ man readme-profil-github
Le README de profil GitHub, et ce que GitHub en garde
Un README de profil n’est pas du Markdown ordinaire. GitHub en retire une partie sans rien dire, en affiche une autre en clair, et n’exécute rien du tout. Voici ce qu’il en reste, mesuré plutôt que lu dans une documentation.
- Vous cherchez un premier poste, et votre profil GitHub est la première chose qu’un recruteur ouvre.
- Vous avez recopié un modèle trouvé ailleurs, et la moitié ne s’affiche pas comme prévu.
- Vous apprenez le développement web, et le Markdown de GitHub reste une suite de recettes.
À écrire la page d’accueil de votre profil GitHub en sachant à l’avance ce que la plateforme en gardera, plutôt qu’en découvrant les surprises sur le dépôt.
- Avant de postuler, parce que ce profil est lu avant votre code.
- Quand un modèle recopié s’affiche de travers et que l’on ne comprend pas pourquoi.
- Quand on veut un profil qui se lise aussi en thème sombre, et le jour où un service tiers ne répond plus.
01Le dépôt qui porte votre pseudo
Le mécanisme est particulier, et il explique la plupart des questions. GitHub affiche en haut de votre page de profil le README d’un dépôt bien précis : celui dont le nom reproduit exactement votre pseudo, casse comprise. Un dépôt public, et le fichier nommé README.md à la racine.
Dans tout autre dépôt, le même fichier reste le README d’un projet ordinaire. Il n’y a pas de réglage à activer, pas de case à cocher : c’est le nom du dépôt qui fait tout.
# pour le pseudo « exemple »
dépôt : exemple/exemple (public)
fichier : README.md (à la racine)
# le contenu apparaît alors sur
https://github.com/exemple02Trois sorts possibles pour une balise
GitHub accepte du HTML dans le Markdown, mais pas tout, et c’est là que les modèles recopiés se cassent. Une balise peut subir trois choses, et la deuxième est celle que personne n’attend.
- Elle est conservée : les titres h1 à h6, p, div, img, a, picture, source, table, details, summary, br, hr, kbd, sub, sup, blockquote.
- Elle est échappée, donc affichée en clair au visiteur : script, style, iframe. Votre code se retrouve lisible dans la page.
- Elle est retirée en silence, son contenu restant : center, font, marquee, video, audio, svg, form, input, button. Un texte dans une balise center sort donc non centré, sans le moindre message.
Cette liste n’a pas été recopiée d’une page de documentation. Elle vient d’un document d’essai envoyé au moteur de rendu de GitHub, dont le résultat a été relu balise par balise. C’est aussi comme cela que l’on découvre que la balise center, présente dans une bonne part des modèles qui circulent, n’a aucun effet.
03Centrer, et le piège qui vient avec
Le Markdown ne sait pas centrer. Le seul moyen est l’attribut align, et il n’est conservé que sur h1 à h6, p, div et td. Tout le reste de la mise en forme en ligne est filtré : un attribut style est retiré partout, sans exception.
Et c’est là que se trouve le piège le plus coûteux du README de profil. Le Markdown n’est pas interprété à l’intérieur d’une balise HTML sur la même ligne. Un gras ou un lien écrits en Markdown dans un paragraphe centré ressortent avec leurs astérisques et leurs crochets visibles.
<!-- affiche littéralement **gras** -->
<p align="center">**gras**</p>
<!-- affiche du gras, grâce aux lignes vides -->
<div align="center">
**gras**
</div>
<!-- ou alors on écrit le HTML jusqu’au bout -->
<p align="center"><strong>gras</strong></p>Les lignes vides à l’intérieur de la balise relancent l’interprétation du Markdown. La même règle vaut dans une cellule de tableau écrite en HTML. Le générateur évite la question autrement : il ne met jamais de Markdown dans un bloc centré, et il signale le cas si vous en introduisez un.
04Les images, et pourquoi la vôtre ne s’affiche pas
GitHub ne sert pas vos images directement : il les relaie par son propre proxy, camo, ce qui masque l’adresse du visiteur au service qui les héberge. Cela ne vaut que pour les adresses absolues.
Une adresse relative est laissée telle quelle. Elle est alors résolue contre le dépôt, ce qui marche sur le profil mais ne vaut plus rien ailleurs. Et une adresse qui commence par une simple barre oblique est résolue contre github.com, donc elle est cassée. C’est de loin la première cause d’image absente dans un README.
- Une adresse complète, protocole inclus, est la seule forme qui fonctionne partout.
- La taille se règle par les attributs width et height, que GitHub conserve. Pas par un style, qui est retiré.
- Un texte alternatif sur chaque image, parce que c’est tout ce qui restera le jour où le service tiers ne répondra pas.
05Le thème clair et le thème sombre
GitHub a deux thèmes, et une bonne part des visiteurs est en sombre. Une bannière à fond blanc tranche alors sur la page, et une carte de statistiques au thème sombre devient illisible pour les autres. Aucune feuille de style ne peut arranger cela, puisque les styles sont retirés.
La seule construction que GitHub respecte est picture, avec deux balises source distinguées par prefers-color-scheme. Elle fonctionne, c’est vérifié : GitHub l’enveloppe dans un élément à lui et sert la bonne image selon le thème du lecteur.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://exemple.fr/sombre.png" />
<source media="(prefers-color-scheme: light)" srcset="https://exemple.fr/clair.png" />
<img src="https://exemple.fr/clair.png" alt="Bannière" />
</picture>La balise img finale n’est pas facultative : c’est elle qui sert de secours, et c’est elle qui porte le texte alternatif.
06Les badges, et les logos qui manquent sans le dire
Les badges d’un README viennent presque tous de shields.io, qui fabrique une image à partir d’une adresse. Le paramètre logo y prend le nom d’une icône, et c’est là qu’une panne discrète attend.
Un nom d’icône inconnu ne provoque aucune erreur. shields.io renvoie un code 200 et un badge parfaitement formé, simplement sans image. Rien ne le signale, et l’on peut garder des mois un badge amputé de ce qui le rendait reconnaissable.
- LinkedIn est le cas le plus courant : son icône a quitté le jeu de simple-icons, et le badge sort donc sans logo.
- Slack, CodePen, Playwright et le C dièse sont dans le même cas.
- Il n’existe aucune icône d’enveloppe générique pour un courriel. Il faut nommer un service précis, ou se passer de logo.
Les slugs proposés par le générateur ont été essayés un par un contre shields.io, et seuls ceux qui renvoient réellement une icône sont offerts avec un logo. Les autres sont marqués d’un rond dans le formulaire, et produits volontairement sans logo.
07Rien ne s’exécute, donc tout est une image
Aucun JavaScript ne tourne dans un README, et aucune feuille de style ne s’y applique. Ce qui s’agite dans les profils que vous voyez passer, compteurs de visites, cartes de statistiques, serpents qui mangent les contributions, ce sont des images fabriquées ailleurs puis servies à l’affichage.
Cela a une conséquence que peu de gens pèsent avant de coller un modèle : chaque image de ce genre est un service extérieur dont dépend l’affichage de votre profil. Avec quatre services, il suffit qu’un seul soit lent pour que votre page s’affiche de travers, et le texte alternatif est alors tout ce qui reste.
Le générateur compte ces domaines et les nomme. Ce n’est pas un interdit, c’est une information que l’on devrait avoir avant de choisir.
08Choisir entre les trois modèles
Les trois modèles ne se distinguent pas par la décoration mais par le lecteur visé, et par ce qu’ils acceptent de coûter.
- Vitrine : bannière centrée, badges, technologies, projets et statistiques. Le format le plus répandu, et celui qui dépend le plus de services tiers.
- Sobre : aucune balise HTML, aucune image. Rien à charger, rien à filtrer, lisible dans un terminal comme par un lecteur d’écran.
- Candidature : ce que vous cherchez, votre parcours en tableau, vos formations, vos projets. Pour quelqu’un qui lit un profil afin de décider d’un entretien, et qui n’a pas trois minutes.
Chaque modèle est décrit en données, avec ses sections et ses champs. En ajouter un ne demande pas de toucher à la page, ce qui est la raison pour laquelle il y en a trois plutôt qu’un.
09Ce que le générateur ne fait pas
Il ne regarde pas votre compte GitHub. Il ne connaît ni vos dépôts, ni vos langages, ni votre nombre de contributions : les cartes de statistiques sont des images produites par un service tiers à partir de votre activité publique.
- 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, et ne pousse rien sur GitHub.
- Il n’écrit pas votre accroche. Un générateur peut mettre en forme, il ne peut pas savoir ce que vous cherchez.
- Il ne conserve rien : tout est assemblé dans le navigateur, et oublié en quittant la page.
En revanche il relit ce qu’il produit, et dit ce que GitHub en fera. Douze contrôles, chacun rendu seul avec sa mesure, sans note globale : un README dont le seul défaut est une image en chemin relatif s’affiche cassé, quel que soit le reste.
Le mieux reste encore d’essayer. Rien n’est enregistré ailleurs que dans votre navigateur.