Custom titles do not work if a page has multiple H1 headers

[choldgraf]

If there are multiple H1 headers on a page (e.g., multiple # Single hash headers), then title over-rides that are specified in .. toctree:: objects do not work properly.

To reproduce

• Create a page with multiple H1 titles (e.g. mypage.md with # My title and # My H1 title section).

• In a parent page, link it with a toctree like:

  .. toctree::
    
    My custom title page <mypage>
  

And the title should not be over-ridden properly.

Originally reported in:

• Custom titles in left nav don't work as expected if a page has more than one <h1> element executablebooks/sphinx-book-theme#628

[trallard]

This is an interesting one - I wonder if this is a decision made at the Sphinx level.
Some things to consider:

1. From an author's point of view, it might be helpful to have more than one H1 heading in a document/web page - and from a web development perspective, this is possible (a.k.a, nothing is preventing this from doing it)
2. From an accessibility point of view, headings (and heading hierarchy) help screen readers navigate the document. So one should not have more than one H1 in a given document (I can find some resources - there is nothing formal like a criterion or rule that says it has to be this way but the consensus in the accessibility community is that there should be one and only one H1 heading

So based on point 2. I wonder if somewhere in Sphinx this was made as a conscious decision to only have one H1 header shown in the TOC

[choldgraf]

Yes I think that is basically it - the first header level is special and reserved for the title. All other headers are expected to be nested under it. If you add multiple top level headers, sphinx treats them as if they were different pages entirely. That's what messes up the TOC and sidebar stuff.

I guess the question is whether we should be clever here and basically say "if there is more than one top level header then nest all subsequent headers under the first".

The other thing that could be done is to support "title:" in the page metadata, and if that exists then nest the page content under a top level header of that name.

[12rambau]

as explained by @choldgraf Sphinx is treating each level 1 header as defining a new page in the toctree hence the confusion when there are multiple.

The thing to keep in mind when using Sphinx is that it is designed for many other build type, not only HTML. In a Latex build, multiplying h1 level will lead to a very strange paginaltion of your document (same for ebooks). I think that's also why it's by design not suported.

[choldgraf]

I think the simplest thing to recommend would be to add a quick check for whether there are multiple top level sections in the page, and emit a warning to tell people to nest all headers under one title header

[trallard]

I think the simplest thing to recommend would be to add a quick check for whether there are multiple top-level sections in the page, and emit a warning to tell people to nest all headers under one title header

Yup - I would prefer avoiding adding workarounds to an intentional design decision that also happens to help with our accessibility goals. And instead, encourage folks to use only one H1 header.

[trallard]

@choldgraf - since it seems we decided not to create a workaround due to accessibility concerns and potential issues with other output types (i.e. LateX), can we close this issue with not planned and open a follow-up one with the checks discussed in this comment plus some guidance on the docs on why using multiple H1 headers is discouraged from an accessibility POV?

[12rambau]

I would simply leave this one open and reference/close it in/with the documentation update you want to make.

[drammock]

superseded by #1351. @12rambau I opted to create a new issue in order to distill just the relevant info so that it's clearer from the title/description what the fix should be (hopefully making it easier for non-core-team contributors to fix it)

[12rambau]

fair enough