Added link checker

Author: mnocon

.github/workflows/link_check.yaml

@@ -0,0 +1,69 @@
+name: "Check documentation links"
+
+on:
+    push:
+        branches:
+            - master
+            - "[0-9]+.[0-9]+"
+    workflow_dispatch:
+        inputs:
+            force_recheck:
+                description: "Clear lychee cache and recheck all links from scratch"
+                type: boolean
+                default: false
+    pull_request: ~
+    schedule:
+        - cron: "0 6 * * *"
+
+jobs:
+    link-check:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: [3.13]
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+
+            - name: Install MkDocs dependencies
+              run: |
+                  python -m pip install --upgrade pip
+                  pip install -r requirements.txt
+
+            - name: Build documentation
+              run: mkdocs build --strict
+
+            - name: Restore lychee cache
+              if: ${{ !inputs.force_recheck }}
+              uses: actions/cache@v4
+              with:
+                  path: .lycheecache
+                  key: lychee-${{ github.ref_name }}-${{ hashFiles('lychee.toml') }}
+                  restore-keys: |
+                      lychee-${{ github.ref_name }}-
+                      lychee-
+
+            - name: Check links
+              uses: lycheeverse/lychee-action@v2
+              with:
+                  args: >-
+                      --config lychee.toml
+                      --cache
+                      --cache-exclude-status "400.."
+                      site
+                  fail: true
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Upload link-check report
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: lychee-report
+                  path: lychee-report.md
+                  if-no-files-found: ignore

.gitignore

@@ -12,3 +12,5 @@ auth.json
 yarn.lock
 docs/css/*.map
 .deptrac.cache
+.lycheecache
+lychee-report.md

docs/js/custom.js

@@ -5,7 +5,7 @@ $(document).ready(function() {
     const latestVersionNumber = '5.0';
 
     // replace edit url
-    let branchName = 'master';
+    let branchName = '5.0';
     const branchNameRegexp = /\/en\/([a-z0-9-_.]*)\//g.exec(document.location.href);
     const eolVersions = window.eol_versions ?? [];
 
@@ -21,7 +21,7 @@ $(document).ready(function() {
     }
 
     if (!/^\d+\.\d+$/.test(branchName) && branchName !== 'latest') {
-        branchName = 'master';
+        branchName = '5.0';
     }
 
     // Insert version into header links

lychee.toml

@@ -0,0 +1,120 @@
+#############################  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 = "1d"
+
+#############################  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 = 0
+
+# 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.
+# 429 = Too Many Requests (rate-limited, treat as valid).
+accept = ["200", "429"]
+
+# Proceed for server connections considered insecure (invalid TLS).
+insecure = false
+
+# Only check external links (https/http). Local file:// paths — i.e. all
+# relative and root-relative internal links — are skipped entirely.
+# Internal links are already validated by `mkdocs build --strict`.
+scheme = ["https", "http"]
+
+# Use HEAD requests — much faster than GET since no body is downloaded.
+# Fragment checking requires GET, so include_fragments is disabled;
+# internal anchor links are already validated by `mkdocs build --strict`.
+method = "head"
+
+# Mimic a browser to avoid Cloudflare bot-detection (403) on sites like doc.ibexa.co.
+user_agent = "Mozilla/5.0 (compatible; lychee link checker)"
+
+# Do NOT check anchor fragments — requires full GET downloads for every URL.
+include_fragments = false
+
+# Do NOT check links inside <code> and <pre> blocks.
+include_verbatim = false
+
+#############################  Exclusions  ##########################
+
+# Exclude URLs from checking (treated as regular expressions).
+exclude = [
+    # LinkedIn blocks automated requests
+    "^https?://(www\\.)?linkedin\\.com",
+    # Localhost and loopback addresses
+    "^https?://localhost",
+    "^https?://127\\.0\\.0\\.1",
+    # Placeholder/example domains
+    "^https?://example\\.com",
+    # GitHub login/auth pages often rate-limit or redirect bots
+    "^https?://github\\.com/login",
+]
+
+# Exclude these input paths from being scanned.
+exclude_path = [
+    # Search index, assets and sitemap contain no meaningful external links
+    "site/search",
+    "site/assets",
+    "site/404.html",
+    "site/sitemap.xml",
+    "site/robots.txt",
+]
+
+# 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.
+# Combined with scheme = ["https", "http"], the resulting file:// paths are
+# silently skipped — no HTTP check, no error.
+root_dir = "site"
+
+#############################  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"
+
+# Stricter throttling for Cloudflare-protected hosts.
+# [hosts] tables must come last in the file (TOML section scoping).
+[hosts."doc.ibexa.co"]
+concurrency = 1
+request_interval = "1s"

mkdocs.yml

@@ -2,6 +2,7 @@ INHERIT: plugins.yml
 
 site_name: Developer Documentation
 repo_url: https://github.com/ibexa/documentation-developer
+edit_uri: edit/5.0/docs
 site_url: https://doc.ibexa.co/en/latest/
 copyright: "Copyright 1999-2026 Ibexa AS and others"
 validation:

tools/api_refs/.phpdoc/template/components/source.html.twig

@@ -2,7 +2,7 @@
 
 {% block content %}
 <div class="md-header__source">
-    {% set href = 'https://github.com/ibexa/documentation-developer/tree/master/docs/api/php_api' %}
+    {% set href = 'https://github.com/ibexa/documentation-developer/tree/5.0/docs/api/php_api' %}
     {% if node.file is not null %}
         {% set path = node.file.path|split('/', 4) %}
         {% set package = path|slice(1, 2)|join('/') %}