Skip to content

ci: ignore repo-local and localhost links in mdox link validation (fixes #2879) - #3079

Open
santhiprakash wants to merge 1 commit into
prometheus:mainfrom
santhiprakash:fix-mdox-link-validation-2879
Open

ci: ignore repo-local and localhost links in mdox link validation (fixes #2879)#3079
santhiprakash wants to merge 1 commit into
prometheus:mainfrom
santhiprakash:fix-mdox-link-validation-2879

Conversation

@santhiprakash

Copy link
Copy Markdown
Contributor

Problem

The mdox link validation step added in #2820 reports false positives for two common link patterns in the docs:

  • Repo-local absolute URLs such as /docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config or /docs/visualization/browser. These are website routes that are generated by the prometheus.io site, not files present in this repository.
  • Tutorial links to localhost, e.g. http://localhost:9090/graph?..., which are not reachable in CI.

This was reproduced with docs/guides/file-sd.md and docs/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. The explicitLocalValidators feature that routes local links through the configured validators is present in a later commit but has not been released yet.

Fix

  • Pin the mdox version in the Makefile to commit e88e0a8655a0c91ef6a849edd29798e7e4809d75, which adds explicitLocalValidators and the local validator type.
  • Update .mdox.validator.yaml:
    • Set explicitLocalValidators: true.
    • Keep the existing http(s|)://.* ignore rule (this already covers http://localhost and all external links).
    • Add a ^/.* ignore rule for repo-local absolute URLs.
    • Add a catch-all local validator so relative local links (e.g. ./node-exporter.md) are still checked.
  • Reformat docs/guides/cadvisor.md with the updated mdox so the example mdox fmt --check invocation passes (docs/guides/file-sd.md was already formatted).

Verification

# The original repro command now passes for both guides:
mdox fmt --links.validate --links.validate.config-file=./.mdox.validator.yaml --check docs/guides/file-sd.md
mdox fmt --links.validate --links.validate.config-file=./.mdox.validator.yaml --check docs/guides/cadvisor.md

# CI-style check is still green and scoped to the OpenMetrics spec:
make check

Risks

  • The mdox pin is to an unreleased commit, not a tagged version. This is required because the local-validator feature has not shipped in a release. The Makefile now installs from a stable Git SHA.
  • docs/guides/cadvisor.md contains 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

 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
santhiprakash force-pushed the fix-mdox-link-validation-2879 branch from 2d96c58 to 0ce48df Compare August 23, 2026 17: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.

improve link-validation action

1 participant