Repository navigation
doc,tools: checkLinks.js does not cover api #35189
Description
Activity
Opened this issue using @aduh95's preliminary findings as seed. I'd like for it to track progress on the unreliability of the link checker and discuss the intended fix as a potential feature request.
One way of fixing it would be to use
.mdextensions in the Markdown files, and use checkLinks.js to test said links – it would also improve the experience of navigating the docs through GitHub web UI.For those who haven't been following previous discussions regarding expectations we have about the docs, it's pretty clear that the fix described in the above quote should be the one pursued. For context, here is one excerpt supporting this notion.
One downside to this approach is that it further degrades the experience of browsing the markdown files on GitHub. Not necessarily a deal-breaker, but the upside should outweigh the downside.
— #32916 (comment)I was not previously aware of the Markdown documents' links not functioning on GitHub.com, but that should probably be pretty high on the list of feature requests. From what I've observed elsewhere, it's highly desirable since a lot of docs PRs are made using the GitHub UI (esp. for small typos), so being able to navigate the docs this way is seen as being of high value.
I'm a bit crunched for time this week, but it would be great to get some idea of how difficult this would be to accomplish. Aside from simply changing the file name extensions and associated links, I'd be interested in knowing if there's anything else to be aware of (any hard-coded file extensions used in the Makefile, doctool JS source, etc.).
- added 3 commits that reference this issue
on Oct 1, 2020 - added 3 commits that reference this issue
on Oct 6, 2020 - added 3 commits that reference this issue
on Jan 8, 2021
This should be tested when building the HTML, but apparently it only tests links internal to
all.htmlpage:node/tools/doc/allhtml.js
Lines 85 to 88 in 9d12c14
Usually that would cover all links internal to the docs, as all links to doc pages are stripped from the filename to keep only the hash part:
node/tools/doc/allhtml.js
Lines 39 to 45 in 9d12c14
But in this case, because
modules_module.htmldoesn't exist, it's treated as an external page and the broken links slip through the test…Yes indeed. The reason
checkLinks.jsdoes not coverapiis because we are using.htmlextension to reference other doc pages, whilecheckLinks.jswould expect.md. One way of fixing it would be to use.mdextensions in the Markdown files, and usecheckLinks.jsto test said links – it would also improve the experience of navigating the docs through GitHub web UI. Another way would be to tweak the current test to make sure this doesn't reproduce.Originally posted by @aduh95 in #35182 (comment)