Repository navigation
fix: name the document a refused Markdown link is in, and report all of them - #95
Open
glennmichael123 wants to merge 2 commits into
Open
glennmichael123 wants to merge 2 commits into
glennmichael123 wants to merge 2 commits into
Conversation
Both link failures named the destination and nothing else, which is the half the reader already knows: the destination is what is missing, and the file holding the link is what has to be edited. On a docs set of any size the only way to act on the message was to grep for the string. The throw site already had the answer. `resolveLink` reads `page.sourceFile` on the line above, to resolve the destination it then rejects, so this is the path relative to the documentation root rather than anything newly threaded through. Under an include it names the included file rather than its host, because `rewriteMarkdownSourceLinks` hands `resolveLink` the innermost origin on its stack. That is the file somebody has to open, and the two differ exactly when the message matters most. Closes #92.
A documentation set with N dead links took N builds to clean up: fix one,
rebuild, learn the next. Each run is a full build, and the count is unknowable
until the last one passes. That is felt hardest on the first build after
adopting the check, when a set that has never been link-checked is checked all
at once.
`resolveLink` now takes an optional collector. With one it records the failure
and returns the destination untouched; without one it throws exactly as
before, which keeps the dev server failing fast - it renders a single page on
request and has no later point to report at.
The build passes a collector, renders every page, and throws once with the
whole list. Nothing changes about what is published: the throw is still inside
`withBuildOutput`, before anything is moved into place, so a build with a dead
link still refuses and still leaves the previous complete output alone.
Repeats are grouped with a count rather than printed as identical rows, since
the authored line number is already gone by the time links are resolved and a
fabricated one would be worse than none:
4 Markdown links could not be resolved:
guide.md ./missing-one.md (no documentation source) (3 times)
other.md ./missing-two.md (no documentation source)
Closes #93.
glennmichael123
changed the base branch from
fix/name-the-document-a-refused-link-is-in
to
main
October 26, 2026 13:55
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.
Closes #92. Closes #93.
Two commits, each reviewable on its own: the first makes a refused link say where it was
written, the second reports all of them instead of the first.
1. Name the document a refused link was authored in
Both link failures in
resolveLinknamed the destination and nothing else, which is thehalf the reader already knows: the destination is what is missing, and the file holding
the link is what has to be edited. On a docs set of any size the only way to act on the
message was to grep for the string.
The throw site already had the answer.
resolveLinkreadspage.sourceFileon the lineabove, to resolve the destination it then rejects:
Relative to the documentation root, because an absolute temporary path is noise in a
build log. Under an include it names the included file rather than its host, because
rewriteMarkdownSourceLinkshandsresolveLinkthe innermost origin on its stack. Thatis the file somebody has to open, and the two differ exactly when the message matters
most, so there is a test for it.
2. Report every refused link, not the first
A documentation set with N dead links took N builds to clean up: fix one, rebuild, learn
the next. Each run is a full build and the count is unknowable until the last one passes.
That is felt hardest on the first build after adopting the check, when a set that has
never been link-checked is checked all at once.
resolveLinknow takes an optional collector. With one it records the failure andreturns the destination untouched; without one it throws exactly as before, which keeps
the dev server failing fast: it renders a single page on request and has no later point
to report at. The build passes a collector, renders every page, and throws once:
Repeats are grouped with a count rather than printed as identical rows. There is no line
number: by the time links are resolved the markdown has already become HTML, so the
authored position is gone, and a fabricated one would be worse than none. The case this
came from was three links to one missing file in a single document.
Nothing changes about what is published
The throw is still inside
withBuildOutput, before anything is moved into place, so abuild with a dead link still refuses and still leaves the previous complete output
untouched. The existing tests covering that behaviour pass unchanged. Returning the
destination untouched during a collecting render is safe for the same reason: that HTML
is never published, and leaving it alone keeps the failing page readable while it is
being looked at.
Tests
Five, in
test/markdown-source-links.test.tsbeside the existing coverage for this area.Each behavioural one was run against the unpatched source first and fails there:
Full suite: 615 pass, 0 fail. Lint unchanged at the 3 pre-existing warnings in
README.mdand
serve.ts, verified identical with and without these changes.tsc --noEmitclean.🤖 Generated with Claude Code