Titles are not handled properly anymore

[Sotty75]

🐛 Bug Report

The article titles are behaving differently than before and in not consistent ways.

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

1. I have a site where an article has the following front-matter section:

---
id: azuread_setup
title: Azure AD Configuration Setup
hide_title: true
hide_table_of_contents: false
sidebar_label: Azure AD Configuration Setup
description: Azure AD Configuration Setup
keywords:
  - Application
  - Web Server
  - Requirements
---

followed by a header 1 title
# My Header

Expected behavior

I expect the front-matter Title to be hidden and the string My Header to be displayed as a title

Actual Behavior

My Header title is hidden as well.
Also if i have instead of # My Header a second level header immediately after the front-matter section, i see the ID displayed as a title.

[slorber]

@Sotty75 can you show me a screenshot of how it was before, how it is now, so that we can more easily understand and compare?

I'm assuming the minimal md doc to reproduce looks like this (I'm not certain because your sample only contains frontmatter):

---
title: Azure AD Configuration Setup
---

# My Header

Lorem Ipsum

Some questions:

• What is your motivation to have BOTH a title in frontmatter AND in the markdown doc?
• What is your expectation when this happens?
• Which title should be used where exactly in such a case?

I expect the front-matter Title to be hidden and the string My Header to be displayed as a title

Why?

Docusaurus support for h1 markdown headings (# title) is new, it's not clear to me why you used it before.

If 2 h1 titles are declared on the doc, there is an ambiguity and Docusaurus has to pick one of the 2.
This choice Docusaurus makes is not really specified, you should not rely on it, and you should avoid creating this ambiguity in the first place.

Also if I have instead of # My Header a second-level header immediately after the front-matter section, I see the ID displayed as a title.

That's the expected behavior.

also now all level 2 headers placed at the top of the document are rendered as standard text, not properly formatted.

Already fixed with #4641), you can use @canary until we release it (soon).

[slorber]

With this doc:

---
title: Azure AD Configuration Setup
---

# My Header

Lorem Ipsum

## My Header 2

Lorem Ipsum 2

The behavior before (tested on alpha.71):

The behavior after (master, using Docusaurus 2 website to test):

The correct behavior is the behavior after the change.

Having a double-h1 heading at the top of a markdown doc is not something semantically correct and you should simply not do that. We normally emit a console warning in this case.

If you really want to, you will have to update your docs to put 2 headings in the markdown:

---
title: Azure AD Configuration Setup
---

# Azure AD Configuration Setup

# My Header

Lorem Ipsum

## My Header 2

Lorem Ipsum 2

If you absolutely want to restore the behavior before, you can write a remark plugin that would extract your frontmatter title and put it at the top of the markdown content, but again I'd advise against this.

[Sotty75]

There was really not a good reason to have the title in the frontmatter and in the markdown.

It was like that as i migrated a set of existing Docs to docusaurus and then added the frontmatter by cut and paste on all of them, without understanding what i was doing.

I cleared the ambiguity as suggested, removing the title from the frontmatter. Thanks a lot for fixing the other problem.

[slorber]

Actually, I'll re-open because while testing newest Docusaurus site on a few existing sites I noticed this pattern was sometimes used.

• Frontmatter title can control page meta title in priority
• Markdown title can control page heading in priority.
• I think it makes sense to make it possible to have a page heading different from the page meta title (even if the current API is not very explicit)

Related: demisto/content-docs#616 (comment)

[baur]

Docusaurus v3.rc0

Doc plugin

hide_title: true
breadcrumbs: false

not affects