doc,tools: checkLinks.js does not cover api

[DerekNonGeneric]

This should be tested when building the HTML, but apparently it only tests links internal to all.html page:

node/tools/doc/allhtml.js

Lines 85 to 88 in 9d12c14

	const hrefRe = / href="#(\w+)"/g;
	while (match = hrefRe.exec(all)) {
	if (!ids.has(match[1])) throw new Error(`link not found: ${match[1]}`);
	}

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

	apicontent += data.slice(match.index + match[0].length)
	.replace(/<!-- API END -->[\s\S]*/, '')
	.replace(/<a href="(\w[^#"]*)#/g, (match, href) => {
	return htmlFiles.includes(href) ? '<a href="#' : match;
	})
	.trim() + '\n';

But in this case, because modules_module.html doesn't exist, it's treated as an external page and the broken links slip through the test…

I haven't dug into why but it looks like the api docs are deliberately excluded

Yes indeed. The reason checkLinks.js does not cover api is because we are using .html extension to reference other doc pages, while checkLinks.js would expect .md. One way of fixing it would be to use .md extensions 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. Another way would be to tweak the current test to make sure this doesn't reproduce.

Originally posted by @aduh95 in #35182 (comment)

[DerekNonGeneric]

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 .md extensions 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.).

/cc @Trott @GeoffreyBooth @aduh95 @richardlau

[aduh95]

I have a fix for that in #35191, it just needs #35182 to land first. The most difficult part of it will be not to get drown in all the merge conflicts, as this touches every single files in doc/api.