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: #28689

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 \

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');
 
@@ -24,6 +25,7 @@ const htmlStringify = require('rehype-stringify');
 
 async function toHTML({ input, filename, nodeVersion }) {
   const content = unified()
+    .use(replaceLinks)
     .use(markdown)
     .use(html.firstHeader)
     .use(html.preprocessText)
@@ -96,6 +98,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;

test/fixtures/document_with_links.md

@@ -0,0 +1,23 @@
+# 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
+
+[Command Line Options `.html`]: cli.html#cli-options
+[web server `.html`]: example.html

tools/doc/generate.js

@@ -29,6 +29,7 @@ const remark2rehype = require('remark-rehype');
 const raw = require('rehype-raw');
 const htmlStringify = require('rehype-stringify');
 
+const { replaceLinks } = require('./markdown');
 const html = require('./html');
 const json = require('./json');
 
@@ -70,6 +71,7 @@ async function main() {
   const input = await fs.readFile(filename, 'utf8');
 
   const content = await unified()
+    .use(replaceLinks)
     .use(markdown)
     .use(html.preprocessText)
     .use(json.jsonAPI, { filename })

tools/doc/markdown.js

@@ -0,0 +1,43 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+'use strict';
+
+const visit = require('unist-util-visit');
+
+module.exports = {
+  replaceLinks
+};
+
+function replaceLinks() {
+  return (tree) => {
+    const linksIdenfitiers = tree.children
+      .filter((child) => child.type === 'definition')
+      .map((child) => child.identifier);
+
+    visit(tree, 'linkReference', (node) => {
+      const htmlLinkIdentifier = `${node.identifier} \`.html\``;
+      if (linksIdenfitiers.includes(htmlLinkIdentifier)) {
+        node.identifier = htmlLinkIdentifier;
+      }
+    });
+  };
+}