Skip to content

docs: explain Windows link-check false positives and WSL workflow (bounty claim) - #69

Open
MaxKerkula wants to merge 1 commit into
The-Swarm-Corporation:mainfrom
MaxKerkula:codex/docs-windows-link-check
Open

docs: explain Windows link-check false positives and WSL workflow (bounty claim)#69
MaxKerkula wants to merge 1 commit into
The-Swarm-Corporation:mainfrom
MaxKerkula:codex/docs-windows-link-check

Conversation

@MaxKerkula

Copy link
Copy Markdown

The contributor guide asks Windows users to run mint broken-links, but native Windows CLI 4.2.876 reports an existing nested page as broken. On this repository's current base (bfa65868ddd1152ec46406eb896e6f4baad29061), it reports 232 links in 70 files. Running the same CLI version with Linux Node in WSL on the same checkout reports none. This is consistent with Mintlify issue #5680.

Add a focused Windows troubleshooting section to the existing contributor guide. It shows how to identify the Linux toolchain, keep the npm cache separate, check the edited checkout, and interpret the exit code without suppressing failures. It also explains the cost of a separate Linux installation and the limits of a link check. No navigation or application code changes are included.

Validation:

  • On a fixture with existing shallow and nested pages, Windows incorrectly reports the nested page; Linux passes.
  • Adding a nonexistent-page link makes Linux fail with only that missing link. Windows reports both the false positive and the missing link.
  • The exact documented npm_config_cache=... npx --yes mint@4.2.876 broken-links command passes on the edited documentation tree, with exit 0.
  • git diff --check passes.

Both installations use Mint 4.2.876. Windows uses Node 22.23.2; WSL uses Node 22.22.0, so the runtime patch versions are not held constant. The public verification report gives the fixture and scope limits. The full mint validate build and a rendered Mintlify preview are not verified. No provider API calls, credentials, or customer data were used.

Bounty claim: Please consider the Silver tier under the documentation bounty program. This is a small troubleshooting tutorial of about 320 words, with executed instructions and a negative control. PayPal is preferred if an award is approved after merge; payment details will be shared privately. No award, reservation, payment, or maintenance agreement is assumed.

This is AI-assisted work. It is separate from the optional-provider example in #68. The newer link-check evidence was also used to correct that PR's validation description.

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.

1 participant