lychee.toml.dist

#############################  Display  #############################

# Verbose program output
verbose = "warn"

# Output format
format = "markdown"

# Path to report output file
output = "lychee-report.md"

# Don't show interactive progress bar while checking links.
no_progress = false

#############################  Cache  ###############################

# Enable link caching to avoid re-checking identical links across runs.
cache = true

# Discard cached results older than this duration.
max_cache_age = "2d"

#############################  Runtime  #############################

# Maximum number of allowed redirects. Set to 0 to fail on any redirect —
# a redirect usually signals moved or reorganised content that should be
# updated at the source.
max_redirects = 1

# Maximum number of allowed retries before a link is declared dead.
max_retries = 3

# Minimum wait time in seconds between retries of failed requests.
retry_wait_time = 2

# Maximum number of concurrent link checks across all hosts.
max_concurrency = 8

#############################  Requests  ############################

# Website timeout from connect to response finished (seconds).
timeout = 20

# Comma-separated list of accepted status codes for valid links.
accept = ["200", "202"]

# Proceed for server connections considered insecure (invalid TLS).
insecure = false

# Check https/http and file:// (used by remap rules below).
# Internal file:// links (resolved via root_dir) are excluded separately — see the
# exclude list below. Only cross-doc file:// links produced by remap rules are checked.
scheme = ["https", "http", "file"]

# GET is required for fragment checking (HEAD responses have no body).
method = "GET"

user_agent = "Mozilla/5.0 (compatible; lychee link checker)"

# Check anchor fragments in cross-doc links (remapped to explicit index.html paths).
# Internal fragments are already validated by `mkdocs build --strict` and are excluded
# via the file:// exclude pattern below.
include_fragments = "full"

# Do NOT check links inside <code> and <pre> blocks.
include_verbatim = false

#############################  Exclusions  ##########################

# Exclude URLs from checking (treated as regular expressions).
# External-host exclusions (bot-blocks, redirects, false positives) live in .lycheeignore.
# Only structural patterns that depend on the build path are kept here.
exclude = [
    # Internal file:// links are resolved by lychee from root-relative hrefs via root_dir.
    # They point to the local MkDocs output and are already validated by `mkdocs build --strict`.
    # Cross-doc links produced by the remap rules below go through the `repositories/`
    # subdirectory and are therefore NOT matched by this pattern.
    "^file://__BASE_DIR__/site/",
    # Versionless project root links (e.g. /projects/connect, /projects/userguide) appear in
    # the MkDocs theme sidebar as cross-project navigation and are not real content links.
    # The https form appears as absolute links; the file:// form appears after root_dir resolution
    # of root-relative hrefs like /projects/connect in the built HTML.
    "^https?://doc\\.ibexa\\.co/projects/[^/]+/?$",
    "^file://.*?/site/projects/[^/]+/?$",
]

# Exclude these input paths from being scanned.
exclude_path = [
    # Search index, assets and sitemap contain no meaningful external links
    "site/search/search_index.json",
    "site/assets",
    "site/sitemap.xml",
    # PHP API reference HTML is generated by phpDocumentor and uses <base href="../"> to resolve
    # relative links — lychee does not honour <base> tags and would flag them as broken.
    # Links pointing *to* these files from other pages are still checked.
    "site/api/php_api/php_api_reference/",
]

# Check the specified file extensions
extensions = ["html"]

# Exclude all private IPs from checking.
exclude_all_private = true

#############################  Local files  #########################

# Required to resolve root-relative links (e.g. href="/…") found in every page into
# file:// URLs. Those file:// URLs are then excluded from checking by the pattern in
# the exclude list — internal links are validated by `mkdocs build --strict`.
# `site` is the default `mkdocs build` output directory.
root_dir = "site"

#############################  Remap  ###############################

