Accessible HTML5 heading structure in WordPress

32 comments

1. “I only use H1′s, because in HTML5 you can”

   The HTML5 Recommendation states:
   “Warning! There are currently no known implementations of the outline algorithm in graphical browsers or assistive technology user agents, although the algorithm is implemented in other software such as conformance checkers. Therefore the outline algorithm cannot be relied upon to convey document structure to users. Authors are advised to use heading rank (h1-h6) to convey document structure.”
   http://www.w3.org/TR/html/sections.html#outlines

   for implementation outlook refer bug links here https://www.w3.org/wiki/HTML/Usage/Headings/h1only#Notes

   further advice:
   https://www.w3.org/wiki/HTML/Usage/Headings/h1only
   https://www.w3.org/wiki/HTML/Usage/Headings/Missing

2. Pingback: Weekly Roundup of Web Design and Development Resources: November 21, 2014

3. Based on the CSS in many themes I think part of the aversion to changing the post title tag between index pages and single pages is that many developers use the h1/h2 declaration to style these elements instead of a CSS class. This would naturally cause style differences between indexes and single posts/pages.

   Not an excuse, but a possible reason.

   On that note I’m considering changing the tag structure of Simone to this approach. I used to do things the way you recommend here but abandoned it because _s abandoned it. Now I want to go back in the archive and look at when that happened and for what reason.

   1. Maybe it’s time for an accessibility review of _s

      1. I’ve had the same thought for a long time. I’ve even got a bug report in really rough draft form. It seems it’s time to revisit that. Headings have been a oft-raised-and-dismissed issue in _s.

4. From an SEO perspective (I worked in SEO for a long time, and still follow best practices in that realm), the best practice for headings is that while the hierarchy doesn’t particularly matter, it’s preferable to have just one H1, and for that H1 to represent the most specific topic for that page – generally, that would be the post title. For hierarchy purposes, that makes it difficult to define a consistent heading structure for the surrounding characteristics, obviously.

   FYI, I wrote a similar article just a week ago, although from a different perspective: The Headings Hierarchy Challenge

   1. Hi Joe, thanks for the link to your excellent headings post. I totally missed that.

   2. I just want to point that Joe is using H1 to outline hierarchy in: https://github.com/joedolson/accessible-twin-cities/

      I’m still thinking if I should go for H2 in my theme…

      1. I’m trying to implement your suggestions with one H1/page idea and have a practical question.

         As you suggested, I marked Main Menu that is located in header with H2. But if visiting individual article, the outline of the document is this: https://cloudup.com/ctdWf4iUfVd

         Question: is it possible to have H2 at the top? If not, what would be the plan, to remove H2 heading from the Main Menu?

         Thank you!

         1. Hi Tomas,

            Great work!

            If it is allowed to have an H2 on the top depends on the guidelines you are following.
            For WCAG 2 AA it’s allowed, for the Dutch Government Accessibility Guidelines it’s not.
            For getting the accessibility-ready tag it’s also allowed.

            For practical accessibility (screen reader users) it’s fine, and it’s doesn’t hinder SEO imho.
            And it’s a hell of a job to alter this construction in WordPress.

            A good construction could be (copying your code):
            <nav id=”site-navigation” class=”main-navigation” role=”navigation” aria-labelledby=”primary-menu” itemscope=”” itemtype=”http://schema.org/SiteNavigationElement”>
            <h2 class=”screen-reader-text” id=”primary-menu”>Main Menu</h2>
            etc..

            Then you link the heading to the nav.

            I looked at your outline, and only the "about" and "leave a reply" H3's are not perfect, but that's a WordPress issue (altering headings in WP itself is an ongoing battle).

            A validator is a machine, so look at the results and decide what you want to alter yourself. We code for users, not for machines 😉

            Can you notify me when the accessibility changes are ready? I would love to make some noise for you.

      2. About the more than one H1: This is where Joe and I disagree. (As Accessible Joe always says: put 3 accessibility people in a room and you get 5 different opinions).

      3. Thank you, Rian, for thorough review! I investigated the use of aria-labelledby and it looks that in my case aria-label fits better, because the heading is hidden:

         “The aria-label attribute is used to define a string that labels the current element. Use it in cases where a text label is not visible on the screen. (If there is visible text labeling the element, use aria-labelledby instead.)”

         I’ll let you know when Tiny Framework theme will be approved for WP.org repository, thank you!

      4. I need some help on aria-label when used for hidden headings. Does the aria-label get ‘rendered’ by AT when the element is set to display: hidden ? Or do you use aria-label on a wrapper?

         1. Hi Evert,
            If you hide an element with display:hidden, it and it’s content is not read out by a screen reader.
            If you want to hide a heading from sight and still have it read out by a screenreader, use the .screen-reader-text class.
            See for more the post: The screen-reader-text class, why and how?

      5. Oh, sorry, one more question (I forgot). If I use the ‘one H1 per page’ rule, how does this work for ATs when the site navigation’s H2 is situated above the article title’s H1? (and the sidebar’s H2 on the same level as (or below) the H1 of the article). Strictly speaking isn’t it so that any site-wide stuff on a page (like navigation and sidebars) are unrelated to the content’s outline? We have at minimum 2, at maximum 3 outlines on a page:
         1. Page layout (header, navigation, content, footer)
         2. Content outline (e.g. headings in an article)
         3. (in collection pages, like archives) outlines for individual items (not just article excerpts but also widgets and apps)
         A web-page is not an actual physical page, in theory a webpage could contain multiple ‘virtual pages’ each completely unrelated to each other, so each should have its own top-level heading (where title-tag is the overall collection heading). Or am I overthinking it?
         This is so confusing.

