Principle:Kserve Kserve Doc Link Verification
| Knowledge Sources | |
|---|---|
| Domains | Documentation, Quality_Assurance, CI_CD |
| Last Updated | 2026-02-13 00:00 GMT |
Overview
An automated quality assurance practice that validates hyperlinks within documentation to detect broken references, ensuring documentation remains accurate and navigable over time.
Description
Doc Link Verification is a documentation maintenance pattern that programmatically crawls documentation files, extracts all hyperlinks (internal cross-references and external URLs), and verifies that each link resolves to a valid target. This catches common documentation decay problems: renamed pages, deleted files, changed URL structures, and external sites that have gone offline.
In open-source projects with rapidly evolving APIs and documentation, link rot is a persistent quality problem. Automated link checking integrated into CI/CD pipelines ensures that documentation contributions do not introduce broken links and that existing links are periodically validated. The verification typically distinguishes between internal links (which can be validated by checking file existence) and external links (which require HTTP requests to verify availability).
Usage
Use this principle when:
- Maintaining documentation across a large repository with many cross-references
- Running CI checks on documentation pull requests
- Performing periodic documentation health audits
- Migrating documentation between platforms or URL structures
Theoretical Basis
# Doc link verification algorithm (NOT implementation code)
Link verification process:
1. Scan documentation files (Markdown, HTML, RST)
2. Extract all hyperlinks:
- Internal links: relative paths, anchor references
- External links: HTTP/HTTPS URLs
3. For each internal link:
a. Resolve relative path from source file location
b. Check if target file exists in the repository
c. If anchor reference, check if heading/ID exists in target
d. Report broken if target not found
4. For each external link:
a. Send HTTP HEAD request (fall back to GET if HEAD not supported)
b. Follow redirects (up to a configurable limit)
c. Check response status code
d. Report broken if 4xx/5xx or timeout
5. Aggregate results:
- List of broken links with source file and line number
- Optionally: list of redirected links for cleanup
CI integration:
- Run on every PR that modifies documentation files
- Exit with non-zero code if broken links found
- Allow configurable ignore patterns for known-flaky external URLs