ENH: Add lychee link-checker as a Utilities/Maintenance script

[jhlegarreta]

Add a manual lychee link-checker (Utilities/Maintenance/check-links.sh + lychee.toml) for periodic maintainer-driven runs, instead of the per-PR GHA workflow originally proposed.

Why a manual script instead of a GHA workflow

The original workflow attempt failed CI consistently due to:

• HTTP 429 rate-limits from github.com on commit URLs in release notes (no per-run workaround that doesn't also accept real broken links).
• lycheeverse/lychee#1574 — caching across CI runs is not effective.
• False positives on host-specific bot blocks (999 from LinkedIn, etc.).

In the Feb 2026 discussion on this PR, @jhlegarreta agreed the per-PR CI approach was not workable and authorized a pivot. This commit takes over the branch (with Co-Authored-By: credit) and converts to the script approach.

What's included

Path	Purpose
Utilities/Maintenance/check-links.sh	Bash wrapper. Resolves the repo root, requires lychee on PATH, accepts optional path arguments, writes a Markdown report and persistent cache.
Utilities/Maintenance/lychee.toml	Configuration with rate-limit-aware accept = [..., 429, 999], commit-URL skip regex, ThirdParty exclusion, and document-only include globs.
.gitignore	Adds .lycheecache and .lychee-report.md (local artifacts).

Intended use: a maintainer runs Utilities/Maintenance/check-links.sh periodically (or scopes it to a subdirectory) and acts on the report. No CI gate is added.

[jhlegarreta]

Not sure why it complains for the links to the commits in the release notes files.

[dzenanz]

Many failures are due to HTTP code 429: Network error: Too Many Requests. Can we slow down request rate or something similar?

[jhlegarreta]

Looks like the limiting the rate of requests through caching does not work. Not sure if the cache has to be built first to have it working. Have gone through these
https://github.com/lycheeverse/lychee-action?tab=readme-ov-file#utilising-the-cache-feature
https://github.com/lycheeverse/lychee/blob/master/docs/TROUBLESHOOTING.md

but have not found how to modify the arguments to make throttling/request pace limiting work. Have seen other workflows accepting 429, e.g.

--accept 403,429,500,502,999

but I guess that will effectively not check the links at issue.

Also, checks will not work until this issue is solved:
lycheeverse/lychee#1574

I do not know any other tool that does this job for rst files. This one only seems to work for md files:
https://github.com/tcort/markdown-link-check

[hjmjohnson]

@jhlegarreta It seems like this effort has been abandoned due to difficulties. Perhaps this effort can be made into a manual script in the Utilities directory that is periodically run rather than addding it to the CI in a way that will slow down other efforts?

I'm making a pass through issues trying reduce the number of stale, unlikely to proceed issues.

[jhlegarreta]

@hjmjohnson thanks for the heads-up; going through challenging times on my end, so I am being unable to push ITK items. My sincere apologies. The approach you propose sounds reasonable. Feel free to close the PR.

[hjmjohnson]

@jhlegarreta — thank you for the original work and for the OK to pivot. Force-pushed cc6bfedde3 to AddLinkCheckerGHAWorkflow (lease pinned to your prior tip). The branch now contains a manual Utilities/Maintenance/check-links.sh + lychee.toml instead of the GHA workflow, with you credited via Co-Authored-By: on the commit. Title and body updated to match.

Holler if you'd rather I close this and open the script under a fresh PR — both work; reusing this branch felt cleaner since the conversation history is already here.

[greptile-apps]

Greptile Summary

This PR adds a manual lychee link-checker maintenance script (Utilities/Maintenance/check-links.sh + lychee.toml) for periodic maintainer-driven use, and accompanies it with a broad sweep of broken-link fixes across 22 documentation files (dead http:// URLs, stale Kitware blog posts, old Doxygen paths, and outdated wiki links).

• New tooling: check-links.sh wraps lychee with caching, a per-run Markdown report, and optional path scoping; lychee.toml configures rate-limit-aware accept codes, commit-URL skip regex, and extension/path filters. Both files are gitignored via .gitignore.
• Documentation sweep: ~60 link replacements across release notes, migration guide, FAQ, and contributing docs.
• One behavioural bug in the script: set -euo pipefail conflicts with the manual status=$? / exit $status pattern \u2014 when lychee finds broken links it exits non-zero, causing bash to terminate immediately and skipping the confirmation message.

Confidence Score: 3/5

Safe to merge after fixing the set -e conflict in check-links.sh; all other findings are documentation cosmetics.

The shell script's set -euo pipefail silently swallows the "Report written to..." confirmation and bypasses the explicit exit-code path whenever lychee finds broken links — precisely the case this tool is built for. The lychee.toml exclude-path entry points to a non-existent directory. The documentation changes are straightforward link-rot fixes with no logic implications.

Utilities/Maintenance/check-links.sh (exit-code handling) and Utilities/Maintenance/lychee.toml (stale exclude path).

Important Files Changed

Filename	Overview
Utilities/Maintenance/check-links.sh	New lychee wrapper script; set -euo pipefail conflicts with the manual exit-code capture pattern — the "Report written to" message and exit $status are skipped when lychee finds broken links.
Utilities/Maintenance/lychee.toml	New lychee config; exclude_path entry Documentation/Release is stale — release notes live at Documentation/docs/releases/ — making the exclusion a silent no-op.
.gitignore	Adds .lycheecache and .lychee-report.md gitignore entries; correct and complete.
Documentation/docs/releases/1.0.md	Dead links updated; CDash URL is duplicated in the resource list (two entries with identical URL replacing two formerly distinct resources).
Documentation/Maintenance/Release.md	Corrects release-notes directory reference from Documentation/ReleaseNotes to Documentation/docs/releases.
Documentation/docs/migration_guides/itk_5_migration_guide.md	Doxygen links updated to docs.itk.org; an incomplete "Update scripts" stub section removed cleanly.
Documentation/docs/releases/5.0b03.md	Multiple dead links replaced with current GitHub/main-branch equivalents; JIRA tracker noted as decommissioned.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Maintainer runs check-links.sh]) --> B{lychee on PATH?}
    B -- No --> C[exit 127]
    B -- Yes --> D{lychee.toml present?}
    D -- No --> E[exit 1]
    D -- Yes --> F[cd REPO_ROOT]
    F --> G{Args supplied?}
    G -- No --> H[default scan]
    G -- Yes --> I[use supplied paths]
    H & I --> J[lychee runs with cache and markdown output]
    J -- exit 0 --> K[echo Report written, exit 0]
    J -- exit non-zero --> L[set -e terminates: echo and exit skipped]
    K --> M([Done])
    L --> N([Script exits with lychee code without confirmation])

Loading

_{Reviews (1): Last reviewed commit: "ENH: lychee.toml absorbs gateway-timeout..." | Re-trigger Greptile}

[jhlegarreta]

Holler if you'd rather I close this and open the script under a fresh PR — both work; reusing this branch felt cleaner since the conversation history is already here.

@hjmjohnson This is fine. Thanks for all this work.

[hjmjohnson]

Thanks @jhlegarreta for initiating this effort.