1

Consider this markup:

<!doctype html>
<html>

    <head>
    </head>

    <body>
        <header>
            <nav>
                <ul>
                    <li>
                        <a href="/">
                            <h2>Home</h2>
                        </a>
                    </li>
                    <li>
                        <a href="/other">
                            <h2>Other</h2>
                        </a>
                    </li>
                </ul>
            </nav>
        </header>
        <main>
            <h1>Page Title</h1>
        </main>
    </body>

</html>

This markup is "fine" but, if I understood correctly, neither accessible nor semantically correct/recommended. The issue is with the h2 appearing before h1, which creates a confusing document outline:

1. Untitled BODY
  1. Home
  2. Other
2. Page Title

However the obvious intended outline is:

1. Page Title
  1. Home
  2. Other

The naive way to achieve this would be to just "move" the whole nav somewhere after the h1, either inside main or after it. But this is not how I want my page to look like, I obviously want my navigation above my main page content. Of course I could use CSS to somehow move the nav visually up, but that doesn't seem correct either.

My question is: What is the most common, but accessible solution to this "dilemma"? Note that I definitely want the nav to keep using h2 (or any other heading level), as that is, as far as I know, the recommended "semantic" way. This way, the navigation links will also show up in the document outline. Is there some way to just tell a screen reader or browser that some headings should "swap" position in the document outline, maybe through some aria- attributes? Is there some alternative I'm missing?

One solution I thought of, but "feels" wrong to me:

<!doctype html>
<html>

    <head>
    </head>

    <body>
        <header>
            <h1>
                Page Title
            </h1>
            <nav>
                <h2>
                    Page Navigation
                </h2>
                <ul>
                    <li>
                        <a href="/">
                            <h3>Home</h3>
                        </a>
                    </li>
                    <li>
                        <a href="/other">
                            <h3>Other</h3>
                        </a>
                    </li>
                </ul>
            </nav>
        </header>
        <main>
            <h2>Main Content Title</h2>
        </main>
    </body>

</html>

This feels a bit verbose but at least results in a correct document outline. Is this really the only way to solve my problem?

4
  • 1
    Don't use h tags here. It's not semantic, nor correct to do so. Your nav element is what is important for accessibility. Style the nav links how you want to - without those tags. Note that I definitely want the nav to keep using h2 (or any other heading level), as that is, as far as I know, the recommended "semantic" way. That is wrong.
    – disinfor
    Nov 30, 2021 at 2:34
  • So the navigation items should not show up in a document outline in your opinion? @disinfor Nov 30, 2021 at 3:38
  • 3
    The navigation does not need to be in the document outline. The document outline is for displaying the content tree of the actual content. In fact, having the navigation in the document outline would probably lead to confusion since the user would be presented with elements that are not relevant to reading. In fact, you should include a single link prior to the menu for skipping to content which would be included in the document outline. This really isn't opinion - but rather the correct use of the document outline.
    – disinfor
    Nov 30, 2021 at 15:06
  • Alright, seems reasonable. Nov 30, 2021 at 16:20

2 Answers 2

1

The proper way to mark up this kind of content (in terms of semantics and accessibility) is as follows—

<header>
  <nav aria-label="Main Navigation">
    <ul>
      <li><a href="#">Home</a></li>
      <li><a href="#">About</a></li>
      <li><a href="#">Lorem</a></li>
      <li><a href="#">Ipsum</a></li>
    </ul>
  </nav>
</header>
<main>
  <h1>Page Title</h1>
  <p>Additional page content...</p>
</main>

Navigation items should not be marked up as headings. A list of links is all that is necessary. See this example from the Mozilla documentation on the navigation element.

If you want to add a hidden label for the navigation for assistive technologies, you can add an aria-label attribute to the <nav> element, as detailed in this example from the W3C Accessibility Guidelines Working Group. Additionally, this approach avoids needing to add a heading out of order.

Finally, be sure to include the document title (<h1>) within the <main> element, as in this example from the Mozilla documentation on the main element.

-2

https://www.accessibility-developer-guide.com/examples/headings/visually-hidden-headings/ is answering most of the questions I have here.

Turns out it's fine to just move headings you don't want to be displayed, but read by screen readers, off the screen. This way a correct document outline can be achieved as well, without being visually verbose.

My solution I will probably use from now on would be:

<!doctype html>
<html>

    <head>
    </head>

    <body>
        <header>
            <h1 class="visually-hidden">
                Page Title
                <!-- this can also just contain a logo -->
            </h1>
            <nav>
                <h2 class="visually-hidden">
                    Page Navigation
                </h2>
                <ul>
                    <li>
                        <a href="/">
                            <h3>Home</h3>
                        </a>
                    </li>
                    <li>
                        <a href="/other">
                            <h3>Other</h3>
                        </a>
                    </li>
                </ul>
            </nav>
        </header>
        <main>
            <h2>Main Content Title</h2>
        </main>
    </body>

</html>

The visually-hidden class would then be described by:

.visually-hidden {
    position: absolute;
    left: -10000px;
    width: 1px;
    height: 1px;
    overflow: hidden;
}
1
  • As @disinfor pointed out, heading elements should not be used for navigation items. Semantically, they should just be anchors in a list.
    – Sean
    Nov 30, 2021 at 15:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.