# Rewrite doc.ibexa.co links to locally-built MkDocs sites, avoiding HTTP
# requests to Cloudflare-protected hosts.
#
# - en/latest/           → current build's site/ directory (self-referential links from cards() macro)
# - en/4.6/              → repositories/devdoc-4.6/site/
# - en/5.0/              → repositories/devdoc-5.0/site/
# - userguide/en/latest/ → repositories/userdoc-5.0/site/ (newest available)
# - userguide/en/4.6/    → repositories/userdoc-4.6/site/
# - userguide/en/5.0/    → repositories/userdoc-5.0/site/
# - connect/en/latest/   → repositories/connect/site/
#
# Three patterns per version handle all URL shapes.
# NOTE: lychee applies remap BEFORE stripping the fragment, so each pattern uses
# an optional (#.*)? group to capture and forward fragments to the local file path.
#
#   Pattern 1 — direct .html files (e.g. REST/PHP API reference):
#               ([^#]+\.html)(#.*)?$
#
#   Pattern 2 — directory paths (with or without trailing slash, with path segments):
#               ([^#/]+(?:/[^#/]+)*)/?(#.*)?$
#               $1 captures the path without a trailing slash; replacement always adds /index.html.
#
#   Pattern 3 — bare version root (e.g. /en/5.0/ with nothing after):
#               $  (exact match of the version prefix)
remap = [
    # GitHub line-number fragments (#L7, #L12-L15) are rendered via JavaScript —
    # lychee cannot find them in the raw HTML. Strip the fragment so the file
    # existence is still verified.
    "^(https://github\\.com/[^#]+)#L[0-9].* $1",
    # MDN URLs without a locale redirect to the browser's preferred language.
    # Remap to en-US so lychee can verify the link without following the redirect.
    "^https://developer\\.mozilla\\.org/docs/(.+) https://developer.mozilla.org/en-US/docs/$1",
    # doc.ibexa.co/en/latest/ links are self-referential: the cards() macro generates
    # them when READTHEDOCS_VERSION_NAME is not set (e.g. in CI). Remap to the locally
    # built site/ directory. These file:// URLs are then matched by the exclude pattern
    # above and skipped — internal links are validated by `mkdocs build --strict`.
    "https://doc\\.ibexa\\.co/en/latest/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/site/$1$2",
    "https://doc\\.ibexa\\.co/en/latest/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/en/latest/$ file://__BASE_DIR__/site/index.html",
    # userguide en/latest/ — map to the newest available clone (userdoc-5.0)
    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/$ file://__BASE_DIR__/repositories/userdoc-5.0/site/index.html",
    # devdoc 4.6
    "https://doc\\.ibexa\\.co/en/4\\.6/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/devdoc-4.6/site/$1$2",
    "https://doc\\.ibexa\\.co/en/4\\.6/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/devdoc-4.6/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/en/4\\.6/$ file://__BASE_DIR__/repositories/devdoc-4.6/site/index.html",
    # devdoc 5.0
    "https://doc\\.ibexa\\.co/en/5\\.0/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/devdoc-5.0/site/$1$2",
    "https://doc\\.ibexa\\.co/en/5\\.0/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/devdoc-5.0/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/en/5\\.0/$ file://__BASE_DIR__/repositories/devdoc-5.0/site/index.html",
    # userdoc 4.6
    "https://doc\\.ibexa\\.co/projects/userguide/en/4\\.6/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/userdoc-4.6/site/$1$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/4\\.6/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/userdoc-4.6/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/4\\.6/$ file://__BASE_DIR__/repositories/userdoc-4.6/site/index.html",
    # userdoc 5.0
    "https://doc\\.ibexa\\.co/projects/userguide/en/5\\.0/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/5\\.0/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/5\\.0/$ file://__BASE_DIR__/repositories/userdoc-5.0/site/index.html",
    # userdoc master — treated as the newest available (userdoc-5.0)
    "https://doc\\.ibexa\\.co/projects/userguide/en/master/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/master/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/projects/userguide/en/master/$ file://__BASE_DIR__/repositories/userdoc-5.0/site/index.html",
    # connect — single branch, mapped from both en/latest/
    "https://doc\\.ibexa\\.co/projects/connect/en/latest/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/connect/site/$1$2",
    "https://doc\\.ibexa\\.co/projects/connect/en/latest/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/connect/site/$1/index.html$2",
    "https://doc\\.ibexa\\.co/projects/connect/en/latest/$ file://__BASE_DIR__/repositories/connect/site/index.html",
]

#############################  Hosts  ###############################

# Global limit: at most 2 simultaneous requests to any single host.
host_concurrency = 2

# Global minimum interval between requests to the same host.
host_request_interval = "500ms"