doc,tools: use only one level 1 header per page

Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: https://github.com/nodejs/node/pull/37839
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Pooja D P <Pooja.D.P@ibm.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

1 files changed, 13 insertions, 4 deletions

diff --git a/tools/doc/html.js b/tools/doc/html.js
index 67157ba6b5f..9089ce7e443 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -66,10 +66,19 @@ const gtocHTML = unified()
 const templatePath = path.join(docPath, 'template.html');
 const template = fs.readFileSync(templatePath, 'utf8');
 
-function wrapSections(content) {
+function processContent(content) {
+  content = content.toString();
+  // Increment header tag levels to avoid multiple h1 tags in a doc.
+  // This means we can't already have an <h6>.
+  if (content.includes('<h6>')) {
+    throw new Error('Cannot increment a level 6 header');
+  }
+  // `++level` to convert the string to a number and increment it.
+  content = content.replace(/(?<=<\/?h)[1-5](?=[^<>]*>)/g, (level) => ++level);
+  // Wrap h3 tags in section tags.
   let firstTime = true;
-  return content.toString()
-    .replace(/<h2/g, (heading) => {
+  return content
+    .replace(/<h3/g, (heading) => {
       if (firstTime) {
         firstTime = false;
         return '<section>' + heading;
@@ -91,7 +100,7 @@ function toHTML({ input, content, filename, nodeVersion, versions }) {
                      .replace('__GTOC__', gtocHTML.replace(
                        `class="nav-${id}"`, `class="nav-${id} active"`))
                      .replace('__EDIT_ON_GITHUB__', editOnGitHub(filename))
-                     .replace('__CONTENT__', wrapSections(content));
+                     .replace('__CONTENT__', processContent(content));
 
   const docCreated = input.match(
     /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.[0-9]+\s*-->/);