5. @tomas: I did some research together with Andrea Fercia: you are right about the aria-label attr., both ways are treated the same by screen readers, so stick with the advised one. You might consider removing the role=”navigation” (http://www.w3.org/TR/html5/dom.html#aria-usage-note)

6. I guess one battle lost :-/

7. Pingback: Wordcamp Europe 2015 | Life is beautiful
8. Pingback: Genesis 2.2, accessibility changes and features

9. Hi,

   I’d like to improve accessibility of my themes and I’ve actually used the approach described in this article before but switched to _s way (similar story to mor10’s).

   However, I feel there is an issue with the rule “first heading tag on the website should be H1” here. That rule is basically broken on all the pages (except front/home page), posts and archives (at least in vast majority of cases).

   Also, I would like to ask if anybody have some insight about whether there is a difference in how screen readers outline the HTML document and how the browser does it? I use HTML5 Outliner tool in Chrome to check things up and I am quite satisfied with the output on my theme (at least the one I’m building right now). Does this HTML5 outline differs from what screen readers “see”?

   Thanks!

   Regards,

   Oliver

   1. Hi Oliver,

      the rule “first heading on the website should be H1”

      Looking at this from an accessibility point of view:

      For WordPress we want to comply with WCAG 2 AA rules, because these are globally the most used guidelines.
      And having the first heading an H1 is not a WCAG 2 AA rule.
      In the header of a WordPress site, H2’s are added to label the skip links, navigation and widget area, which is very useful for screen readers. The H1 is added on the homepage in the header, and for the rest of the pages just above the content.
      There is no a11y problem with this structure, for screen reader users the first heading doesn’t need to be an H1. More important is to have one H1 per page and the rest meaningful and semantically used.

      Not all screen readers support reading an outline, it depends on brand and version, the same for browsers. But screen reader users depend heavily on heading structure to navigate.
      And then there is this post by Steve Faulkner: The HTML5 Document Outline:

      If you as a developer want to provide a meaningful document structure, use the h1–h6 elements to express document structure. DO NOT rely upon the HTML5 document outline.

      Hope this helps
      Rian

      1. Hi Rian,

         Thank you for the reply and explanation. It really seems better solution for accessible websites. I’ll try my best to implement the proposed heading structure then.

         Regards,

         Oliver

      2. Hi Rian,

         I would like to ask about the first heading on the page being H1 again. According to WordPress Accessibility, this is required: “Failure: First heading element on the page is not an H1” (from https://make.wordpress.org/themes/handbook/review/accessibility/required/ )

         So, I’m getting a bit confused about this… Do you have any insight on this WP requirement please?

         Thanks!

         Oliver

10. Pingback: Accessible Headings FTW - Simple web accessibility tips

11. Hi Oliver,
    For WCAG 2 AA it is not required to have the H1 as first heading.
    I know the accessibility-tag rules states different and I don’t agree with that. This is being discussed in the wpa11y group at the moment.
    If you have problems getting the accessibility-ready tag because of this rule, please contact me.

12. Hi Rian,

    Thank you very much for the answer. I am currently building a commercial theme, so this one won’t be listed in WPORG repository and thus I will keep the heading structure like it is now, according to your suggestions above.

    But I’d like to make it WP accessibility-tag compliant anyway as I would like to make all my themes accessible from now on. And obviously I’ve got very confused about the requirements the WordPress has. I needed some clarification for my future WPORG themes too.

    Thank you again and let’s hope this requirement will change to recommendation at least.

    Regards,

    Oliver

    1. Hi Oliver,

       FYI:
       The rule “First heading element on the page is not an H1” has been removed from the accessibility-tag requirements as from today 🙂

       Kind regards
       Rian Rietveld

       1. 🙂 This is a great news! Thank you! I’m glad I’ve asked you about this 😉

13. Pingback: Accessibility fundamentals. AKA building, designing and writing for real people.
14. Pingback: How to Hide/Remove Archive Headlines in Genesis

15. What is the difference between html5 and previous ver?

    1. For the headings structure there is no difference.

Comments are closed.