Theme Classic inconsistently wraps the doc page title into <header>

[cmfcmf]

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

The theme inconsistently wraps the title of a doc page into <header>: Only when a synthetic title is rendered, it is being wrapped into <header>. Non-synthetic titles are not wrapped into <header>.

Relevant code:

docusaurus/packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx

Lines 41 to 43 in 024474a

	<header>
	<Heading as="h1">{syntheticTitle}</Heading>
	</header>

Reproducible demo

https://codesandbox.io/s/dazzling-panini-566sqf

Steps to reproduce

Go to "Tutorial Intro" page: Title not wrapped in <header>
Go to "Tutorial - Basics" -> "Create a Page": Title is wrapped in <header>

Expected behavior

The doc title should either always, or never, be wrapped in <header>.

Actual behavior

The doc page title is wrapped in <header> depending on whether it is a synthetic title or not.

Your environment

• Docusaurus version used: 2.2.0

Self-service

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

[slorber]

Thanks

I also noticed that.
Historically the synthetic/frontMatter title was wrapped in a header.

When introducing the # Title title as it's part of MDX it's not really possible to "extract it" apart (although it should be possible in MDX 2).

I'm not an expert in semantic HTML and accessibility, does this violate any existing rule, or is it just more convenient for you to crawl the doc and create a search index if things are consistent?

[cmfcmf]

I'm not an expert in semantic HTML and accessibility, does this violate any existing rule, or is it just more convenient for you to crawl the doc and create a search index if things are consistent?

It was a bit surprising to me that the <header> is sometimes there and sometimes not. The fix for parsing it wasn't difficult or anything special.
I guess this issue is more of a feature request to make it consistent, which could be as simple as never rendering a <header>, but I am unsure about the implications.

[slorber]

I am not sure either 😅

So I'd prefer if someone can back up with semantic HTML links what we should do exactly before we change anything

[sierikov]

In my perspective, it would be beneficial for us to consistently include the <header> tag. It helps individuals, who rely on accessibility features, identify the introductory content. Moreover, it aligns with the usage outlined in MDN.

[slorber]

We already have a contentTitle remark plugin where we could do this wrapping, we'll look into it.

We could probably wrap the MDX heading in a <heading> tag thanks to that remark plugin. Pseudo code to test: