Accessibility checkers have a problem with the placement of the h1 tag

[mclarty]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Accessibility checkers (such as SiteImprove) are flagging each page using the blog layout as not adhering to "accessibility best practices" with the following note:

Page does not start with a level 1 heading
A level 1 heading h1 tells the user what the page is about before they decide to navigate through the content.

Headings are used to structure content into a hierarchy of importance. If a page starts with a different heading level, it can cause confusion for the user.

When analyzing the HTML output from Docusaurus, the sidebar (aside) is rendered before the main content (main) and the h3 tag in the sidebar is being detected as the first header in the HTML source. By removing the use of h3 in the sidebar and replacing with a div class specific to the sidebar, accessibility checkers (and screen readers and other assistive devices) will see the use of h-tags in the main content as the only actual headings on the page.

Source example below:

<div class="row">
    <aside class="col col--3">
        <nav class="sidebar_re4s thin-scrollbar" aria-label="Blog recent posts navigation">
            <div class="sidebarItemTitle_pO2u margin-bottom--md">Recent posts</div>
            <div role="group">
                <h3 class="yearGroupHeading_rMGB">2025</h3>
                <ul class="sidebarItemList_Yudw clean-list">

                	[...]

                </ul>
            </div>
        </nav>
    </aside>
    <main class="col col--7">
        <article class="margin-bottom--xl">
            <header>
                <h2 class="title_f1Hy"><a href="/blog/item1/">Article Title</a></h2>

                [...]

            </header>
            <div class="markdown">
                <p>Article body.</p>
            </div>

            [...]

        </article>
    </main>
</div>

Related to this -- the blog index page does not contain an h1 tag altogether.

Reproducible demo

No response

Steps to reproduce

1. Publish a Docusaurus site using docusaurus-theme-classic and create a blog page.
2. Review the HTML code.

Expected behavior

The first header tag on a blog page should be an h1 that conveys the article title.

An h1 tag on the blog index (e.g., recent posts) page should be an h1 that conveys the page title.

Actual behavior

The first header tag to occur on the blog pages is an h3 in the sidebar.

No h1 tag exists on the blog index page.

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Hey, I'm not an accessibility expert but this indeed seems weird to use an <h3> for the "year groups" of our blog sidebar.

However,

Accessibility checkers (such as SiteImprove)

Can you tell me which other accessibility checker report this error? How can I verify this myself?

I've come to not trust blindly what a single accessibility tool report, because they may all behave differently in practice.

Also, do you have any reference document from an authoritative source that explains that it's bad to use an h3 in this <aside> context? I'm not sure but I think it's fine to use headings outside the main content.

See for example: https://www.w3.org/WAI/tutorials/page-structure/headings/#:~:text=used%20like%20this.-,Main%20heading%20after%20navigation,-In%20this%20second

---

TLDR: can you help me and somehow find a way to prove that it's not your specific tool that is wrong and reporting a false positive.

[vipulbhasin23]

When analyzing the HTML output from Docusaurus, the sidebar (aside) is rendered before the main content (main) and the h3 tag in the sidebar is being detected as the first header in the HTML source. By removing the use of h3 in the sidebar and replacing with a div class specific to the sidebar, accessibility checkers (and screen readers and other assistive devices) will see the use of h-tags in the main content as the only actual headings on the page.

Unrelated to the issue being reported, I also feel that the sidebar with years and other blog posts could also semantically be a nav item since it allows you to navigate to other posts while also changing the URL

[TimvdLippe]

We are seeing similar issues on https://developer.overheid.nl/communities/

index.mdx (source):

# Communities

Hieronder een overzicht van developer communities.

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```

Rendered output (cut some SVG elements out for readability):

<header>
    <h1>Communities</h1>
</header>
<p>Hieronder een overzicht van developer communities.</p>
<section class="row">
    <article class="docCardListItem_d7Ib col col--6">
        <a class="card padding--lg cardContainer_S8oU" href="/communities/code-for-nl">
            <h3 class="cardTitle_HoSo"><!-- -->Code for NL</h3>
            <p class="cardDescription_c27F">Code for NL is een netwerk van developers, designers en andere experts die
                samenwerken aan digitale toepassingen voor een open, eerlijke en inclusieve samenleving.</p>
        </a>
    </article>
    <article class="docCardListItem_d7Ib col col--6">
        <a class="card padding--lg cardContainer_S8oU" href="/communities/common-ground">
            <h3 class="cardTitle_HoSo"> <!-- -->CommonGround</h3>
            <p class="cardDescription_c27F">Gemeenten werken samen met een community van betrokkenen partijen aan
                bouwstenen, zoals softwaretoepassingen, technische componenten of standaarden voor gegevensuitwisseling.
            </p>
        </a>
    </article>
</section>

Note that, despite DocCard setting the heading to h2 (

docusaurus/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx

Line 79 in a4c33bf

as="h2"

), the heading is rendered as h3.

When we run npx axe https://developer.overheid.nl/communities/ we get the following output:

Running axe-core 4.10.3 in chrome-headless

Testing https://developer.overheid.nl/communities/ ... please wait, this may take a minute.

  Violation of "heading-order" with 1 occurrences!
    Ensure the order of headings is semantically correct. Correct invalid elements at:
     - a[href$="code-for-nl"] > h3
    For details, see: https://dequeuniversity.com/rules/axe/4.10/heading-order

1 Accessibility issues detected.

Which is a correct finding, since the heading order is h1 for "Communitities" and then h3 for "Code for NL". It should be h2 for "Code for NL", which is what DocCard wants it to be, yet it isn't rendered as such.

This is for Docusaurus 3.8.1 (latest version at time of writing).

[slorber]

@TimvdLippe are you sure you didn't swizzle the components?

Because we don't see this behavior on our own website: https://docusaurus.io/docs/sidebar/items#embedding-generated-index-in-doc-page

[TimvdLippe]

Ah, I am not familiar that much with Docusaurus and didn't know swizzling. Turns out that you are correct. Haven't been able to figure out how to fix the issue, given that the h1 header is generated by Docusaurus. I tried swizzling https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/DocCategoryGeneratedIndexPage (which is marked as unsafe, I know) to make it a h2, but that didn't have any effect. Will have to debug further what's going on with our setup.