doc: add links to alternative versions of doc

Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: https://github.com/nodejs/node/pull/10958
Fixes: https://github.com/nodejs/node/issues/10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

tools/doc/html.js

@@ -31,6 +31,7 @@ const typeParser = require('./type-parser.js');
 module.exports = toHTML;
 
 const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
+const DOC_CREATED_REG_EXP = /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.([0-9]+)\s*-->/;
 
 // customized heading without id attribute
 const renderer = new marked.Renderer();
@@ -52,13 +53,17 @@ const gtocPath = path.resolve(path.join(
 ));
 var gtocLoading = null;
 var gtocData = null;
+var docCreated = null;
+var nodeVersion = null;
 
 /**
  * opts: input, filename, template, nodeVersion.
  */
 function toHTML(opts, cb) {
   const template = opts.template;
-  const nodeVersion = opts.nodeVersion || process.version;
+
+  nodeVersion = opts.nodeVersion || process.version;
+  docCreated = opts.input.match(DOC_CREATED_REG_EXP);
 
   if (gtocData) {
     return onGtocLoaded();
@@ -157,6 +162,8 @@ function render(opts, cb) {
       );
     }
 
+    template = template.replace(/__ALTDOCS__/, altDocs(filename));
+
     // content has to be the last thing we do with
     // the lexed tokens, because it's destructive.
     const content = marked.parser(lexed);
@@ -188,6 +195,50 @@ function replaceInText(text) {
   return linkJsTypeDocs(linkManPages(text));
 }
 
+function altDocs(filename) {
+  let html = '';
+
+  if (!docCreated) {
+    console.error(`Failed to add alternative version links to ${filename}`);
+    return html;
+  }
+
+  function lte(v) {
+    const ns = v.num.split('.');
+    if (docCreated[1] > +ns[0])
+      return false;
+    if (docCreated[1] < +ns[0])
+      return true;
+    return docCreated[2] <= +ns[1];
+  }
+
+  const versions = [
+    { num: '8.x' },
+    { num: '7.x' },
+    { num: '6.x', lts: true },
+    { num: '5.x' },
+    { num: '4.x', lts: true },
+    { num: '0.12.x' },
+    { num: '0.10.x' }
+  ];
+
+  const host = 'https://nodejs.org';
+  const href = (v) => `${host}/docs/latest-v${v.num}/api/${filename}.html`;
+
+  function li(v, i) {
+    let html = `<li><a href="${href(v)}">${v.num}`;
+
+    if (v.lts)
+      html += ' <b>LTS</b>';
+
+    return html + '</a></li>';
+  }
+
+  const lis = (vs) => vs.filter(lte).map(li).join('\n');
+
+  return `<ol class="version-picker">${lis(versions)}</ol>`;
+}
+
 // handle general body-text replacements
 // for example, link man page references to the actual page
 function parseText(lexed) {