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
PR-URL: #29946
Reviewed-By: Anna Henningsen <anna@addaleax.net>

Author: Marek Łabuz

Makefile

@@ -746,7 +746,7 @@ $(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
 $(call available-node, $(gen-apilink))
 
 out/doc/api/%.jsonout/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 {
 constassert=require('assert');
 const{ readFile }=require('fs');
 constfixtures=require('../common/fixtures');
+const{ replaceLinks }=require('../../tools/doc/markdown.js');
 consthtml=require('../../tools/doc/html.js');
 constpath=require('path');
 
@@ -22,8 +23,22 @@ const remark2rehype = require('remark-rehype');
 constraw=require('rehype-raw');
 consthtmlStringify=require('rehype-stringify');
 
+// Test links mapper is an object of the following structure:
+// {
+// [filename]: {
+// [link definition identifier]: [url to the linked resource]
+// }
+// }
+consttestLinksMapper={
+'foo': {
+'command line options': 'cli.html#cli-options',
+'web server': 'example.html'
+}
+};
+
 asyncfunctiontoHTML({ input, filename, nodeVersion }){
 constcontent=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>'
+},
 ];
 
 constspaces=/\s/g;

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

tools/doc/generate.js

@@ -29,6 +29,8 @@ const remark2rehype = require('remark-rehype');
 constraw=require('rehype-raw');
 consthtmlStringify=require('rehype-stringify');
 
+const{ replaceLinks }=require('./markdown');
+constlinksMapper=require('./links-mapper');
 consthtml=require('./html');
 constjson=require('./json');
 
@@ -70,6 +72,7 @@ async function main() {
 constinput=awaitfs.readFile(filename,'utf8');
 
 constcontent=awaitunified()
+.use(replaceLinks,{ filename, linksMapper })
 .use(markdown)
 .use(html.preprocessText)
 .use(json.jsonAPI,{ filename })

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"
+ }
+}

tools/doc/markdown.js

@@ -0,0 +1,21 @@
+'use strict';
+
+constvisit=require('unist-util-visit');
+
+module.exports={
+ replaceLinks
+};
+
+functionreplaceLinks({ filename, linksMapper }){
+return(tree)=>{
+constfileHtmlUrls=linksMapper[filename];
+
+visit(tree,'definition',(node)=>{
+consthtmlUrl=fileHtmlUrls&&fileHtmlUrls[node.identifier];
+
+if(htmlUrl&&typeofhtmlUrl==='string'){
+node.url=htmlUrl;
+}
+});
+};
+}