fix(v2): fix contentTitle issues when markdown h1 title contains code blocks (#4882)

* attempt to fix contentTitle issues when markdown h1 title contains inline code blocks

* mention hide_title frontmatter only prevents frontmatter.title from being added in the dom (not a markdown # title in content)

* alwayss insert MainHeading under the div.markdown container for consistency

* ensure MainHeading has no useless id

* revert https://github.com/facebook/docusaurus/pull/4859 as it's now useless: docMeta.title contains the text/frontmatter title in priority over the contentTitle

* fix docs test after revert

* improve markdownParser and fix tests

* fix docs tests

* markdownParser: restore option to remove contentTitle (mostly for blog plugin)

* use removeContentTitle for blog

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -168,7 +168,7 @@ Object {
   \\"unversionedId\\": \\"foo/bar\\",
   \\"id\\": \\"foo/bar\\",
   \\"isDocsHomePage\\": false,
-  \\"title\\": \\"Remarkable\\",
+  \\"title\\": \\"Bar\\",
   \\"description\\": \\"This is custom description\\",
   \\"source\\": \\"@site/docs/foo/bar.md\\",
   \\"sourceDirName\\": \\"foo\\",
@@ -190,7 +190,7 @@ Object {
   \\"unversionedId\\": \\"foo/baz\\",
   \\"id\\": \\"foo/baz\\",
   \\"isDocsHomePage\\": false,
-  \\"title\\": \\"Baz markdown title\\",
+  \\"title\\": \\"baz\\",
   \\"description\\": \\"Images\\",
   \\"source\\": \\"@site/docs/foo/baz.md\\",
   \\"sourceDirName\\": \\"foo\\",
@@ -418,12 +418,12 @@ Object {
             \\"items\\": [
               {
                 \\"type\\": \\"link\\",
-                \\"label\\": \\"Remarkable\\",
+                \\"label\\": \\"Bar\\",
                 \\"href\\": \\"/docs/foo/bar\\"
               },
               {
                 \\"type\\": \\"link\\",
-                \\"label\\": \\"Baz markdown title\\",
+                \\"label\\": \\"baz\\",
                 \\"href\\": \\"/docs/foo/bazSlug.html\\"
               }
             ]

packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts

@@ -180,7 +180,7 @@ describe('simple site', () => {
       isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       slug: '/foo/bar',
-      title: 'Remarkable',
+      title: 'Bar',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',
@@ -254,7 +254,7 @@ describe('simple site', () => {
       isDocsHomePage: true,
       permalink: '/docs/',
       slug: '/',
-      title: 'Remarkable',
+      title: 'Bar',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',
@@ -286,7 +286,7 @@ describe('simple site', () => {
       isDocsHomePage: false,
       permalink: '/docs/foo/bazSlug.html',
       slug: '/foo/bazSlug.html',
-      title: 'Baz markdown title',
+      title: 'baz',
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
       description: 'Images',
@@ -345,7 +345,7 @@ describe('simple site', () => {
       isDocsHomePage: false,
       permalink: '/docs/foo/bazSlug.html',
       slug: '/foo/bazSlug.html',
-      title: 'Baz markdown title',
+      title: 'baz',
       editUrl: hardcodedEditUrl,
       description: 'Images',
       frontMatter: {

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -375,7 +375,7 @@ describe('simple website', () => {
         'foo',
         'bar.md',
       ),
-      title: 'Remarkable',
+      title: 'Bar',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',

packages/docusaurus-plugin-content-docs/src/docs.ts

@@ -202,11 +202,9 @@ export function processDocMetadata({
         numberPrefixParser: options.numberPrefixParser,
       });
 
-  // TODO expose both headingTitle+metaTitle to theme?
-  // Different fallbacks order on purpose!
-  // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-  const headingTitle: string = contentTitle ?? frontMatter.title ?? baseID;
-  // const metaTitle: string = frontMatter.title ?? contentTitle  ?? baseID;
+  // Note: the title is used by default for page title, sidebar label, pagination buttons...
+  // frontMatter.title should be used in priority over contentTitle (because it can contain markdown/JSX syntax)
+  const title: string = frontMatter.title ?? contentTitle ?? baseID;
 
   const description: string = frontMatter.description ?? excerpt ?? '';
 
@@ -245,7 +243,7 @@ export function processDocMetadata({
     unversionedId,
     id,
     isDocsHomePage,
-    title: headingTitle,
+    title,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -199,11 +199,7 @@ export default function pluginContentDocs(
             nextId,
           } = sidebarsUtils.getDocNavigation(doc.id);
           const toDocNavLink = (navDocId: string): DocNavLink => ({
-            // Use frontMatter.title in priority over a potential # title found in markdown
-            // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-            title:
-              docsBaseById[navDocId].frontMatter.title ||
-              docsBaseById[navDocId].title,
+            title: docsBaseById[navDocId].title,
             permalink: docsBaseById[navDocId].permalink,
           });
           return {

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -82,6 +82,7 @@ declare module '@theme/DocItem' {
       readonly frontMatter: FrontMatter;
       readonly metadata: Metadata;
       readonly toc: readonly TOCItem[];
+      readonly contentTitle: string | undefined;
       (): JSX.Element;
     };
   };