From 268b794e66f80f308a832b766840f9f3d7eac1e2 Mon Sep 17 00:00:00 2001
From: Sam Ruby <rubys@intertwingly.net>
Date: Sun, 22 Jul 2018 14:13:56 -0700
Subject: [PATCH] tools: flatten apidoc headers

ensure optional parameters are not treated as markedown links by
replacing the children of headers nodes with a single text node
containing the raw markup;

Fixes issue identified in https://github.com/nodejs/node/pull/21490#issuecomment-406859983
---
 tools/doc/html.js | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/tools/doc/html.js b/tools/doc/html.js
index fa7cb7b81bcdec..d759270e0f838d 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -184,9 +184,9 @@ function linkJsTypeDocs(text) {
   return parts.join('`');
 }
 
-// Preprocess stability blockquotes and YAML blocks
+// Preprocess headers, stability blockquotes, and YAML blocks.
 function preprocessElements({ filename }) {
-  return (tree) => {
+  return (tree, file) => {
     const STABILITY_RE = /(.*:)\s*(\d)([\s\S]*)/;
     let headingIndex = -1;
     let heading = null;
@@ -196,6 +196,22 @@ function preprocessElements({ filename }) {
         headingIndex = index;
         heading = node;
 
+        // Ensure optional API parameters are not treated as links by
+        // collapsing all of heading into a single text node.
+        if (heading.children.length > 1) {
+          const position = {
+            start: heading.children[0].position.start,
+            end: heading.position.end
+          };
+
+          heading.children = [{
+            type: 'text',
+            value: file.contents.slice(
+              position.start.offset, position.end.offset),
+            position
+          }];
+        }
+
       } else if (node.type === 'html' && common.isYAMLBlock(node.value)) {
         node.value = parseYAML(node.value);
 
@@ -340,10 +356,9 @@ function buildToc({ filename }) {
 
       depth = node.depth;
       const realFilename = path.basename(realFilenames[0], '.md');
-      const headingText = node.children.map((child) =>
-        file.contents.slice(child.position.start.offset,
-                            child.position.end.offset)
-      ).join('').trim();
+      const headingText = file.contents.slice(
+        node.children[0].position.start.offset,
+        node.position.end.offset).trim();
       const id = getId(`${realFilename}_${headingText}`, idCounters);
 
       const hasStability = node.stability !== undefined;