tools,doc: allow page titles to contain inline code

Previously the HTML title would be cut to the first text node only.

PR-URL: #35003
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>

test/doctool/test-doctool-html.js

@@ -9,7 +9,7 @@ try {
 }
 
 const assert = require('assert');
-const { readFile } = require('fs');
+const { readFileSync } = require('fs');
 const fixtures = require('../common/fixtures');
 const { replaceLinks } = require('../../tools/doc/markdown.js');
 const html = require('../../tools/doc/html.js');
@@ -58,11 +58,6 @@ function toHTML({ input, filename, nodeVersion, versions }) {
 // This HTML will be stripped of all whitespace because we don't currently
 // have an HTML parser.
 const testData = [
-  {
-    file: fixtures.path('sample_document.md'),
-    html: '<ol><li>fish</li><li>fish</li></ol>' +
-      '<ul><li>Redfish</li><li>Bluefish</li></ul>'
-  },
   {
     file: fixtures.path('order_of_end_tags_5873.md'),
     html: '<h3>ClassMethod: Buffer.from(array) <span> ' +
@@ -126,6 +121,10 @@ const testData = [
     'href="#foo_see_also" id="foo_see_also">#</a></span></h2><p>Check' +
     'out also<a href="https://nodejs.org/">this guide</a></p>'
   },
+  {
+    file: fixtures.path('document_with_special_heading.md'),
+    html: '<title>Sample markdown with special heading |',
+  }
 ];
 
 const spaces = /\s/g;
@@ -144,17 +143,16 @@ testData.forEach(({ file, html }) => {
   // Normalize expected data by stripping whitespace.
   const expected = html.replace(spaces, '');
 
-  readFile(file, 'utf8', common.mustCall(async (err, input) => {
-    assert.ifError(err);
-    const output = toHTML({ input: input,
-                            filename: 'foo',
-                            nodeVersion: process.version,
-                            versions: versions });
+  const input = readFileSync(file, 'utf8');
+
+  const output = toHTML({ input,
+                          filename: 'foo',
+                          nodeVersion: process.version,
+                          versions });
 
-    const actual = output.replace(spaces, '');
-    // Assert that the input stripped of all whitespace contains the
-    // expected markup.
-    assert(actual.includes(expected),
-           `ACTUAL: ${actual}\nEXPECTED: ${expected}`);
-  }));
+  const actual = output.replace(spaces, '');
+  // Assert that the input stripped of all whitespace contains the
+  // expected markup.
+  assert(actual.includes(expected),
+         `ACTUAL: ${actual}\nEXPECTED: ${expected}`);
 });

test/fixtures/document_with_special_heading.md

@@ -0,0 +1,4 @@
+# Sample `markdown` with _special_ **heading**
+
+Sometimes heading contains more than just one text child, the current file is
+there to test just that. 

tools/doc/html.js

@@ -93,12 +93,14 @@ function toHTML({ input, content, filename, nodeVersion, versions }) {
 // Set the section name based on the first header.  Default to 'Index'.
 function firstHeader() {
   return (tree, file) => {
-    file.section = 'Index';
-
     const heading = find(tree, { type: 'heading' });
-    if (heading) {
-      const text = find(heading, { type: 'text' });
-      if (text) file.section = text.value;
+
+    if (heading && heading.children.length) {
+      const recursiveTextContent = (node) =>
+        node.value || node.children.map(recursiveTextContent).join('');
+      file.section = recursiveTextContent(heading);
+    } else {
+      file.section = 'Index';
     }
   };
 }