Headings hierarchy could be improved/cleaned for better accessibility (a11y) #4609

New Issue

OVERLORD · 2026-02-05T09:07:27+03:00

OVERLORD commented

2026-02-05 09:07:27 +03:00

Originally created by @JocelynDelalande on GitHub (Apr 10, 2024).

Describe the Bug

Headings hierarchy of content pages have several issues and makes title-based navigation (very common with srceen-reader navigation) difficult. Issues are :

Links to books/chapters/pages in « Book navigation » should not be marked up as headings, but rather as bare links in ul / li
Details / Actions / Page navigation / Book navigation are <h5>, which is a cosmetic rather than structural use of titles level and breaks title navigation ; should probably be h2 ?
h1 includes website title (which is legit in <title> but maybe not in <h1>, probably minor issue if issue at all)
in some pages, Details/Actions h5. headings (which are navigation, not content) get « absorbed » into the last content section (see second screenshot, which is from another, private, page).

The heading hierarchy of the content part itself is good though :)

Steps to Reproduce

Open any content page of a BS wiki. (example of the issue with [a page of GRAP wiki](https://librairie.grap.coop/books/odoo-v12/page/un-mot-sur-odoo-et-grap page) )

Expected Behaviour

Use more accessibility-friendly headings hierarchy ; see different possible layouts at w3 website . Remove some heading tags (book nagivation links).

Screenshots or Additional Context

Headings map extension can be used to debug such issues

Good luck with that, and thanks by advance for taking that topic into consideration <3

Browser Details

No response

Exact BookStack Version

v23.08.3

Originally created by @JocelynDelalande on GitHub (Apr 10, 2024). ### Describe the Bug Headings hierarchy of content pages have several issues and makes title-based navigation (very common with srceen-reader navigation) difficult. Issues are : - Links to books/chapters/pages in « Book navigation » should *not* be marked up as headings, but rather as bare links in ul / li - Details / Actions / Page navigation / Book navigation are `<h5>`, which is a cosmetic rather than structural use of titles level and breaks title navigation ; should probably be h2 ? - h1 includes website title (which is legit in `<title>` but maybe not in `<h1>`, probably minor issue if issue at all) - in some pages, Details/Actions h5. headings (which are navigation, not content) get « absorbed » into the last content section (see second screenshot, which is from another, private, page). The heading hierarchy of the content part itself is good though :) ### Steps to Reproduce Open any content page of a BS wiki. (example of the issue with [a page of GRAP wiki](https://librairie.grap.coop/books/odoo-v12/page/un-mot-sur-odoo-et-grap page) ) ### Expected Behaviour Use more accessibility-friendly headings hierarchy ; see different possible layouts [at w3 website ](https://www.w3.org/WAI/tutorials/page-structure/headings/#main-heading-after-navigation). Remove some heading tags (book nagivation links). ### Screenshots or Additional Context ![](https://github.com/BookStackApp/BookStack/assets/429633/c47862aa-7e5c-4fe0-ad1c-6ed8ea4697d2) ![](https://github.com/BookStackApp/BookStack/assets/429633/55cf1496-07a0-4e89-b0a3-bb25b4f1800e) [Headings map extension](https://addons.mozilla.org/fr/firefox/addon/headingsmap/) can be used to debug such issues Good luck with that, and thanks by advance for taking that topic into consideration <3 ### Browser Details _No response_ ### Exact BookStack Version v23.08.3

OVERLORD added the 🐛 Bug label 2026-02-05 09:07:27 +03:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#4609