fix(tools): check raw HTML image and link references in validate_docs - #439
Open
HugoFernandezz wants to merge 1 commit into
Open
Conversation
The path check only looked at Markdown links/images and Archbee's ::Image[] / :inlineImage[] directives, so references written as raw HTML were never checked. Pages built out of Archbee HTML tables use that form exclusively: docs/general/Controls.md (10 icons) and docs/cpu-software/FlipCTL.md (5 screenshots) hold 15 image references between them, plus one <a href> on Markup-reference.md, none of which CI would have caught if the target were renamed or removed. Extract <img src=...> and <a href=...> alongside the existing patterns, both quote styles. Fenced examples stay excluded as before, so the documented placeholder markup in Markup-reference.md is not flagged. Signed-off-by: HugoFernandezz <104948166+HugoFernandezz@users.noreply.github.com>
HugoFernandezz
force-pushed
the
fix/validate-raw-html-refs
branch
from
August 25, 2026 15:35
5cf62fc to
d6ced32
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
1 participant
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.
What's wrong
tools/validate_docs.pyonly extracts references from Markdown links/images and Archbee's::Image[]/:inlineImage[]directives. References written as raw HTML are invisible to it — and the pages built out of Archbee HTML tables use that form exclusively:docs/general/Controls.md— 10<img src="/files/icons/controls/*.svg">docs/cpu-software/FlipCTL.md— 5<img src="/files/pics/flipctl-*.png">docs/resources/docs/Markup-reference.md— 1<a href="Markup-reference.md">If any of those targets were renamed or removed, CI would stay green and the page would ship with a broken image.
How to reproduce
Create a page with three broken references, one per syntax:
python3 tools/validate_docs.py --docs-root <that dir>reports only the Markdown one:The fix
Extract
<img src="...">and<a href="...">alongside the existing patterns, both quote styles.<img>goes through the same image resolution as the Archbee directives (file-relative, then the docs-root fallback);<a href>is treated as a normal link, so its#fragmentis anchor-checked too. Fenced blocks are still skipped, so the placeholder markup documented inMarkup-reference.mdisn't flagged.After the fix, the same input reports all three:
Checks
public-releasewithout this change; all 48 pass with it.python3 tools/validate_docs.pyon the real corpus:0 error(s) across 78 files scanned— the 16 newly covered references all resolve, no new false positives.cd tools && mypy *.py:Success: no issues found in 4 source files.