URL validation in documentation (mkdocs)

[degenaro]

Issue description / feature objectives

See #1919 where 2 URLs were added to the ignore list for mkdocs as a work-around.

mkdocs uses htmlproofer as a plug-in to verify URL aliveness. Recently, 2 URLs failed htmlproofer access, causing the trestle validation pipeline to fail for all newly submitted trestle PRs. The work-around was to have htmlproofer skip these 2 URLs.

Find a way to have mkdocs/htmlproofer not fail these links or find an alternative way to validate them.

Caveats / Assumptions

N/A

Completion Criteria

The links are validated.

[flushthemoney]

Reproduced the issue and did some research on what can be done to solve it. Seems like it might be better to switch to another URL validation tool like markdown-link-check or lychee

These tools seem to be better at handling validation errors with urls that return 404 (similar to FedRAMP link) or asset urls (similar to the CNCF SVG link)

[degenaro]

trestle uses mkdocs. mkdocs uses htmlproofer. mkdocs would need to support a a different plugin, i think.

…

On Fri, Aug 29, 2025 at 2:08 PM Kaviraj Sankameeswaran < ***@***.***> wrote: *flushthemoney* left a comment (oscal-compass/compliance-trestle#1921) <#1921 (comment)> Reproduced the issue and did some research on what can be done to solve it. Seems like it might be better to switch to another URL validation tool like markdown-link-check <https://www.npmjs.com/package/markdown-link-check> or lychee <https://github.com/lycheeverse/lychee> These tools seem to be better at handling validation errors with urls that return 404 (similar to FedRAMP link) or asset urls (similar to the CNCF SVG link) — Reply to this email directly, view it on GitHub <#1921 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAD66XNYBWTTXETGOFE3KRL3QCJJRAVCNFSM6AAAAACFBQ6F5SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMZXHAZDAMRRHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[flushthemoney]

@degenaro So how do you want to proceed with this issue for now?

[degenaro]

@flushthemoney There are some possibilities, some can be done in parallel:

• open an issue against htmlproofer, giving the failing URLs and asking for a fix
• open an issue against mkdocs asking for a plugin for a "better" html proofer and suggest one that you have found that works for the URLs that are failing
• open a trestle child issue to incorporate a "better" proofer in the mkdocs tests, for those URLs that are in the mkdocs except list
• or suggest other courses of action...

[degenaro]

@flushthemoney Are you interested in working this issue?