Harden documentation link validation to prevent false CI passes by bitflicker64 · Pull Request #452 · apache/incubator-hugegraph-doc

bitflicker64 · 2026-02-09T12:43:42Z

Purpose of the PR

close [Bug] CI link validation misses broken internal documentation links #451

What this PR does

This PR hardens the documentation link validation used in CI.

Previously, CI could pass even when documentation contained broken internal links due to limited link detection and path resolution. This change expands validation coverage and ensures CI fails when unresolved internal links are present.

Key changes

Validate all inline Markdown links with accurate file and line numbers
Correctly resolve internal paths, including:
- /docs/* → content/en/docs/*
- /cn/docs/* → content/cn/docs/*
- absolute root paths
- relative links
Exclude fenced code blocks from validation without breaking line numbers
Skip external links and Hugo shortcodes intentionally
Validate non-Markdown assets separately (images, configs, etc.)
Fail CI deterministically on unresolved internal links

Notes

This change surfaces existing broken documentation links that CI was previously not detecting.
Those issues can be addressed incrementally in follow-up PRs.

- Add support for relative link validation - Check absolute root paths (e.g., /language/*) - Skip asset files (.png, .xml, .css, etc.) - Strip code blocks from validation - Add case-insensitive protocol detection This catches ~54 previously undetected broken links.

bitflicker64 · 2026-02-09T12:51:41Z

@imbajin This PR tightens the link validation so CI fails when unresolved internal links exist. Earlier some broken links were not being detected because the validation coverage was limited which allowed CI to pass.
With the updated validator those existing issues are now surfaced. This PR focuses on fixing the validation behaviour itself and the underlying documentation links can be cleaned up separately in follow up PRs if needed.

dist/validate-links.sh

…numbers

bitflicker64 · 2026-02-09T20:04:13Z

I improved the link validator by adding canonical path resolution, content directory boundary checks, and accurate file line reporting

imbajin · 2026-02-10T07:32:55Z

If the total number of changed lines isn't too large, I'd suggest fixing them together in this PR. Otherwise, (Required) CI failures might be troublesome & blocking the merge, and these fixes should have minimal side effects.

bitflicker64 · 2026-02-10T07:41:10Z

If the total number of changed lines isn't too large, I'd suggest fixing them together in this PR. Otherwise, (Required) CI failures might be troublesome & blocking the merge, and these fixes should have minimal side effects.

ill start working on fixing the links

dist/validate-links.sh

bitflicker64 · 2026-02-10T08:23:29Z

sorry for committing the batch ill fix the issues and continue the url fixes

bitflicker64 · 2026-02-10T14:09:10Z

Link validation checks are passing now. Fixed broken relative links, corrected SUMMARY navigation for Hugo routing, and removed an invalid reference to a nonexistent file Remaining messages are expected Hugo runtime URL warnings only.

dist/validate-links.sh

Copilot

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 3 comments.

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

Copilot · 2026-02-11T06:19:41Z

content/en/docs/clients/restful-api/rebuild.md

 Note:

-> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 1). See More [AsyncJob RESTfull API](../task)
+> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 1). See More [AsyncJob RESTfull API](./task)


Typo in link text: “RESTfull” should be “RESTful”.

Copilot · 2026-02-11T06:19:41Z

content/en/docs/clients/restful-api/rebuild.md

 Note:

-> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 2). See More [AsyncJob RESTfull API](../task)
+> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 2). See More [AsyncJob RESTfull API](./task)


Typo in link text: “RESTfull” should be “RESTful”.

Copilot · 2026-02-11T06:19:41Z

content/en/docs/clients/restful-api/rebuild.md

 Note:

-> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 3). See More [AsyncJob RESTfull API](../task)
+> You can get the asynchronous job status by `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/${task_id}` (the task_id here should be 3). See More [AsyncJob RESTfull API](./task)


Typo in link text: “RESTfull” should be “RESTful”.

dist/validate-links.sh

bitflicker64 · 2026-02-11T07:21:47Z

Thanks for the review. I will debug the issues and push a proper fix after my classes.

bitflicker64 · 2026-02-11T12:17:04Z

All validator issues raised in the review thread have been addressed.
Path normalization, absolute path handling, URL decoding, and asset resolution logic are corrected.
Heuristic behaviors for code fences and inline code detection are now explicitly documented.
The script is fail fast, Bash compatible, and produces deterministic validation results.

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated no new comments.

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

dist/validate-links.sh

content/en/docs/SUMMARY.md

imbajin

Thanks a lot for your contribution

…#452) * feat: enhance link validator to catch all internal links - Add support for relative link validation - Check absolute root paths (e.g., /language/*) - Skip asset files (.png, .xml, .css, etc.) - Strip code blocks from validation - Add case-insensitive protocol detection 202d930

bitflicker64 added 2 commits February 9, 2026 18:02

Harden link validation to fail CI on unresolved internal links

d2e5674

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. bug Something isn't working labels Feb 9, 2026

imbajin requested a review from Copilot February 9, 2026 13:31

This comment was marked as outdated.

Sign in to view

imbajin reviewed Feb 9, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

imbajin reviewed Feb 9, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

Improve link validation script with canonical path handling and line …

cbba938

…numbers

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

imbajin reviewed Feb 10, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

Fix relative links in REST API docs

60e2878

bitflicker64 added 2 commits February 10, 2026 14:33

Improve link validator robustness and diagnostics

ac43d50

Fix SUMMARY links for Hugo routing

868520e

dosubot bot removed the size:L This PR changes 100-499 lines, ignoring generated files. label Feb 10, 2026

Remove invalid hugegraph-style.xml reference

0f823fc

dosubot bot added the size:XL This PR changes 500-999 lines, ignoring generated files. label Feb 10, 2026

imbajin requested a review from Copilot February 11, 2026 06:12

Copilot started reviewing on behalf of imbajin February 11, 2026 06:12 View session

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

Copilot AI reviewed Feb 11, 2026

View reviewed changes

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

bitflicker64 added 2 commits February 11, 2026 12:19

Fix validate-link.sh

7701983

Fix validate-link.sh

25a599f

This PR addresses all validator issues raised in the review thread.

0d9ecfc

Fix broken documentation links

a9764df

imbajin requested a review from Copilot February 11, 2026 13:20

Copilot started reviewing on behalf of imbajin February 11, 2026 13:21 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Show resolved Hide resolved

imbajin reviewed Feb 11, 2026

View reviewed changes

dist/validate-links.sh Outdated Show resolved Hide resolved

imbajin reviewed Feb 11, 2026

View reviewed changes

content/en/docs/SUMMARY.md Outdated Show resolved Hide resolved

Addressed github pr review comments

0523dc8

imbajin approved these changes Feb 12, 2026

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Feb 12, 2026

imbajin merged commit 202d930 into apache:master Feb 12, 2026
1 check passed

Conversation

bitflicker64 commented Feb 9, 2026

Purpose of the PR

What this PR does

Key changes

Notes

Uh oh!

bitflicker64 commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

bitflicker64 commented Feb 9, 2026

Uh oh!

imbajin commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bitflicker64 commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bitflicker64 commented Feb 10, 2026

Uh oh!

bitflicker64 commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bitflicker64 commented Feb 11, 2026

Uh oh!

bitflicker64 commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bitflicker64 commented Feb 9, 2026 •

edited

Loading

imbajin commented Feb 10, 2026 •

edited

Loading