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>

6 files changed, 81 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index d46b4a0c18..21ab5de0b9 100644
--- a/Makefile
+++ b/Makefile
@@ -745,7 +745,7 @@ $(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
 	$(call available-node, $(gen-apilink))
 
 out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
-	tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | $(LINK_DATA)
+	tools/doc/markdown.js tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | $(LINK_DATA)
 	$(call available-node, $(gen-api))
 
 out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \
diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js
index 11b28dc8a2..ee8099f8cd 100644
--- a/test/doctool/test-doctool-html.js
+++ b/test/doctool/test-doctool-html.js
@@ -11,6 +11,7 @@ try {
 const assert = require('assert');
 const { readFile } = require('fs');
 const fixtures = require('../common/fixtures');
+const { replaceLinks } = require('../../tools/doc/markdown.js');
 const html = require('../../tools/doc/html.js');
 const path = require('path');
 
@@ -22,8 +23,22 @@ const remark2rehype = require('remark-rehype');
 const raw = require('rehype-raw');
 const htmlStringify = require('rehype-stringify');
 
+// Test links mapper is an object of the following structure:
+// {
+//   [filename]: {
+//     [link definition identifier]: [url to the linked resource]
+//   }
+// }
+const testLinksMapper = {
+  'foo': {
+    'command line options': 'cli.html#cli-options',
+    'web server': 'example.html'
+  }
+};
+
 async function toHTML({ input, filename, nodeVersion }) {
   const content = unified()
+    .use(replaceLinks, { filename, linksMapper: testLinksMapper })
     .use(markdown)
     .use(html.firstHeader)
     .use(html.preprocessText)
@@ -96,6 +111,21 @@ const testData = [
     file: fixtures.path('altdocs.md'),
     html: '<li><a href="https://nodejs.org/docs/latest-v8.x/api/foo.html">8.x',
   },
+  {
+    file: fixtures.path('document_with_links.md'),
+    html: '<h1>Usage and Example<span><a class="mark"' +
+    'href="#foo_usage_and_example" id="foo_usage_and_example">#</a>' +
+    '</span></h1><h2>Usage<span><a class="mark" href="#foo_usage"' +
+    'id="foo_usage">#</a></span></h2><p><code>node \\[options\\] index.js' +
+    '</code></p><p>Please see the<a href="cli.html#cli-options">' +
+    'Command Line Options</a>document for more information.</p><h2>' +
+    'Example<span><a class="mark" href="#foo_example" id="foo_example">' +
+    '#</a></span></h2><p>An example of a<a href="example.html">' +
+    'webserver</a>written with Node.js which responds with<code>' +
+    '\'Hello, World!\'</code>:</p><h2>See also<span><a class="mark"' +
+    'href="#foo_see_also" id="foo_see_also">#</a></span></h2><p>Check' +
+    'out also<a href="https://nodejs.org/">this guide</a></p>'
+  },
 ];
 
 const spaces = /\s/g;
diff --git a/test/fixtures/document_with_links.md b/test/fixtures/document_with_links.md
new file mode 100644
index 0000000000..1392029a30
--- /dev/null
+++ b/test/fixtures/document_with_links.md
@@ -0,0 +1,20 @@
+# Usage and Example
+
+## Usage
+
+`node \[options\] index.js`
+
+Please see the [Command Line Options][] document for more information.
+
+## Example
+
+An example of a [web server][] written with Node.js which responds with
+`'Hello, World!'`:
+
+## See also
+
+Check out also [this guide][]
+
+[Command Line Options]: cli.md#options
+[this guide]: https://nodejs.org/
+[web server]: example.md
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;
+      }
+    });
+  };
+}