Skip to content

Add internal link checker for documentation#8178

Merged
josbeir merged 2 commits into5.xfrom
add-broken-link-checker
Jan 28, 2026
Merged

Add internal link checker for documentation#8178
josbeir merged 2 commits into5.xfrom
add-broken-link-checker

Conversation

@josbeir
Copy link
Contributor

@josbeir josbeir commented Jan 28, 2026

This PR adds automated validation of internal markdown links with baseline support for existing issues.

Changes

Link Checker Script (bin/check-links.js)

  • Validates internal file references and anchor links
  • Zero dependencies (Node.js built-ins only)
  • Supports glob patterns: "docs/**/*.md"
  • Baseline filtering to ignore known issues (opt-in)

CI Integration (.github/workflows/docs-validation.yml)

  • Added link-check job
  • PRs: Checks only changed files
  • Uses baseline to focus on new issues only

Baseline (.github/linkchecker-baseline.json)

  • 421 existing broken links cataloged
  • Opt-in via --baseline flag

Usage

# Check files
node bin/check-links.js docs/en/installation.md
node bin/check-links.js "docs/**/*.md"

# With baseline
node bin/check-links.js --baseline .github/linkchecker-baseline.json "docs/**/*.md"

Copilot AI review requested due to automatic review settings January 28, 2026 07:49
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds an internal Markdown link checker and integrates it into CI to prevent introducing new broken internal links while tolerating existing known issues via a baseline.

Changes:

  • Added a zero-dependency Node.js link-checker (bin/check-links.js) with optional baseline filtering and baseline generation.
  • Integrated link checking into the documentation validation GitHub Actions workflow.
  • Added contributor documentation for running the link checker locally and committed a baseline of existing issues.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File Description
docs/en/contributing/documentation.md Documents how to run the new link checker and adds it to the local pre-flight command list.
bin/check-links.js Implements internal link validation, globbing, anchor resolution, and baseline filtering/generation.
.github/workflows/docs-validation.yml Adds a new CI job to run the link checker (baseline-enabled) on changed markdown files.
.github/linkchecker-baseline.json Stores the catalog of known broken links for baseline filtering.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@josbeir josbeir merged commit 1f20739 into 5.x Jan 28, 2026
5 checks passed
@josbeir josbeir deleted the add-broken-link-checker branch January 28, 2026 09:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants