Lychee : détecter les liens cassés dans votre documentation

Ce guide va vous permettre de détecter automatiquement tous les liens cassés dans votre documentation en moins de 5 minutes. Vous apprendrez à installer Lychee, vérifier vos fichiers Markdown/HTML, et l’intégrer dans votre pipeline CI/CD pour ne plus jamais publier de liens morts.

Ce que vous apprendrez :

• à l’installer rapidement (Docker, cargo, gestionnaire de paquets)
• à vérifier des fichiers, dossiers et sites web
• à le configurer pour vos besoins spécifiques (cache, exclusions, formats de sortie)

Pourquoi Lychee ?

Imaginez que vous maintenez une documentation technique avec 200 pages. Chaque page contient 10 à 20 liens vers d’autres pages, des sites externes, des dépôts GitHub. Au fil des mois :

• Des articles de blog changent d’URL
• Des projets GitHub sont archivés ou renommés
• Vos propres pages internes sont déplacées
• Des APIs changent de domaine

Résultat : vos lecteurs tombent sur des erreurs 404. Ils perdent confiance, quittent votre site, et votre réputation en prend un coup.

Lychee résout ce problème en parcourant tous vos fichiers et en testant chaque lien (HTTP, HTTPS, mailto, ancres). Il est asynchrone (vérifie plusieurs liens en parallèle), rapide (écrit en Rust), et facile à intégrer dans un workflow CI/CD.

Qu’est-ce que Lychee ?

Lychee est un vérificateur de liens (link checker) ultra-rapide écrit en Rust. Il scanne vos fichiers Markdown, HTML, ou même votre site web complet pour détecter les liens cassés ou invalides.

🔗 Liens officiels :

• Site web
• Dépôt GitHub
• GitHub Action

Analogie : Lychee est comme un détecteur de fumée pour vos liens — il vous alerte avant que les lecteurs ne subissent l’incendie d’une page 404.

Fonctionnalités clés

Voici les capacités qui distinguent Lychee des autres outils de vérification de liens. Ces fonctionnalités répondent aux besoins réels des équipes qui maintiennent de la documentation à grande échelle :

Fonctionnalité	Description	Exemple d’usage
Multi-formats	Markdown, HTML, texte brut	Documentation, blog, site statique
Asynchrone	Vérifie plusieurs liens en parallèle	Scan de 1000 liens en quelques secondes
Cache	Évite de re-vérifier les mêmes URLs	Accélère les scans répétés
JSON output	Sortie structurée pour l’automatisation	Parsing dans un script CI/CD
Exclusions	Ignore certains domaines ou patterns	Exclure localhost, liens privés
Ancres	Vérifie les #fragment dans les URLs	S’assure que page.html#section existe
Email check	Valide les adresses mailto:	Détecte les emails invalides

Pourquoi l’utiliser ?

Lychee a été créé par Matthias Endler pour maintenir le dépôt analysis-tools.dev, qui liste des centaines d’outils. Les liens cassaient régulièrement, et les solutions existantes présentaient des lacunes majeures qui rendaient leur utilisation difficile en production :

• Trop lentes (vérifications synchrones)
• Obsolètes (projets non maintenus)
• Limitées (pas de support Markdown, pas de cache)

Résultat : Lychee vérifie 10 000 liens en moins de 30 secondes sur un projet moyen.

Prérequis

Avant de commencer, assurez-vous que votre environnement répond aux critères suivants. La bonne nouvelle : Lychee étant un binaire statique, les dépendances sont minimales.

Connaissances :

• Utilisation basique du terminal (Linux/macOS/Windows)
• Notions de Markdown ou HTML (optionnel mais utile)

Système :

• Linux, macOS, ou Windows (WSL2 recommandé)
• Docker ou Rust/Cargo ou gestionnaire de paquets

Outils (un seul suffit) :

• Docker (méthode la plus simple)
• Cargo (si vous développez en Rust)
• Gestionnaire de paquets : pacman, Homebrew, Scoop, Nix, etc.

Installation

Lychee est distribué comme un binaire statique : pas de dépendances système compliquées. Choisissez la méthode qui vous convient.

Astuce

Méthode rapide : Utilisez Docker pour éviter toute installation système.

Docker

La façon la plus simple, sans rien installer sur votre système :

docker run --init -it --rm \
  -v $(pwd):/input \
  lycheeverse/lychee /input

Explication :

