prometheus · zeitlinger · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026
diff --git a/.editorconfig b/.editorconfig
@@ -18,5 +18,5 @@ max_line_length = 120
 indent_size = 4
 max_line_length = 120
 
-[{.mise/tasks/build-release.sh,.mise/tasks/lint/super-linter.sh,.github/workflows/multi-version-test.yml}]
-max_line_length = 200
+[{.mise/tasks/build-release.sh,.mise/tasks/lint/super-linter.sh,.mise/tasks/lint/links-in-modified-files.sh,.github/workflows/multi-version-test.yml,.github/workflows/lint-rest.yml}]
+max_line_length = 200
diff --git a/.github/config/lychee.toml b/.github/config/lychee.toml
@@ -0,0 +1,35 @@
+# Lychee configuration file
+# See https://lychee.cli.rs/config/
+
+timeout = 30
+retry_wait_time = 5
+max_retries = 6
+max_concurrency = 4
+
+# Check link anchors
+include_fragments = true
+
+base_url = "https://prometheus.github.io"
+exclude_path = ["docs/themes"]
+
+remap = [
+  # workaround for https://github.com/lycheeverse/lychee/issues/1729
+  "https://github.com/(.*?)/(.*?)/blob/(.*?)/(.*#.*)$ https://raw.githubusercontent.com/$1/$2/$3/$4"
+]
+
+exclude = [
+  # excluding links to pull requests and issues is done for performance
+  "^https://github.com/prometheus/client_java/(issues|pull)/\\d+$",
+
+  # exclude localhost URLs as they require running services
+  "^http://localhost",
+  "^https://localhost",
+
+  '#',
+  'CONTRIBUTING.md',
+  'LICENSE',
+  'MAINTAINERS.md',
+
+  # exclude private GitHub settings pages
+  "^https://github.com/prometheus/client_java/settings/",
+]
diff --git a/.github/workflows/lint-rest.yml b/.github/workflows/lint-rest.yml
@@ -1,9 +1,14 @@
 ---
 name: Lint What Super Linter Can't
 
-on: [pull_request]
+on:
+  pull_request:
+  push:
+    branches:
+      - main
 
-permissions: {}
+permissions:
+  contents: read
 
 jobs:
   lint:
@@ -12,10 +17,20 @@ jobs:
       - name: Check out
         with:
           persist-credentials: false
+          fetch-depth: 0 # needed for merge-base used in lint:links-in-modified-files
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1
         with:
           version: v2026.1.7
           sha256: d98523f15392ab17909a55560244667aa81122766209b816d9a9b9585109bfea
-      - name: Lint
-        run: mise run lint:rest
+
+      - name: Lint for pull requests
+        if: github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+          GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          mise run lint:bom
+          mise run lint:local-links
+          mise run lint:links-in-modified-files --base origin/"${GITHUB_BASE_REF}" --head "${GITHUB_HEAD_SHA}"
diff --git a/.mise/tasks/lint/links-in-modified-files.sh b/.mise/tasks/lint/links-in-modified-files.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+#MISE description="Lint links in modified files"
+
+set -e
+
+#USAGE flag "--base <base>" help="base branch to compare against (default: origin/main)" default="origin/main"
+#USAGE flag "--head <head>" help="head branch to compare against (empty for local changes) (default: empty)" default=""
+
+# shellcheck disable=SC2154
+if [ "$usage_head" = "''" ]; then
+	usage_head=""
+fi
+
+# Check if lychee config was modified
+# - because usage_head may be empty
+# shellcheck disable=SC2086,SC2154
+config_modified=$(git diff --name-only --merge-base "$usage_base" $usage_head |
+	grep -E '^(\.github/config/lychee\.toml|\.mise/tasks/lint/.*|mise\.toml)$' || true)
+
+if [ -n "$config_modified" ]; then
+	echo "config changes, checking all files."
+	mise run lint:links
+else
+	# Using lychee's default extension filter here to match when it runs against all files
+	# Note: --diff-filter=d filters out deleted files
+	# - because usage_head may be empty
+	# shellcheck disable=SC2086
+	modified_files=$(git diff --name-only --diff-filter=d "$usage_base" $usage_head |
+		grep -E '\.(md|mkd|mdx|mdown|mdwn|mkdn|mkdown|markdown|html|htm|txt)$' |
+		tr '\n' ' ' || true)
+
+	if [ -z "$modified_files" ]; then
+		echo "No modified files, skipping link linting."
+		exit 0
+	fi
+
+	# shellcheck disable=SC2086
+	mise run lint:links $modified_files
+fi
diff --git a/.mise/tasks/lint/links.sh b/.mise/tasks/lint/links.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Lint links in all files"
+
+set -e
+
+#USAGE arg "<file>" var=#true help="files to check" default="."
+
+# shellcheck disable=SC2154
+for f in $usage_file; do
+	echo "Checking links in file: $f"
+done
+
+# shellcheck disable=SC2086
+lychee --verbose --config .github/config/lychee.toml $usage_file
diff --git a/.mise/tasks/lint/local-links.sh b/.mise/tasks/lint/local-links.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Lint links in local files"
+
+set -e
+
+#USAGE arg "<file>" var=#true help="files to check" default="."
+
+# shellcheck disable=SC2154
+for f in $usage_file; do
+	echo "Checking links in file: $f"
+done
+
+# shellcheck disable=SC2086
+lychee --verbose --scheme file --include-fragments --config .github/config/lychee.toml $usage_file
diff --git a/lychee.toml b/lychee.toml
diff --git a/mise.toml b/mise.toml
@@ -43,10 +43,6 @@ run = "./mvnw verify"
 description = "build all modules without tests"
 run = "./mvnw install -DskipTests -Dcoverage.skip=true"
 
-[tasks."lint:links"]
-description = "Lint markdown links"
-run = "lychee --include-fragments ."
-
 [tasks."lint:rest"]
 description = "All lints not covered by super linter"
 depends = ["lint:links", "lint:bom"]