mdBook

mdBook copied to clipboard

Problem

There must be only one Heading Level one present. If Book Title is shown, its H1. Then all Markdown files need to Start with H2.

Steps

1. Set book title
2. Make entries in Summary.md
3. Find that the entries all start with H1 "#" instead of H2 "##"

Possible Solution(s)

Start new Markdown files with H2 "##"

Notes

No response

Version

mdbook v0.4.37

This is indeed a mild accessibility issue (though not a WCAG AA violation!), but the better solution is probably to make the title of the book on each page a styled link that is not a heading; see this discussion (among many others!) for example.

This is indeed a mild accessibility issue (though not a WCAG AA violation!), but the better solution is probably to make the title of the book on each page a styled link that is not a heading; see this discussion (among many others!) for example.

You still need to expose language of the page, and the H1 must always reflect the site title - for which can only 1 h1 exist. If you decide to not make the Book Title H1, then the site title is also missing, because currently H1 is automagically the site title. But you need to have one.

A <title> works just fine for that, and the h1 should, as a rule, not be the same across all pages on a site!

A <title> works just fine for that, and the h1 should, as a rule, not be the same across all pages on a site!

Refer to https://dequeuniversity.com/rules/axe/4.0/document-title

"Make the page title match the top heading (ideally labelled as h1) on your page. These don’t need to be identical, but it often makes sense to make them very similar, since the title and h1 elements serve essentially the same purpose. "

Every page must have a clear and descriptive title. For screen reader users, having inconsistent headings and page titles can be confusing. The content should not only be accessible but also logically structured.

Headings should follow a clear hierarchy:

First Level (H1): This is the main page title, such as "How to Make a Sandwich."
Second Level (H2): This indicates major sections within the page, like "Preparation."
Third Level (H3): These are subsections under the second level, for example, "Ingredients."

Maintaining a logical structure ensures that both screen reader users and sighted users can navigate the content effectively.

Yep! In this case the title should probably be something like <Chapter>: <Section> – <Book>. My point was not that the title would be only the book title but that it would include and so subsume it.