• --init : Gère correctement les signaux (Ctrl+C)
• -v $(pwd):/input : Monte le dossier courant dans le conteneur
• /input : Chemin à scanner dans le conteneur

Vérification :

docker run --rm lycheeverse/lychee --version
# Affiche : lychee 0.x.x

Cargo (Rust)

Si vous avez Rust installé, utilisez cargo :

cargo install lychee

Avec fonctionnalités optionnelles :

cargo install lychee \
  --features native-tls,email-check

Les features optionnelles permettent d’activer des fonctionnalités supplémentaires selon vos besoins. Voici celles disponibles :

Options disponibles :

• native-tls : Utilise OpenSSL (par défaut)
• rustls-tls : Alternative pure Rust (pas d’OpenSSL)
• email-check : Valide les adresses email
• vendored-openssl : Compile OpenSSL depuis les sources

Vérification :

lychee --version

Arch Linux (pacman)

sudo pacman -S lychee

macOS (Homebrew)

brew install lychee

Windows (Scoop)

scoop install lychee

NixOS

nix-env -iA nixpkgs.lychee

Note

Astuce : Si vous utilisez GitHub Actions, vous n’avez rien à installer — utilisez directement l’action officielle (voir section CI/CD).

Utilisation de base

Une fois installé, Lychee s’utilise en ligne de commande. Voici les scénarios les plus courants.

1. Vérifier un fichier Markdown

   lychee README.md

   Résultat attendu :

   ✅ 23 links checked.
   ✅ 0 errors.

   Si liens cassés :

   ✗ 2 errors:
     [404] https://example.com/old-page
     [ERR] https://broken-site.io (DNS resolution failed)

2. Vérifier tous les fichiers d’un dossier

   Scanne récursivement tous les Markdown/HTML :

   lychee docs/

   Ou avec un pattern spécifique :

   lychee "docs/**/*.md"

3. Vérifier un site web complet

   Scanne toutes les pages d’un site déployé :

   lychee https://blog.stephane-robert.info

   Limite la profondeur (évite de scanner tout Internet) :

   lychee --max-depth 3 https://blog.stephane-robert.info

4. Vérifier plusieurs sources en une fois

   lychee README.md docs/ https://example.com

5. Lire les URLs depuis stdin

   Utile pour piper depuis un autre outil :

   echo "https://github.com" | lychee -

   Ou depuis un fichier :

   cat urls.txt | lychee -

6. Utiliser un glob pattern avancé

   lychee "**/*.{md,html,txt}"

   Scanne tous les .md, .html, et .txt récursivement.

Exemple de sortie

Voici ce que vous verrez lors d’un scan typique :

$ lychee docs/

📝 Extracting links from 45 files...
🔍 23 unique links found
✅ 21 links OK
✗ 2 errors:

  [404] https://old-blog.example.com/post
    → Trouvé dans docs/guide.md:42

  [ERR] https://timeout.io (Timeout after 20s)
    → Trouvé dans docs/faq.md:15

⏱ Total time: 3.2s

Configuration avancée

Exclure certains liens

Certains liens sont volontairement cassés (exemples dans la doc) ou privés (localhost, intranets). Vous pouvez les exclure.

Option 1 : Ligne de commande

lychee --exclude 'localhost|127\.0\.0\.1' docs/

Option 2 : Fichier de configuration

Créez un fichier lychee.toml :

# Exclure localhost et les IPs privées
exclude = [
  'localhost',
  '127\.0\.0\.1',
  '192\.168\.\d+\.\d+',
  '10\.\d+\.\d+\.\d+'
]

# Ignorer certains domaines
exclude_domains = [
  'example.com',
  'placeholder.org'
]

# Ignorer certains chemins de fichiers
exclude_path = [
  'node_modules/',
  '.git/',
  'vendor/'
]

Utilisation :

lychee --config lychee.toml docs/

Activer le cache

Par défaut, Lychee re-vérifie tous les liens à chaque exécution. Avec le cache, il se souvient des liens déjà validés.

lychee --cache docs/

Le cache est stocké dans ~/.lychee_cache (ou %LOCALAPPDATA%/lychee/cache sur Windows).

Vider le cache :

rm -rf ~/.lychee_cache

Astuce

En CI/CD, configurez une persistance du cache entre les runs pour accélérer les vérifications (voir section GitHub Actions).

Formats de sortie

Lychee supporte plusieurs formats pour intégrer les résultats dans d’autres outils. Choisissez le format adapté à votre cas d’usage : lecture humaine en console, automatisation dans un script, ou rapport à inclure dans votre documentation.

