lychee.toml

# Lychee link checker configuration
# https://github.com/lycheeverse/lychee
#
# Run locally: atmos lint link-check
# Or directly: lychee --config lychee.toml '**/*.md'

# Log level: "error", "warn", "info", "debug", "trace"
verbose = "info"

# Don't show progress bar (cleaner CI output)
no_progress = true

# Timeout for each request (seconds)
timeout = 60

# Retry failed requests
max_retries = 3

# Accept these HTTP status codes as valid.
# 500 is included alongside 403/429 because GitHub's gateway intermittently
# rejects a handful of the ~800 unique links checked here with 500 Internal
# Server Error under CI's request volume (verified to return 200 outside CI),
# spanning arbitrary github.com issue/PR/repo URLs across different repos —
# not any one specific broken link. See the v1.203.0 release-tag exclude below
# for the single-URL precedent of this same GitHub-gateway flakiness.
accept = ["200", "204", "301", "302", "403", "429", "500"]

# Paths to exclude from checking (input files to scan)
exclude_path = [
  "website",
  "node_modules",
  ".git",
  ".conductor",
]

# URL patterns to exclude (regex)
exclude = [
  "localhost",
  "127\\.0\\.0\\.1",
  "example\\.com",
  "cpco\\.io",
  "cloudposse\\.com.*utm_",
  # Private GitHub org (not accessible to CI)
  "github\\.com/cloudposse-corp",
  "slack\\.cloudposse\\.com",
  "wttr\\.in",
  # GNU.org (rate limits and connection resets)
  "gnu\\.org",
  # The Linux Documentation Project (intermittent 502 Bad Gateway in CI)
  "tldp\\.org",
  # Linux Foundation specs (slow response times)
  "refspecs\\.linuxfoundation\\.org",
  # OpenBSD man pages (slow response times, intermittent timeouts in CI)
  "man\\.openbsd\\.org",
  # Kubernetes.io (rate limits and connection resets in CI)
  "kubernetes\\.io",
  # runatlantis.io (connection resets on automated requests)
  "runatlantis\\.io",
  # GitHub docs (intermittent 503s in CI)
  "docs\\.github\\.com",
  # npm package-lock documentation intermittently returns 503 from CI runners;
  # the canonical page returns 200 outside that transient upstream failure.
  "docs\\.npmjs\\.com/cli/v10/configuring-npm/package-lock-json/?$",
  # Cloudinary image resizing proxy
  "img\\.cloudposse\\.com",
  # atmos.tools URLs (can't verify website links locally)
  "atmos\\.tools",
  # Root-relative paths converted to file:// URLs (atmos.tools website paths)
  "file://.*/cli/",
  "file://.*/functions/",
  # Files that don't exist yet (planned documentation)
  "website/docs/cli/errors\\.mdx",
  "website/docs/cli/configuration/mask\\.mdx",
  # Documentation template placeholder (intentional)
  "github\\.com/cloudposse/atmos/issues/XXXX",
  # GitHub redirects (expected behavior)
  "github\\.com/cloudposse/atmos/releases/latest",
  "github\\.com/codespaces",
  # Raw file URLs redirect through GitHub's CDN (by design)
  "\\?raw=true",
  # shields.io redirects /github/release/ to /github/v/release/ internally (both work)
  "img\\.shields\\.io/github/release/",
  # Shields badge endpoints intermittently return 503/520 from CI runners even
  # though the badges resolve in browsers. These are decorative status badges,
  # so exclude the unstable badge and GitHub-status endpoints from link checks.
  "shields\\.io/badge/",
  "img\\.shields\\.io/github/(actions/workflow/status|last-commit)/",
  # Atmos Pro redirects to sign-in page for unauthenticated users
  "atmos-pro\\.com",
  # LF AI Foundation blog links (may change or be unavailable)
  "lfaidata\\.foundation",
  # Taskfile.dev (connection resets in CI)
  "taskfile\\.dev",
  # Gomplate docs (connection resets in CI)
  "docs\\.gomplate\\.ca",
  # regex101.com (intermittent timeouts in CI)
  "regex101\\.com",
  # nx.dev (intermittent connection failures in CI)
  "nx\\.dev",
  # Test data placeholder URLs (intentional)
  "github\\.com/test/",
  # Planned documentation paths (not yet published)
  "file://.*/ai/skills",
  "file://.*/ai/skill-marketplace",
  # Example/placeholder URLs in usage documentation
  "github\\.com/user/repo",
  # Claude Code product page (claude.com edge returns 500 to non-browser/CI requests)
  "claude\\.com/product/",
  # Claude Code docs (code.claude.com) now exhibit the same CI-hostile pattern as
  # docs.anthropic.com/platform.openai.com/clau.de below: requests from CI runners
  # 302-redirect to https://dns.google/<same-path> (a DNS-sinkhole-style artifact,
  # not a real site redirect) before 404ing, while the pages resolve normally and
  # are correctly indexed by search engines when fetched from a real browser.
  "code\\.claude\\.com",
  # regex101.com (intermittent 504 Gateway Timeout in CI)
  "regex101\\.com",
  # Anthropic's clau.de URL shortener is Cloudflare-fronted and returns 525
  # (SSL handshake failed) to non-browser/CI requests; it resolves in a real browser.
  "clau\\.de",
  # Anthropic docs intermittently return 503 Service Unavailable from CI runners.
  "docs\\.anthropic\\.com",
  # OpenAI's docs (platform.openai.com, developers.openai.com) are Cloudflare-fronted
  # and return inconsistent 403/404 responses to non-browser/CI requests depending on
  # path, even with a browser User-Agent; the pages resolve fine in a real browser.
  "platform\\.openai\\.com",
  "developers\\.openai\\.com",
  # luigi.readthedocs.io (intermittent 502 Bad Gateway in CI)
  "luigi\\.readthedocs\\.io",
  # tldp.org (intermittent 502 Bad Gateway in CI; sibling exit-code references
  # like gnu.org, man.openbsd.org, and refspecs.linuxfoundation.org are excluded for the same reason)
  "tldp\\.org",
  # no-color.org (intermittent connection failures / unreachable from CI runners;
  # it is the canonical NO_COLOR spec site referenced from the help-system and
  # io-handling PRDs, and resolves in a real browser)
  "no-color\\.org",
  # Algolia DocSearch docs (intermittent timeouts from CI runners)
  "docsearch\\.algolia\\.com",
  # Open Group POSIX specs (intermittent timeouts from CI runners)
  "pubs\\.opengroup\\.org",
  # Pact docs (intermittent timeouts from CI runners)
  "docs\\.pact\\.io",
  # google-gemini/gemini-cli repo deep-links intermittently return 502 Bad Gateway
  # from GitHub's gateway in CI; the pages are valid and load in a browser.
  "github\\.com/google-gemini/gemini-cli",
  # This specific older release tag page intermittently returns 500 Internal
  # Server Error from GitHub's gateway in CI; the page is valid and loads in
  # a browser (verified via `gh api repos/cloudposse/atmos/releases/tags/v1.203.0`).
  "github\\.com/cloudposse/atmos/releases/tag/v1\\.203\\.0",
  # Otelic (intermittent "Connection reset by peer" from CI runners; the page
  # returns 200 and loads fine outside CI, verified via curl).
  "otelic\\.com",
]