facebook / facebook/docusaurus

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

Open
#11,261 5 comments 1 reaction 0 assignees View on GitHub
bug domain: a11y
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).

### Prerequisites

- [x] I'm using the latest version of Docusaurus.
- [x] I have tried the `npm run clear` or `yarn clear` command.
- [x] I have tried `rm -rf node_modules yarn.lock package-lock.json` and re-installing packages.
- [x] I have tried creating a repro with https://new.docusaurus.io.
- [x] 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:

```




Recent posts


2025


    [...]








Article Title

[...]



Article body.


[...]




```

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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.