Format	Usage	Commande
Texte	Lecture humaine (défaut)	lychee docs/
JSON	Parsing automatisé	lychee --format json docs/
Markdown	Rapport à inclure dans un README	lychee --format markdown docs/
CSV	Import dans Excel/Sheets	lychee --format csv docs/

Exemple JSON :

{
  "total": 23,
  "successful": 21,
  "failures": 2,
  "errors": [
    {
      "url": "https://example.com/404",
      "status": "404 Not Found",
      "source": "docs/guide.md:42"
    }
  ]
}

Redirection vers un fichier :

lychee --format json docs/ > report.json

Vérifier les ancres (fragments)

Par défaut, Lychee vérifie uniquement que https://example.com/page répond. Pour vérifier que https://example.com/page#section contient bien l’ancre #section :

lychee --include-fragments docs/

Cas d’usage : Vous avez des liens vers des sections précises d’une page (#installation, #configuration). Si la section est renommée, le lien devient invalide.

Gérer les rate limits

Certains sites limitent le nombre de requêtes par seconde. Lychee peut être trop rapide et se faire bloquer.

Ralentir les requêtes :

lychee --max-concurrency 5 docs/

Ajouter un délai entre les requêtes :

lychee --throttle 1000 docs/  # 1 seconde de pause

Headers personnalisés (pour contourner des blocages) :

lychee --header "User-Agent=Mozilla/5.0" docs/

Intégration CI/CD

GitHub Actions

L’usage principal de Lychee est de vérifier les liens à chaque commit pour éviter de publier des liens cassés.

Lychee fournit une GitHub Action officielle qui simplifie l’intégration dans vos workflows.

Exemple de workflow (.github/workflows/links.yml) :

name: Vérification des liens

on:
  push:
    branches: [main]
  pull_request:

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Vérifier les liens avec Lychee
        uses: lycheeverse/lychee-action@v2
        with:
          args: --verbose --no-progress './**/*.md' './**/*.html'
          fail: true  # Échoue si liens cassés
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Avec cache pour accélérer les vérifications :

- name: Vérifier les liens
  uses: lycheeverse/lychee-action@v2
  with:
    args: --cache --verbose './**/*.md'
    fail: true
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Ajouter un commentaire sur la PR en cas d’erreur :

- name: Commenter la PR
  if: failure()
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '⚠️ Des liens cassés ont été détectés. Voir les logs CI.'
      })

GitLab CI

Pour GitLab, la configuration est encore plus simple puisque Lychee fournit une image Docker officielle. Voici un job minimal qui s’exécute à chaque push :

link-check:
  image: lycheeverse/lychee
  script:
    - lychee --cache --verbose './**/*.md'
  artifacts:
    when: on_failure
    paths:
      - lychee-report.json

Pipeline local (pre-commit)

Vérifiez les liens avant de commit avec un hook Git. Cette approche évite de pousser des liens cassés vers le dépôt distant, économisant du temps CI et des notifications inutiles.

Créez un fichier dans votre dépôt avec ce contenu :

.git/hooks/pre-commit :

#!/bin/bash
lychee --offline README.md docs/
if [ $? -ne 0 ]; then
  echo "❌ Liens cassés détectés. Corrigez avant de commit."
  exit 1
fi

Rendre le hook exécutable :

chmod +x .git/hooks/pre-commit

Dépannage

Problème : Timeouts fréquents

Symptôme :

[ERR] https://slow-site.com (Timeout after 20s)

Cause : Le site est lent ou votre connexion est instable.

Solution : Augmenter le timeout :

lychee --timeout 60 docs/

Problème : Rate limit atteint

Symptôme :

[429] https://api.github.com/repos/... (Too Many Requests)

Cause : Trop de requêtes en parallèle vers la même API.

Solution 1 : Réduire la concurrence :

lychee --max-concurrency 2 docs/

Solution 2 : Ajouter un token GitHub (pour les URLs GitHub) :

export GITHUB_TOKEN=ghp_your_token
lychee docs/

Problème : Faux positifs (liens valides marqués cassés)

Symptôme : Un lien fonctionne dans le navigateur mais échoue dans Lychee.

Cause : Le site bloque les requêtes sans User-Agent ou cookies.

Solution : Ajouter des headers :

lychee --header "User-Agent=Mozilla/5.0" \
       --header "Accept=text/html" \
       docs/

