Sub headings not getting direct linkified

I noticed these two <h2> tags aren’t being highlighted and turned into a direct link like they should be. This is happening on the Using CSS Variables page.

[peterbe]

What’s happening here is that we have HTML looks like this:

<p>intro bla bla</p>

<h2>Basic usage</p>
<p>blabla</p>

<h2>First steps with custom properties</h2>
<div id="sample1">
  <p>blabla</p>
  <h2>Inheritance of custom properties</h2>
</div>

What the builder does is that it first breaks it up into sections by looping over the “root level” elements. The first and section section is:

<p>intro bla bla</p>

and

<h2>Basic usage</p>
<p>blabla</p>

But for the next section, yes it starts with a lovely <h2> but here’s more than one within

<h2>First steps with custom properties</h2>
<div id="sample1">
  <p>blabla</p>
  <h2>Inheritance of custom properties</h2>
</div>

So it dares not to extract split it by <h2>. In fact, to extract the title, it uses:

const h2s = $.find("h2");
if (h2s.length === 1) {
    id = h2s.attr("id");
    title = h2s.html();
    titleAsText = h2s.text();
    h2s.remove();
}

But what happens here on this page is that h2s.length === 2 so it can’t confidently proceed.

The solution is two-fold. First, we need to correct the HTML. That second <h2>Inheritance of custom properties</h2> should be moved and appear outside the <div id="sample1"> so it’s at the root level instead. Secondly, because there’s a lot of pages that are like this. We can do a little bit better. So we can change the id and title extraction to:

const h2s = $.find("h2");
if (h2s.length >= 1) {
    id = h2s.attr("id"); 
    title = h2s.html();
    titleAsText = h2s.text();
    h2s.eq(0).remove();  // only remove the first one
}

That, and log it as a flaw (not fixable) where a writer has to go in and move the <h2> to the root level.

[peterbe]

So what’s probably happening is that some invalid HTML gets forgiven by cheerio and when serialized back to a HTML string, it adds that <div> lets see what’s going on.