tools: add unified plugin changing links for html docs

[MarekLabuz]

This commit introduces additional stage in the process of generating
html docs from markdown files. Plugin transforms links to *.md files
in the respository to links to *.html files in the online documentation.

Fixes: #28689

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[Trott]

Unless the test itself is substantially copied from another file with this copyright boilerplate, the copyright boilerplate should be omitted from new files.

[Trott]

Welcome @MarekLabuz and thanks for the pull request!

[Trott]

@nodejs/documentation On the one hand, this will resolve the issue linked near the top. On the other hand, the whole requiring-bottom-references-that-are-unused-in-the-markdown file will be flagged by our lint rules as they currently stand and it's a bit non-intuitive.

At the moment, I'm feeling kind of -0 on it, maybe -0.5. I'd prefer something less obtrusive, more "just works". But I'm not sure we can realistically get there. I'm not concerned about broken links in the markdown-rendered docs. It would be nice if they weren't broken, but probably greater than 99% of our users read the HTML docs, not the rendered markdown in the GitHub interface or whatever.

I do appreciate the effort here and I'd like to see if there's a way to improve it a bit to something I'd be more +1 on.

[MarekLabuz]

Alright, I get it, thank you for your feedback. There is also a possibility to move these references to a separate file e.g.

{
  "synopsis": {
    "Command Line Options": "cli.html#cli_command_line_options",
    "web server": "http.html"
  }
}

However, I wonder whether it will be worth to maintain it since, as you said, the vast majority of users don't use it.

[Trott]

I think the problem here is pretty small and probably not worth any added complexity to our setup to solve, but others might feel differently. Anyone?

[Trott]

@nodejs/collaborators This could use some reviews.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/26387/

[rvagg]

needs a rebase I think https://ci.nodejs.org/job/node-test-commit/32422/console

I recall lots of "unified" errors in the without-ssl tests in earlier release lines, worth confirming that this passes that hurdle.

[Trott]

The rebase here seems to have gotten a bit confusing. I think I cleaned it up correctly, but please check.

[MarekLabuz]

Yes, I think it is correct, thank you.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/26455/

[rvagg]

withoutssl passed, that's all I cared about 👍

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/26461/

[addaleax]

Landed in 62c61b7, thanks for the PR and sorry it took a while for somebody to get around to merging it!