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

[cmfcmf]

trafficstars

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] 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: https://github.com/facebook/docusaurus/blob/024474a7b9924f206fa22a91b0c39832354f8e0d/packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx#L41-L43

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

[monkeytronics]

Is this related to an issue I'm seeing. In certain pages, the file name is appearing (sort of) above the H1 header. For example, for a file called: 1-quick-start.md with the following at the top of the file:

---
sidebar_position: 1
---

import DocsCard from '/src/components/global/DocsCard';
import DocsCards from '/src/components/global/DocsCards';
import TOCInline from '@theme/TOCInline';


# Quick Start

<div class="indent-1">
  <TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel = {2} />
</div>
<br/>

In the output file, I can see the H1 Header for "Quick Start" as expected, but there is an additional H1 header with the text "quick-start". I.e.

::before
<header>
  <h1>quick-start</h1>
</header>
<header>
  <h1>Quick Start</h1>
</header>

The odd thing is that I have 2 almost identical files. In one case the undesirable first header tag shows, but in the other it does not... Any idea what the underlying issue is?

[Josh-Cena]

@monkeytronics Your issue is because Docusaurus did not pick up the H1 heading in the content, so we (1) could not remove it from the content (2) inferred another title based on the file name. The reason why parsing failed for your case is unknown; I can try to reproduce this later.

[monkeytronics]

I moved the lines of code around and it now works?!

---
sidebar_position: 1
---

# Quick Start

import DocsCard from '/src/components/global/DocsCard';
import DocsCards from '/src/components/global/DocsCards';
import TOCInline from '@theme/TOCInline';


<div class="indent-1">
  <TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel = {2} />
</div>
<br/>

[Josh-Cena]

@monkeytronics I could not reproduce your issue. Could you submit a new issue with a reproduction? FYI, your second one is more likely to work because Docusaurus simply extracts the first H1 heading before any content, and the less text there is before the H1, the less likely it is to think that there's no title.

[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: