lychee.toml

# Configuration for lychee link checker. See https://lychee.cli.rs/.
# Used by .github/workflows/site-health.yml.

cache = true
max_cache_age = "30d"
timeout = 30
max_retries = 3
retry_wait_time = 5

# root_dir is passed via the lychee-action args (it requires an absolute
# path which differs between local dev and CI). See site-health.yml.

# Use GET instead of HEAD. Many academic publishers (arxiv, nature, etc.)
# don't handle HEAD reliably and return 405 or other oddities; GET is
# what real browsers use and gets through more often.
method = "GET"

# Browser-like UA — lychee's default ("lychee/...") triggers bot
# protection on many sites.
user_agent = "Mozilla/5.0 (compatible; lychee-link-checker; +https://lychee.cli.rs/)"

# Status codes to treat as success. We're trying to catch dead links
# (404) and broken servers, not paywalls or anti-bot measures.
# - 200/204/206: success
# - 202: escholarship.org and some other deferred-fetch repos return
#   this on a request that will succeed if you retry or wait
# - 401: paywalled but exists
# - 403/405/429: bot-protection / rate-limit / method-not-allowed
# - 415: some servers (e.g. OJS journal platforms, ccneuro.org PDFs)
#   reject lychee's request based on the Accept header even though the
#   resource exists and loads in a browser.
# - 999: LinkedIn's bot-detection response
accept = [200, 202, 204, 206, 401, 403, 405, 415, 429, 999]

# Hosts to skip:
# - pearsonlab.github.io: this is the site we're building. The sitemap
#   and robots.txt contain absolute self-referential URLs by spec, but
#   HTTP-checking them only tells us about the *currently deployed*
#   site, not our build. Internal page-to-page links should be relative
#   anyway (lychee resolves them against the local _site/ directory).
# - maxcdn.bootstrapcdn.com: stable enough that transient 5xx responses
#   shouldn't fail the build.
exclude = [
    "pearsonlab\\.github\\.io",
    "maxcdn\\.bootstrapcdn\\.com",
    # localhost references in README.md (jekyll-readme-index copies
    # README into _site/ so lychee scans it).
    "localhost",
    # Specific URLs with known issues that aren't worth blocking on:
    # - thomasli.me: former undergrad's personal site, host unreachable
    #   from GitHub Actions runners (DNS or geoblock).
    # - stat.washington.edu/people/pdhoff/book.php: SSL handshake fails
    #   in lychee but the page loads in browsers (server cert chain).
    # - socialsciences.nature.com: TLS handshake failure (server config).
    "thomasli\\.me",
    "stat\\.washington\\.edu/people/pdhoff",
    "socialsciences\\.nature\\.com",
    # LinkedIn's bot-detection responds inconsistently to GitHub Actions
    # runners: same URL can return 200, 301-to-stripped-URL, 404, or 999
    # depending on time, IP, and load. Treat the whole domain as
    # unreliable for automated checking — link-rot detection on LinkedIn
    # was never going to work in practice.
    "linkedin\\.com",
]

# Path excludes for legacy blog posts are passed via the workflow's
# args (--exclude-path) rather than configured here, to keep the
# arg-passing pattern uniform with --root-dir. See site-health.yml.