Top 5 des erreurs de liens sur GitHub

Un lien mort dans un README est le signe d'un projet mal entretenu. Voici les 5 erreurs les plus fréquentes identifiées lors de notre audit de 50 projets populaires.

Le vrai problème, c’est que beaucoup d’erreurs Markdown ne se voient pas à la relecture. Le fichier s’affiche correctement sur GitHub, mais le lien casse dès qu’un utilisateur arrive depuis un fork, une branche différente ou une page de package.

1. Confusion des chemins relatifs

Utiliser ./docs/setup.md au lieu de docs/setup.md peut casser l'affichage sur certains générateurs de documentation comme docs.rs.

2. Le piège "Master" vs "Main"

Si vous avez renommé votre branche par défaut, les anciens liens vers master sont désormais des impasses.

3. La casse (Linux vs Windows)

Les serveurs GitHub sont sous Linux et donc sensibles à la casse. Guide.md n'est pas guide.md.

4. Ancres de sections obsolètes

Renommer un titre dans le README casse facilement la table des matières ou les liens profonds vers une section. Le texte reste joli, mais l’utilisateur reste bloqué en haut de page.

5. Liens communautaires et externes expirés

Les invitations Slack, Discord, Notion ou les anciens guides support vieillissent vite. Ce sont souvent les premiers liens qui abîment la confiance dans un projet open source.

Checklist README avant publication

• Installation : setup, prérequis, liens de téléchargement et docs principales.
• Navigation : changelog, contribution, exemples, wiki, support.
• Ancres : sommaire et renvois internes.
• Liens externes : API docs, pages produit, licences, communauté.