916444 - [Redesign] TOC doesn't work when <h3> without <h2>

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: Design, defect)

Description

[Jean-Yves Perrier [:teoli]]

Attachment: Borked TOC

Some pages have no <h2> but only <h3>.

This is erroneous and we are fixing them little by little, but there are still 100s of them. (Though I expect a lot of these to be fixed by Christmas as the flattening of the JavaScript zone should happen until then).

In this case, the TOC algorithm displays a fake empty 1. in the TOC. This shouldn't happen (and the <h3> should be displayed as 1. 2. 3. 4. )

Comment 1

[Jean-Yves Perrier [:teoli]]

This need to block the beta launch.

Comment 2

[David Walsh :davidwalsh]

Yeah, this is a legacy issue, I believe.  Not sure there's a great way around this.

Comment 3

[Jean-Yves Perrier [:teoli]]

If I could have the list of such pages, we could fix it. We want to fix these pages. Any way to find them?

Comment 4

[Eric Shepherd [:sheppy]]

(In reply to Jean-Yves Perrier [:teoli] from comment #3)
> If I could have the list of such pages, we could fix it. We want to fix
> these pages. Any way to find them?

Hm. I don't think so, but if the devs can think of a way that'd be great.

Comment 5

[Jean-Yves Perrier [:teoli]]

The long term fix here is to fix the pages, but this is blocked by not being able to find them. Also I have no idea how many pages are affected. I guess about 50-60, a lot of them out-of-date. But that's a (slightly educated) guess. No actively maintained page should display this.

A temporary fix gap would be not to display the <h2> in the ToC if empty.

Habber, would this be acceptable? David is this doable without too much work/risk?

Comment 6

[David Walsh :davidwalsh]

This has been an issue for a long time.  It should be fixed by a python expert dev.  I could fix with JavaScript but that's really not ideal.

Comment 7

[Jean-Yves Perrier [:teoli]]

Oh yes, you're right not js here, sorry. Asking groovecoder for the opinion about comment 5.

Comment 8

[Florian Scholz (Open Web Docs)]

(In reply to Jean-Yves Perrier [:teoli] from comment #5)
> The long term fix here is to fix the pages, but this is blocked by not being
> able to find them. Also I have no idea how many pages are affected. I guess
> about 50-60, a lot of them out-of-date. But that's a (slightly educated)
> guess. No actively maintained page should display this.

Unfortunately I came across a lot of more pages, especially in the JavaScript area. I'm currently doing a lot of clean up (about 50+ pages in the last few days), so there is progress, but I expect the number of pages affected to be way bigger :/ Also note that old translated docs will probably have this, too. 

I dug into the TOC code some months ago. For quick reference the SectionTOCFilter lives here: 
https://github.com/mozilla/kuma/blob/master/apps/wiki/content.py#L588

Maybe "level" shouldn't be initialized with "2" but with the highest <hx> level that is found. But this method is quite complicated and I think can't come up with a quick PR without thinking about this a bit longer (plus tests) ;-)

Comment 9

[Luke Crouch [:groovecoder]]

There's a PR in for a find tool that uses refactored ElasticSearch:

https://github.com/mozilla/kuma/pull/1578

Probably be live within a few days.

Comment 12

[sjw]

There is the same problem if you have <h4> in <h2> without a <h3> and so on.

Comment 13

[David Walsh :davidwalsh]

Update from the writers here?  Can we close this?  Headings without structure are a massive a11y / readability issue.

Comment 14

[Eric Shepherd [:sheppy]]

This is no longer a huge issue since we've removed the numbers. The TOC still gets indented oddly, but it doesn't look nearly as bad. I think we can close this.