Ou exclure le domaine si c’est un cas isolé :

lychee --exclude 'problematic-site\.com' docs/

Problème : Ancres non détectées

Symptôme : #section marquée comme invalide alors qu’elle existe.

Cause : Par défaut, Lychee ne vérifie pas les fragments.

Solution :

lychee --include-fragments docs/

Problème : Liens locaux cassés

Symptôme :

[ERR] ./assets/image.png (File not found)

Cause : Chemin relatif incorrect ou fichier réellement absent.

Solution 1 : Vérifier que le fichier existe :

ls -la ./assets/image.png

Solution 2 : Utiliser --base-url si votre site n’est pas servi depuis la racine :

lychee --base-url https://example.com/blog/ docs/

Exemples de configuration réels

Les sections précédentes vous ont montré les options individuelles. Voici maintenant des configurations complètes, prêtes à l’emploi, pour trois cas d’usage fréquents. Copiez celle qui correspond à votre projet et ajustez selon vos besoins.

Documentation technique (Markdown)

Cas d’usage : Dépôt GitHub avec des guides en Markdown.

Cette configuration est optimisée pour un dépôt de documentation classique. Elle active le cache pour accélérer les scans répétés, exclut les répertoires de build, et vérifie les ancres pour détecter les liens internes cassés.

lychee.toml :

# Exclure les exemples et localhost
exclude = [
  'localhost',
  'example\.(com|org|net)',
  '127\.0\.0\.1'
]

# Vérifier les ancres
include_fragments = true

# Cache activé
cache = true

# Timeout augmenté (certains sites de docs sont lents)
timeout = 30

# Format JSON pour parsing
format = "json"

# Ignorer node_modules et .git
exclude_path = [
  'node_modules/',
  '.git/',
  'vendor/',
  'dist/'
]

Commande :

lychee --config lychee.toml .

Site statique (HTML)

Cas d’usage : Site généré par Hugo/Jekyll/Astro.

Pour un site web généré, cette configuration se concentre sur le dossier de build final (public/ ou dist/). Elle exclut les domaines tiers (analytics, CDN) qui peuvent causer des faux positifs.

# Vérifier uniquement le build final
base_url = "https://blog.stephane-robert.info"

# Exclure les domaines analytics et CDNs
exclude_domains = [
  'google-analytics.com',
  'googletagmanager.com',
  'cdn.jsdelivr.net'
]

# Vérifier les fragments (ancres de navigation)
include_fragments = true

# Format Markdown pour rapport
format = "markdown"

# Ignorer les répertoires de build
exclude_path = [
  'node_modules/',
  '.cache/',
  'dist/',
  'public/'
]

Commande :

lychee --config lychee.toml public/

Blog personnel

Cas d’usage : Blog avec des liens externes vers des articles de référence.

Cette configuration est adaptée aux blogs qui citent beaucoup de sources externes. Elle augmente le timeout pour gérer les sites lents, ajoute des retries pour la résilience, et ralentit les requêtes pour éviter les rate limits.

# Timeout augmenté (certains blogs sont lents)
timeout = 45

# Exclure les liens sponsorisés
exclude = [
  'bit\.ly',
  'goo\.gl',
  't\.co'
]

# Cache activé
cache = true

# Réessayer 3 fois en cas d'échec
max_retries = 3

# Délai entre requêtes pour éviter les rate limits
throttle = 500  # 500ms

À retenir

• Lychee détecte automatiquement les liens cassés dans Markdown, HTML, et sites web.
• Installation simple : Docker, cargo, ou gestionnaire de paquets.
• Usage basique : lychee README.md pour un fichier, lychee docs/ pour un dossier.
• Cache et exclusions : Accélérez les scans et ignorez les faux positifs.
• Intégration CI/CD : GitHub Actions, GitLab CI, ou hooks Git pour vérifications automatiques.
• Configuration TOML : Centralisez vos règles dans lychee.toml pour éviter les longues commandes.
• Formats de sortie : JSON, Markdown, CSV pour automatisation ou rapports.
• Vérification des ancres : Utilisez --include-fragments pour valider les #section.

Ressources supplémentaires

• Site officiel Lychee : Documentation complète et guides
• Dépôt GitHub lycheeverse/lychee : Code source, issues et releases
• Changelog : Nouvelles fonctionnalités et corrections
• GitHub Action lychee-action : Intégration CI/CD officielle

×

📖 Voir la documentation →