Skip to content

Add html-proofer link check for 4.x docs - #497

Merged
DomGarguilo merged 8 commits into
apache:mainfrom
DomGarguilo:link-checker
Oct 6, 2026
Merged

DomGarguilo merged 8 commits into
apache:mainfrom
DomGarguilo:link-checker

Conversation

@DomGarguilo

@DomGarguilo DomGarguilo commented Sep 28, 2026 •

Copy link
Copy Markdown
Member

This PR adds an internal link checker to the CI to make sure we are actively fixing any dead/broken links.

The config/setup for things to run in the CI was added in 980113f

Tooling added:

  • html-proofer added to the Gemfile
  • Rakefile: defines the task (named links here) which opens the built site (from _site/), checks all internal links against the files that actually exist, for now skips checks for everythign outside of the docs/4.x dir, prints errors if there are any

Here are some resources I used to add this feature:

@dlmarion dlmarion left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't have any experience with this, but the changes look benign to me.

@DomGarguilo

DomGarguilo commented Sep 29, 2026 •

Copy link
Copy Markdown
Member Author

Marking this as ready for review now. Once #495 is merged the failing checks will pass.

This PR fixes ~50 errors from the tooling added.

An example of what the new CI check looks like when it fails can be seen at 231e026. Here is a snippet from that failing check:

* At ./_site/docs/4.x/administration/in-depth-install.html:936:

  internally linking to /docs/4.x/configuration/server-properties#tserver_port_search; the file exists, but the hash 'tserver_port_search' does not

* At ./_site/docs/4.x/administration/in-depth-install.html:937:

  internally linking to /docs/4.x/configuration/server-properties#replication_receipt_service_port; the file exists, but the hash 'replication_receipt_service_port' does not


HTML-Proofer found 16 failures!

That commit makes these issues fail the build instead of warn so it now catches the broken links that will be fixed as of the changes in #495

Update: the build passes after merging. 92132cd

@ctubbsii ctubbsii left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Very cool. I just have a few suggestions to improve the wording around some of the broken links that were fixed.

Comment thread _docs-4/administration/upgrading.md Outdated
Comment thread _docs-4/configuration/files.md
Comment thread Gemfile Outdated
Comment thread Rakefile Outdated
ctubbsii and others added 2 commits October 2, 2026 18:48
Co-authored-by: Christopher Tubbs <ctubbsii@apache.org>
@DomGarguilo
DomGarguilo merged commit e4a536e into apache:main Oct 6, 2026
1 check passed
@DomGarguilo
DomGarguilo deleted the link-checker branch October 6, 2026 16:21
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