Request for support of H3 in the page TOC

[dipikabh]

Hello everyone,

This is a request for adding H3 headings to the page TOC on the right.
(I've used H2 and H3 here for visual clarity but they do refer to the markdown equivalents ## and ###, respectively, that we use in writing now.)

Let us know if you see any major roadblocks in implementing this or if we have missed any possible issues that we should keep in mind.

In this discussion

• Current scenario and requirement
• Possible problems
  • Engineering/Design-related
  • Content-related
• Appendix

Current scenario and requirement

Currently, the page TOC on the right shows only the H2 headings. From what I understand, it was done this way when the page real-estate was limited and the page TOC was being stacked over the left sidebar. Now that the page TOC has its own, dedicated right column, it would be nice to use it more.
There is a consensus among the MDN and OWD writing folks that the page TOC on the right side should also expose the H3 headings.

The main reasons for requesting this change (if anybody needs more convincing 🙂) are:

• Page TOC is a nice place to instantly scan whether or not something is covered on the page.
• Some important concepts/topics that are H3 are currently hidden away from the page TOC, especially in articles that are long (as shown in the screenshot below).
• On the flip side, as @schalkneethling pointed out, there might be an overuse of H2s because of the need for a heading to show up in the page TOC since we only expose H2s at the moment.
• The H2 "Examples" section in the Reference pages sometimes has one or more H3 subsections with descriptive titles and it would be nice to have a direct link to specific H3 examples from the page TOC itself.

---

Possible problems

We do foresee some problem scenarios when this is implemented:

Engineering/Design-related

• If H3s are made available in the page TOC, the TOC on some pages might run too long on pages that have many subheadings. This could be handled via design decisions during implementation or by fixing the content structure on the page or by a mix of both in some cases. (See Appendix at the end).
  • @caugner had a few suggestions to handle this:
    • Always show TOC entries for h2s.
    • Make those collapsible that have h3s below them.
    • Always expand the current h2, and collapse others.
• The aside block at the bottom of the page (as shown below) has the "Found a problem with this page?" heading in H3 and we do not want this to end up in the page TOC.

---

Content-related

The content-side updates can be done before or after H3s are available in the page TOC and are not a blocker or prerequisite for this implementation.

• On the content side, this would be a good exercise to reevaluate sections and subsections on pages. This will also be a good exercise to make titles consistent in language and structure. Best practices for naming titles and guidelines for creating sections and sub-subsections will be covered in the revamped MDN writing style guide (which is open to further improvements) and hopefully that information will be useful to fix title and content organization-related issues. With the vast nature of this exercise, this will remain an ongoing project - some pages will be simpler to tackle than others.
• Some "Examples" sections have one or more '"HTML - CSS - Result" H3 subsections without a title about what the example is about. Such instances will need to be identified and fixed in content. Again, this is neither a blocker nor a prerequisite for the "H3 in TOC" implementation, just something that writers need to be aware of. @wbamberg has defined guidelines around this: More guidance about examples content#15894.

Appendix

• As an example, @wbamberg shared this page that has 53 H3s - https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Constants. In case we don't fix it on the content side and keep all the headings, it would be nice to have a design solution to handle the long TOC (like being expandable/collapsible).
• @wbamberg also shared that 22 pages on MDN have more than 20 H3 headings: https://gist.github.com/wbamberg/4dd53a837f7a7891b1f34efaae3b7034.
  • A decision will be required if we need a special design implementation to take care of a handful of pages that might have a long page TOC.
  • How many H3s will make the TOC too long along with their parent H2s?
  • What if there are too many H2s?