Skip to content

doc,tools: checkLinks.js does not cover api #35189

Closed
@DerekNonGeneric

Description

@DerekNonGeneric

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

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:

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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    buildIssues and PRs related to build files or the CI.discussIssues opened for discussions and feedbacks.docIssues and PRs related to the documentations.toolsIssues and PRs related to the tools directory.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions