diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js
index f052990055e224..ee8099f8cd8728 100644
--- a/test/doctool/test-doctool-html.js
+++ b/test/doctool/test-doctool-html.js
@@ -23,9 +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)
+    .use(replaceLinks, { filename, linksMapper: testLinksMapper })
     .use(markdown)
     .use(html.firstHeader)
     .use(html.preprocessText)
@@ -103,7 +116,7 @@ const testData = [
     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' +
+    '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">' +
diff --git a/test/fixtures/document_with_links.md b/test/fixtures/document_with_links.md
index 6d40d11a24b1a7..1392029a30ba6a 100644
--- a/test/fixtures/document_with_links.md
+++ b/test/fixtures/document_with_links.md
@@ -18,6 +18,3 @@ 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
diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index 468775c623bc12..aac8bfd5e7ba21 100644
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -30,6 +30,7 @@ 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');
 
@@ -71,7 +72,7 @@ async function main() {
   const input = await fs.readFile(filename, 'utf8');
 
   const content = await unified()
-    .use(replaceLinks)
+    .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 00000000000000..158d72c7fe5822
--- /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
index 3dbceab40e38dc..97feadbf9990bb 100644
--- a/tools/doc/markdown.js
+++ b/tools/doc/markdown.js
@@ -6,16 +6,15 @@ module.exports = {
   replaceLinks
 };
 
-function replaceLinks() {
+function replaceLinks({ filename, linksMapper }) {
   return (tree) => {
-    const linksIdenfitiers = tree.children
-      .filter((child) => child.type === 'definition')
-      .map((child) => child.identifier);
+    const fileHtmlUrls = linksMapper[filename];
 
-    visit(tree, 'linkReference', (node) => {
-      const htmlLinkIdentifier = `${node.identifier} \`.html\``;
-      if (linksIdenfitiers.includes(htmlLinkIdentifier)) {
-        node.identifier = htmlLinkIdentifier;
+    visit(tree, 'definition', (node) => {
+      const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];
+
+      if (htmlUrl && typeof htmlUrl === 'string') {
+        node.url = htmlUrl;
       }
     });
   };