fix(document-extractor): split h4 sections

build/document-extractor.ts

@@ -59,6 +59,7 @@ export function extractSections($: cheerio.CheerioAPI): [Section[], string[]] {
   const iterable = [...(body.childNodes as cheerio.Element[])];
 
   let c = 0;
+
   iterable.forEach((child) => {
     if (
       (child as cheerio.Element).tagName === "h2" ||
@@ -303,11 +304,11 @@ function addSections($: cheerio.Cheerio<cheerio.Element>): SectionsAndFlaws {
     const specialSections = _addSingleSpecialSection($);
 
     // The _addSingleSpecialSection() function will have sucked up the <h2> or <h3>
-    // and the `div.bc-data` or `div.bc-specs` to turn it into a special section.
+    // or <h4> and the `div.bc-data` or `div.bc-specs` to turn it into a special section.
     // First remove that, then put whatever HTML is left as a prose
     // section underneath.
-    $.find("div.bc-data, h2, h3").remove();
-    $.find("div.bc-specs, h2, h3").remove();
+    $.find("div.bc-data, h2, h3, h4").remove();
+    $.find("div.bc-specs, h2, h3, h4").remove();
     const [proseSections, proseFlaws] = _addSectionProse($);
     specialSections.push(...proseSections);
     flaws.push(...proseFlaws);
@@ -330,18 +331,23 @@ function _addSingleSpecialSection(
   let id: string | null = null;
   let title: string | null = null;
   let isH3 = false;
+  let isH4 = false;
 
   const h2s = $.find("h2");
+  const h3s = $.find("h3");
   if (h2s.length === 1) {
     id = h2s.attr("id");
     title = h2s.text();
+  } else if (h3s.length === 1) {
+    id = h3s.attr("id");
+    title = h3s.text();
+    isH3 = true;
   } else {
-    const h3s = $.find("h3");
-    if (h3s.length === 1) {
-      id = h3s.attr("id");
-      title = h3s.text();
-      isH3 = true;
-    }
+    // Look for <h4>s
+    const h4s = $.find("h4");
+    id = h4s.attr("id");
+    title = h4s.text();
+    isH4 = true;
   }
 
   let dataQuery: string = "";
@@ -381,6 +387,7 @@ function _addSingleSpecialSection(
             title,
             id,
             isH3,
+            isH4,
             data: null,
             query,
             browsers: null,
@@ -398,6 +405,7 @@ function _addSingleSpecialSection(
             title,
             id,
             isH3,
+            isH4,
             query,
             specifications: [],
           },
@@ -486,6 +494,7 @@ function _addSingleSpecialSection(
           title,
           id,
           isH3,
+          isH4,
           data,
           query,
           browsers,
@@ -666,6 +675,7 @@ function _addSingleSpecialSection(
           title,
           id,
           isH3,
+          isH4,
           specifications,
           query,
         },
@@ -681,13 +691,16 @@ function _addSectionProse(
   let title: string | null = null;
   let titleAsText: string = "";
   let isH3 = false;
+  let isH4 = false;
 
   const flaws: string[] = [];
 
   // The way this works...
   // Given a section of HTML, try to extract a id, title,
 
   let h2found = false;
+  let h3found = false;
+
   const h2s = $.find("h2");
   h2s.each((i) => {
     const h2 = h2s.eq(i);
@@ -730,9 +743,33 @@ function _addSectionProse(
           h3.remove();
         }
       }
+      h3found = true;
     });
   }
 
+  // TODO: h4 elements are not being linkified and the
+  // tests are just picking up the initial text instead of the <a> tag
+  // const h4s = $.find("h4");
+  // h4s.each((i) => {
+  //   const h4 = h4s.eq(i);
+  //   if (i) {
+  //     // Excess!
+  //     flaws.push(
+  //       `Excess <h4> tag that is NOT at root-level (id='${h4.attr(
+  //         "id"
+  //       )}', text='${h4.text()}')`
+  //     );
+  //   } else {
+  //     id = h4.attr("id") ?? "";
+  //     title = h4.html() ?? "";
+  //     titleAsText = h4.text();
+  //     if (id && title) {
+  //       isH4 = true;
+  //       h4.remove();
+  //     }
+  //   }
+  // });
+
   if (id) {
     // Remove trailing underscores (https://github.com/mdn/yari/issues/5492).
     id = id.replace(/_+$/g, "");
@@ -742,6 +779,7 @@ function _addSectionProse(
     id,
     title,
     isH3,
+    isH4,
     content: $.html()?.trim(),
   };
 

build/index.ts

@@ -253,7 +253,8 @@ function makeTOC(doc) {
           section.type === "specifications") &&
         section.value.id &&
         section.value.title &&
-        !section.value.isH3
+        !section.value.isH3 &&
+        !section.value.isH4
       ) {
         return { text: section.value.title, id: section.value.id };
       }

client/src/document/ingredients/prose.tsx

@@ -1,4 +1,4 @@
-import { DisplayH2, DisplayH3 } from "./utils";
+import { DisplayHeading } from "./utils";
 
 export function Prose({ section }: { section: any }) {
   const { id } = section;
@@ -14,11 +14,10 @@ export function Prose({ section }: { section: any }) {
     return <Content />;
   }
 
-  const DisplayHx = section.isH3 ? DisplayH3 : DisplayH2;
-
   return (
     <section aria-labelledby={id}>
-      <DisplayHx
+      <DisplayHeading
+        level={section.isH4 ? 4 : section.isH3 ? 3 : 2}
         id={id}
         title={section.title}
         titleAsText={section.titleAsText}

client/src/document/ingredients/spec-section.tsx

@@ -1,16 +1,18 @@
-import { DisplayH2, DisplayH3 } from "./utils";
+import { DisplayHeading } from "./utils";
 import NoteCard from "../../ui/molecules/notecards";
 
 export function SpecificationSection({
   id,
   title,
   isH3,
+  isH4,
   specifications,
   query,
 }: {
   id: string;
   title: string;
   isH3: boolean;
+  isH4: boolean;
   specifications: Array<{
     title: string;
     bcdSpecificationURL: string;
@@ -19,8 +21,7 @@ export function SpecificationSection({
 }) {
   return (
     <>
-      {title && !isH3 && <DisplayH2 id={id} title={title} />}
-      {title && isH3 && <DisplayH3 id={id} title={title} />}
+      {<DisplayHeading level={isH4 ? 4 : isH3 ? 3 : 2} id={id} title={title} />}
 
       {specifications.length > 0 ? (
         <table className="standard-table">

client/src/document/ingredients/utils.tsx

@@ -1,32 +1,19 @@
-export function DisplayH2({
+export function DisplayHeading({
+  level,
   id,
   title,
   titleAsText,
 }: {
+  level: number;
   id: string;
   title: string;
   titleAsText?: string;
 }) {
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
   return (
-    <h2 id={id.toLowerCase()}>
-      <Permalink title={title} titleAsText={titleAsText} id={id} />
-    </h2>
-  );
-}
-
-export function DisplayH3({
-  id,
-  title,
-  titleAsText,
-}: {
-  id: string;
-  title: string;
-  titleAsText?: string;
-}) {
-  return (
-    <h3 id={id.toLowerCase()}>
-      <Permalink title={title} titleAsText={titleAsText} id={id} />
-    </h3>
+    <Tag id={id.toLowerCase()}>
+      <Permalink id={id} title={title} titleAsText={titleAsText} />
+    </Tag>
   );
 }
 

client/src/document/lazy-bcd-table.tsx

@@ -1,7 +1,7 @@
 import React, { lazy, Suspense, useEffect, useState } from "react";
 import useSWR from "swr";
 
-import { DisplayH2, DisplayH3 } from "./ingredients/utils";
+import { DisplayHeading } from "./ingredients/utils";
 import { Loading } from "../ui/atoms/loading";
 // Because it's bad for web performance to lazy-load CSS during the initial render
 // (because the page is saying "Wait! Stop rendering, now that I've downloaded
@@ -25,19 +25,21 @@ export function LazyBrowserCompatibilityTable({
   id,
   title,
   isH3,
+  isH4,
   query,
   dataURL,
 }: {
   id: string;
   title: string;
   isH3: boolean;
+  isH4: boolean;
   query: string;
   dataURL: string | null;
 }) {
   return (
     <>
-      {title && !isH3 && <DisplayH2 id={id} title={title} />}
-      {title && isH3 && <DisplayH3 id={id} title={title} />}
+      {<DisplayHeading level={isH4 ? 4 : isH3 ? 3 : 2} id={id} title={title} />}
+
       {dataURL ? (
         <LazyBrowserCompatibilityTableInner dataURL={dataURL} />
       ) : (

libs/types/document.ts

@@ -165,6 +165,7 @@ export interface ProseSection {
     id: string | null;
     title: string | null;
     isH3: boolean;
+    isH4: boolean;
     content?: string;
     titleAsText?: string;
   };
@@ -175,6 +176,7 @@ export interface SpecificationsSection {
     id: string;
     title: string;
     isH3: boolean;
+    isH4: boolean;
     query: string;
     specifications: {
       bcdSpecificationURL: any;
@@ -189,6 +191,7 @@ export interface BCDSection {
     id: string;
     title: string;
     isH3: boolean;
+    isH4: boolean;
     data?: BCD.Identifier | null;
     dataURL?: string;
     query: string;

testing/content/files/en-us/web/split_section_by_heading/index.html

@@ -0,0 +1,14 @@
+---
+title: Split section by heading
+slug: Web/Split_section_by_heading
+---
+
+<p>This page contains a few h2, h3 and h4 tags at root-level that will be direct linkified.</p>
+
+
+<h2>Some heading</h2>
+<h4>Foo buzz</h4>
+<h4 id="foo">Foo bar</h4>
+<h3>Another heading</h3>
+<div><p>stuff</p></div>
+<h4>Final heading</h4>

testing/tests/index.test.ts

@@ -1767,6 +1767,46 @@ test("notecards are correctly transformed by the formatNotecards utility", () =>
   );
 });
 
+test("sections should be split by h2, h3 or h4", () => {
+  const builtFolder = path.join(
+    buildRoot,
+    "en-us",
+    "docs",
+    "web",
+    "split_section_by_heading"
+  );
+
+  const jsonFile = path.join(builtFolder, "index.json");
+  const { doc } = JSON.parse(fs.readFileSync(jsonFile, "utf-8"));
+  expect(doc.flaws.length).toBeFalsy();
+  expect(doc.title).toBe("Split section by heading");
+
+  const htmlFile = path.join(builtFolder, "index.html");
+  const html = fs.readFileSync(htmlFile, "utf-8");
+  const $ = cheerio.load(html);
+
+  const h2 = $("h2#some_heading");
+  expect(h2.text()).toBe("Some heading");
+  expect(h2.attr("id")).toBe("some_heading");
+  expect(h2.html()).toBe(
+    '<a href="#some_heading" title="Permalink to Some heading">Some heading</a>'
+  );
+
+  const h3 = $("h3#another_heading");
+  expect(h3.text()).toBe("Another heading");
+  expect(h3.attr("id")).toBe("another_heading");
+  expect(h3.html()).toBe(
+    '<a href="#another_heading" title="Permalink to Another heading">Another heading</a>'
+  );
+
+  const h4 = $("h4#final_heading");
+  expect(h4.text()).toBe("Final heading");
+  expect(h4.attr("id")).toBe("final_heading");
+  expect(h4.html()).toBe(
+    '<a href="#final_heading" title="Permalink to Final heading">Final heading</a>'
+  );
+});
+
 test("homepage links and flaws", () => {
   const builtFolder = path.join(
     buildRoot,