lychee.toml

# ============================================================
# lychee.toml (Lychee link checker configuration)
# ============================================================

# REQ.PROJECT: Automatic link checking using GitHub Actions and Lychee.
# WHY-FILE: Shared Lychee configuration (lychee.toml) for documentation-heavy repositories.
# REQ: Link checking MUST be reliable and CI-safe.
# WHY: Configures Lychee link checker behavior for CI/CD.
# OBS: Flat structure required by lychee v0.22+; no nested sections.
# OBS: No path exclusions; all documentation files are expected to be link-clean.
# OBS: Link integrity preserves stable, reconstructible references over time.
# OBS: Link integrity maintains connections to external resources.

# WHY: Control verbosity and CI-friendly output
verbose = "info"   # WHY: Balance between detail and noise
no_progress = true # WHY: Progress bars don't work well in CI logs

# WHY: Performance tuning for link checking
max_concurrency = 6 # WHY: Parallel requests without overwhelming servers
max_retries = 3     # WHY: Retry flaky connections before failing
retry_wait_time = 8 # WHY: Wait 8 seconds between retries
timeout = 30        # WHY: 30 seconds per request before timeout

# WHY: Accept common status codes that don't indicate broken links
# OBS: 403 and 429 reduce false positives
accept = [
  200, # OK
  206, # Partial content
  301, # Moved permanently
  302, # Found (temporary redirect)
  307, # Temporary redirect
  308, # Permanent redirect
  403, # Forbidden (often false positive)
  429, # Too many requests (rate limiting)
  503, # Service unavailable (temporary)
]

# WHY: Exclude patterns that shouldn't be checked
exclude = [
  "example\\.com",   # WHY: Exclude example domains in documentation
  "localhost",       # WHY: Exclude local development URLs
  "127\\.0\\.0\\.1", # WHY: Exclude local loopback
  "\\.local",        # WHY: Exclude local network domains
]