Accessibility proposal: removing extra H1s from the page

CharpentierLucas · November 24, 2023, 5:19pm

Good afternoon!
In the context of an accessibility audit conducted by Dataport, the current structure of the page headings has been reported. The audit highlighted that there were too many H1s, which is especially true on pages like the Dashboard. This caused the auditor to report a lack of structure on the page. I started implementing a solution in this pull request , but wanted to make sure such changes would only happen after a discussion.

The tricky part of this question is that there is still no official recommendation in standards. As far as I could see, neither HTML or WCAG give precise indications on the best solution.

In the past, the subject of the heading structure has already been discussed, such as in those two discussions on the mailing list (2009):

On one hand, the complementary content is not bound to the main page content, so it would make sense for it to be in a separate ‘heading-tree’. On the other hand, it’s more or less the default today to have only one H1 per web page and most of accessibility tools / audits count having more than one H1 as against the best practice. Here, we can see that even if the W3C’s page has a couple H1s, it keeps H2s on complementaries (very similar to our side panels):

From what I could gather, today a H1 is recognized by most people and tools as the page title. Moreover, in the context of a XWiki page, the title of the current page is more important than the title of the panels.

However, banning/removing H1 from user content would be very complicated (breaking the expected rendering at a fundamental level).

In regards to all of these elements, I want to propose a change in our use of H1s in the UI:

proposal#
Only use one H1 per page, except for user generated content.
This would mean that we do not update the rendering of user’s content, but we should change:

current UI elements using H1s such as panels
default page contents with H1s, such as the Home page, to replace every = title = with == title ==

#END OF PROPOSAL#

I think the first point is just necessary for our interface to provide a better heading structure. The second one goes in the direction of educating users by providing them with some examples that have optimal accessibility. The first one is more critical but also less wide in its application.

Note that this heading structure question is not as important regarding accessibility as it was a few months ago because landmarks were added in the interface (XWIKI-20696 and XWIKI-18838). They provide an alternative way to navigate and scan the content for Assistive Technology users.

Please let me know if I missed a critical argument in this discussion (or a forum/mailing list topic)

What do you think of this proposal?

Thank you in advance for your feedback,
Lucas C.

mflorea · November 27, 2023, 10:36am

Yes, but note that MDN is currently recommending having a single H1 as a best practice <h1>–<h6>: The HTML Section Heading elements - HTML: HyperText Markup Language | MDN

While using multiple <h1> elements on one page is allowed by the HTML standard (as long as they are not nested), this is not considered a best practice. A page should generally have a single <h1> element that describes the content of the page (similar to the document’s <title> element).

We need to follow the best practice, so +1 for your proposal.

Thanks,
Marius

mleduc · November 27, 2023, 11:22am

+1

Do you also want to make it a best practice when writing pages on (*.)xwiki.org ?

CharpentierLucas · November 27, 2023, 12:08pm

It would be interesting for consistency
Is there a specific doc where we could put this best practice?
I think we can add a couple lines about this at least on:

Thanks for your feedback
Lucas C.

mleduc · November 27, 2023, 1:02pm

+1 for DocGuide, I’m not sure to understand what you want to add to XWikiXMLFilesCodeStyle though

CharpentierLucas · November 27, 2023, 1:13pm

default page contents with H1s, such as the Home page, to replace every = title = with == title ==

When writing XML Wiki content, devs should avoid using H1 in their content (e.g. in the home page a for a new extension,… which is not content on the xwiki.org wiki). I think it’s outside the scope of the recommendation for doc and would make sense in the codestyle.
An alternative to that could be to add a disclaimer on the XWiki 2.1 syntax to warn users that using first level title can degrade the experience for assistive technologies users.

mleduc · November 27, 2023, 1:16pm

Indeed, good

CharpentierLucas · November 29, 2023, 10:22am

Updated the PR at XWIKI-21370: Header structure uses too many H1 by Sereza7 · Pull Request #2448 · xwiki/xwiki-platform · GitHub
Updated doc:

Created an improvement ticket for the ToC macro: XRENDERING-732.

pbodnar · March 14, 2025, 5:26pm

Hi, probably little bit late to the party, but I’m not quite convinced about simply just recommending common users to skip the usage of “Heading 1” (as per the updated https://dev.xwiki.org/xwiki/bin/view/Community/DocGuide#HTextediting). Because it means there would be one unused heading level offered in the XWiki editor, but also one heading level unused for rendering (while “edit” buttons are only offered next to headings 1 and 2).

Another thing is that the title of the page gets rendered into the 1st <h1> as well as into the <title> element by default. Isn’t that at least partly mitigating the issue with accessibility?

I think the simplest solution to this problem could be to generate <h2> for the current “Heading 1”, <h3> for the current “Heading 2” etc. But I realize this can be problematic, as it would impact styling and there is no <h7> in HTML for mapping the lowest “Heading 6”.

All in all, I do realize there is probably no really easy solution for this problem of “multiple h1 elements on a page”, while considering all related aspects. So which approach would you recommend to users of a regular, company-wide (internal) XWiki instance? And are there no plans to change the XWiki behavior in this regard in the foreseeable future?

Simpel · March 15, 2025, 11:46am

Parallel to recommend not using h1 we did some adaptions to the editors. We only show h2 to h6 in the wysiwyg editors.

CKE_Headlines

Following code snippets are active in our wysiwyg editor config:

CKEDITOR.config.format_tags = 'p;h2;h3;h4;h5;h6;pre';
config.removeQuickActions = ['h1',…

In the wiki editor we hide h1 with css (that’s not a cool selector for the lack of a better one):

#xwikieditcontentinner > div.leftmenu2 > a:nth-child(12) {
    display: none;
}

Our first approach was stepping up the level in the wysiwyg editor config what worked but did some confusion on some users knowing about “only one h1 per page”. The not existing h7 was a problem too.

In the end we decided to hide h1 on all places we can and explain why we do this.

Nevertheless people using the wiki editor (not so many) can create a h1. I expect people who write syntax to be a bit more familiar with the rules. Importing word documents can create bad h1 too. But some things can’t be solved entirely.

CharpentierLucas · March 17, 2025, 9:13am

Note that technically there’s a way to make a H7 with ARIA markup. However it’s not as easy as h1->h6 and not as widely supported.

AFAIK, there’s no plan to make large changes, too many XWiki users and content rely on those headings for us to break backward compatibility here.
However we could consider bringing in XWiki standard some stronger enforcement for our recommendations like Simpel showed – given there’s a generic need for them.

Thanks for your participation on the topic!