tools: add unified plugin changing links for html docs

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: https://github.com/nodejs/node/issues/28689

PR-URL: https://github.com/nodejs/node/pull/29946
Reviewed-By: Anna Henningsen <anna@addaleax.net>

3 files changed, 30 insertions, 0 deletions

diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index cd85d53657..aac8bfd5e7 100644
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -29,6 +29,8 @@ const remark2rehype = require('remark-rehype');
 const raw = require('rehype-raw');
 const htmlStringify = require('rehype-stringify');
 
+const { replaceLinks } = require('./markdown');
+const linksMapper = require('./links-mapper');
 const html = require('./html');
 const json = require('./json');
 
@@ -70,6 +72,7 @@ async function main() {
   const input = await fs.readFile(filename, 'utf8');
 
   const content = await unified()
+    .use(replaceLinks, { filename, linksMapper })
     .use(markdown)
     .use(html.preprocessText)
     .use(json.jsonAPI, { filename })
diff --git a/tools/doc/links-mapper.json b/tools/doc/links-mapper.json
new file mode 100644
index 0000000000..158d72c7fe
--- /dev/null
+++ b/tools/doc/links-mapper.json
@@ -0,0 +1,6 @@
+{
+  "doc/api/synopsis.md": {
+    "command line options": "cli.html#cli_command_line_options",
+    "web server": "http.html"
+  }
+}
\ No newline at end of file
diff --git a/tools/doc/markdown.js b/tools/doc/markdown.js
new file mode 100644
index 0000000000..97feadbf99
--- /dev/null
+++ b/tools/doc/markdown.js
@@ -0,0 +1,21 @@
+'use strict';
+
+const visit = require('unist-util-visit');
+
+module.exports = {
+  replaceLinks
+};
+
+function replaceLinks({ filename, linksMapper }) {
+  return (tree) => {
+    const fileHtmlUrls = linksMapper[filename];
+
+    visit(tree, 'definition', (node) => {
+      const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];
+
+      if (htmlUrl && typeof htmlUrl === 'string') {
+        node.url = htmlUrl;
+      }
+    });
+  };
+}