Aller au contenu
Accueil Stéphane ROBERT
medium

Zéro lien cassé : automatiser la détection avec Lychee

Photo de Stéphane Robert
Stéphane Robert DevOps Engineer
6 min de lecture

Lychee, outil de vérification de liens brisés

Un problème classique quand on documente beaucoup

Quand on documente beaucoup, les liens cassés finissent toujours par gagner.

Un dépôt GitHub déplacé, une doc externe supprimée, une URL qui change… Et sans s’en rendre compte, on dégrade progressivement l’expérience de lecture.

Sur ce site, avec plus de 800 pages de documentation DevOps/DevSecOps, je publie en moyenne 2 à 3 guides par semaine. Chaque guide contient entre 10 et 30 liens (internes et externes). Sans outil automatisé, vérifier manuellement plusieurs milliers de liens serait impossible. C’est exactement pour répondre à ce besoin que j’ai ajouté Lychee à ma liste d’outils.

Lychee, c’est quoi exactement ?

Lychee est un outil en ligne de commande écrit en Rust dont le rôle est simple :

Scanner des fichiers ou des sites et détecter automatiquement les liens cassés.

Il sait analyser :

  • des fichiers Markdown
  • des pages HTML
  • des répertoires entiers
  • ou même un site web généré statiquement

Le tout de manière rapide, asynchrone et avec un niveau de contrôle suffisant pour l’intégrer dans des workflows automatisés.

Ce qui le distingue des autres outils

J’ai testé plusieurs alternatives (markdown-link-check, linkchecker, htmltest) avant d’adopter Lychee. Voici ce qui fait la différence :

  • Vitesse : Écrit en Rust, Lychee vérifie 10 000 liens en moins de 30 secondes grâce aux requêtes asynchrones. Sur mon site, un scan complet prend environ 8 secondes au lieu de plusieurs minutes avec d’autres outils.
  • Cache intelligent : Une fois un lien vérifié, il est mis en cache. Lors du prochain scan, seuls les nouveaux liens sont testés. Gain de temps considérable en CI/CD.
  • Binaire statique : Pas de dépendances Python ou Node.js à installer. Un seul exécutable suffit.
  • Support des ancres : Vérifie que page.html#section pointe bien vers une ancre existante, pas juste que la page existe.

Pourquoi cet outil a aussi du sens dans un workflow DevOps

Dans une démarche DevOps, la documentation fait partie intégrante du produit. Un lien mort, ce n’est pas anodin :

  • perte de crédibilité
  • frustration pour le lecteur
  • augmentation du bounce rate
  • dette documentaire silencieuse

Lychee permet justement de :

  • détecter les erreurs tôt
  • automatiser les vérifications
  • éviter les régressions dans le temps

C’est typiquement le genre d’outil qu’on peut lancer :

  • en local avant un commit
  • dans une CI
  • avant une mise en production d’un site statique

Mon intégration concrète avec Lychee

Voici comment j’utilise Lychee au quotidien sur ce site :

1. Vérification locale avant commit

J’ai créé un alias dans mon .zshrc :

Fenêtre de terminal
alias check-links="lychee --cache --exclude 'localhost|127\.0\.0\.1' ./dist"

Avant chaque commit important, je lance check-links pour valider les liens.

2. GitHub Action automatisée

Dans .github/workflows/links.yml, j’ai configuré une vérification automatisée sur chaque pull request :

- name: Vérifier les liens
  uses: lycheeverse/lychee-action@v2
  with:
    args: --cache --verbose './**/*.md' './**/*.mdx'
    fail: true

Si un lien est cassé, la PR est bloquée. Zéro lien mort en production.

3. Configuration personnalisée

Mon fichier lychee.toml à la racine du projet :

# Exclusions spécifiques
exclude = [
  'localhost',
  'example\\.com',
  # Liens d'exemples volontairement cassés dans les guides
  'httpstat\\.us'
]


# Cache pour accélérer
cache = true
timeout = 30


# Vérifier les ancres
include_fragments = true

Résultats concrets après 1 mois d’utilisation

  • ✅ 457 liens cassés détectés et dont une centaine déjà corrigés (anciennes URLs GitHub, projets archivés, docs supprimées)
  • ✅ 0 lien mort publié depuis l’intégration en CI/CD
  • ✅ environ 30 secondes de scan moyen sur 800+ pages
  • ✅ 100% de confiance dans la qualité documentaire

En clair : Lychee m’a permis de reprendre le contrôle sur une dette documentaire invisible.

Pourquoi je l’ai ajouté à ma liste d’outils

Je sélectionne les outils que je référence ici avec un critère simple : est-ce qu’ils m’aident concrètement à améliorer la qualité de ce que je produis ?

Lychee coche toutes les cases :

  • simple à prendre en main
  • focalisé sur un problème précis
  • efficace à grande échelle
  • compatible avec des chaînes CI/CD

Il s’intègre naturellement dans une démarche de qualité continue, sans complexifier inutilement l’existant.

Aller plus loin avec Lychee

Ce billet est volontairement une présentation éditoriale : le pourquoi et le quand utiliser Lychee.

Pour le comment (installation, options, exclusions, exemples concrets), tout est détaillé ici : Guide complet Lychee

Ressources pour aller plus loin

Comme pour les autres outils référencés sur le site, l’objectif reste le même : documenter des solutions utiles, éprouvées, et directement exploitables sur le terrain.