ci: ignore repo-local and localhost links in mdox link validation (fixes #2879) - #3079
Open
santhiprakash wants to merge 1 commit into
Open
ci: ignore repo-local and localhost links in mdox link validation (fixes #2879)#3079santhiprakash wants to merge 1 commit into
santhiprakash wants to merge 1 commit into
Conversation
prometheus#2879) - Enable explicitLocalValidators in .mdox.validator.yaml so absolute local/website-root links are routed through the configured validators. - Add an ignore rule for repo-local absolute URLs (^/.*) which resolve to site routes rather than files on the local filesystem. - Add a catch-all local validator to keep validating relative local links. - Pin mdox to the commit (e88e0a8) that introduces explicitLocalValidators and the local validator type. - Reformat docs/guides/cadvisor.md with the updated mdox so the example validation command passes (docs/guides/file-sd.md was already formatted). The external URL ignore rule already covers http://localhost links, so no additional localhost rule is required. Signed-off-by: Santhi Prakash <b.santhiprakash@gmail.com> Co-Authored-By: Paperclip <noreply@paperclip.ing>
santhiprakash
force-pushed
the
fix-mdox-link-validation-2879
branch
from
August 23, 2026 17:43
2d96c58 to
0ce48df
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The mdox link validation step added in #2820 reports false positives for two common link patterns in the docs:
/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_configor/docs/visualization/browser. These are website routes that are generated by the prometheus.io site, not files present in this repository.localhost, e.g.http://localhost:9090/graph?..., which are not reachable in CI.This was reproduced with
docs/guides/file-sd.mdanddocs/guides/cadvisor.md.Root cause
mdox v0.9.0 only applies configured validators to
http(s)://links. Local/absolute links are always validated directly against the filesystem, so an ignore regex like^/.*in the validator config has no effect. TheexplicitLocalValidatorsfeature that routes local links through the configured validators is present in a later commit but has not been released yet.Fix
mdoxversion in theMakefileto commite88e0a8655a0c91ef6a849edd29798e7e4809d75, which addsexplicitLocalValidatorsand thelocalvalidator type..mdox.validator.yaml:explicitLocalValidators: true.http(s|)://.*ignore rule (this already covershttp://localhostand all external links).^/.*ignore rule for repo-local absolute URLs.localvalidator so relative local links (e.g../node-exporter.md) are still checked.docs/guides/cadvisor.mdwith the updated mdox so the examplemdox fmt --checkinvocation passes (docs/guides/file-sd.mdwas already formatted).Verification
Risks
mdoxpin is to an unreleased commit, not a tagged version. This is required because the local-validator feature has not shipped in a release. TheMakefilenow installs from a stable Git SHA.docs/guides/cadvisor.mdcontains formatting changes produced by the newer mdox (GFM table, list numbering, blank lines around headings). No documentation content was changed.Fixes #2879
cc @jan--f