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

packages/docusaurus-mdx-loader/src/index.js

@@ -31,10 +31,7 @@ module.exports = async function docusaurusMdxLoader(fileString) {
 
   const {frontMatter, content: contentWithTitle} = parseFrontMatter(fileString);
 
-  // By default, will remove the markdown title from the content
-  const {content} = parseMarkdownContentTitle(contentWithTitle, {
-    keepContentTitle: reqOptions.keepContentTitle,
-  });
+  const {content, contentTitle} = parseMarkdownContentTitle(contentWithTitle);
 
   const hasFrontMatter = Object.keys(frontMatter).length > 0;
 
@@ -69,7 +66,11 @@ module.exports = async function docusaurusMdxLoader(fileString) {
     return callback(err);
   }
 
-  let exportStr = `export const frontMatter = ${stringifyObject(frontMatter)};`;
+  let exportStr = ``;
+  exportStr += `\nexport const frontMatter = ${stringifyObject(frontMatter)};`;
+  exportStr += `\nexport const contentTitle = ${stringifyObject(
+    contentTitle,
+  )};`;
 
   // Read metadata for this MDX and export it.
   if (options.metadataPath && typeof options.metadataPath === 'function') {

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

@@ -203,12 +203,7 @@ 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;
-
+  const title: string = frontMatter.title ?? contentTitle ?? baseID;
   const description: string = frontMatter.description ?? excerpt ?? '';
 
   const permalink = normalizeUrl([versionMetadata.versionPath, docSlug]);
@@ -246,7 +241,7 @@ export function processDocMetadata({
     unversionedId,
     id,
     isDocsHomePage,
-    title: headingTitle,
+    title,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,

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;
     };
   };

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

@@ -222,7 +222,6 @@ export default function pluginContentPages(
                     rehypePlugins,
                     beforeDefaultRehypePlugins,
                     beforeDefaultRemarkPlugins,
-                    keepContentTitle: true,
                     staticDir: path.join(siteDir, STATIC_DIR_NAME),
                     // Note that metadataPath must be the same/in-sync as
                     // the path from createData for each MDX.

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

@@ -13,6 +13,7 @@ import LastUpdated from '@theme/LastUpdated';
 import type {Props} from '@theme/DocItem';
 import TOC from '@theme/TOC';
 import EditThisPage from '@theme/EditThisPage';
+import {MainHeading} from '@theme/Heading';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
@@ -49,13 +50,15 @@ function DocItem(props: Props): JSX.Element {
   // See https://github.com/facebook/docusaurus/issues/3362
   const showVersionBadge = versions.length > 1;
 
-  // For meta title, using frontMatter.title in priority over a potential # title found in markdown
-  // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-  const metaTitle = frontMatter.title || title;
+  // We only add a title if:
+  // - user asks to hide it with frontmatter
+  // - the markdown content does not already contain a top-level h1 heading
+  const shouldAddTitle =
+    !hideTitle && typeof DocContent.contentTitle === 'undefined';
 
   return (
     <>
-      <Seo {...{title: metaTitle, description, keywords, image}} />
+      <Seo {...{title, description, keywords, image}} />
 
       <div className="row">
         <div
@@ -72,11 +75,7 @@ function DocItem(props: Props): JSX.Element {
                   </span>
                 </div>
               )}
-              {!hideTitle && (
-                <header>
-                  <h1 className={styles.docTitle}>{title}</h1>
-                </header>
-              )}
+              {shouldAddTitle && <MainHeading>{title}</MainHeading>}
               <div className="markdown">
                 <DocContent />
               </div>

packages/docusaurus-theme-classic/src/theme/DocItem/styles.module.css

@@ -5,11 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docTitle {
-  font-size: 3rem;
-  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
-}
-
 .docItemContainer {
   margin: 0 auto;
   padding: 0 0.5rem;

packages/docusaurus-theme-classic/src/theme/Heading/index.tsx

@@ -16,7 +16,21 @@ import {useThemeConfig} from '@docusaurus/theme-common';
 import './styles.css';
 import styles from './styles.module.css';
 
-const Heading = (Tag: HeadingType): ((props: Props) => JSX.Element) =>
+type HeadingComponent = (props: Props) => JSX.Element;
+
+export const MainHeading: HeadingComponent = function MainHeading({...props}) {
+  return (
+    <header>
+      <h1 {...props} className={styles.h1Heading}>
+        {props.children}
+      </h1>
+    </header>
+  );
+};
+
+const createAnchorHeading = (
+  Tag: HeadingType,
+): ((props: Props) => JSX.Element) =>
   function TargetComponent({id, ...props}) {
     const {
       navbar: {hideOnScroll},
@@ -51,4 +65,8 @@ const Heading = (Tag: HeadingType): ((props: Props) => JSX.Element) =>
     );
   };
 
+const Heading = (headingType: HeadingType): ((props: Props) => JSX.Element) => {
+  return headingType === 'h1' ? MainHeading : createAnchorHeading(headingType);
+};
+
 export default Heading;

packages/docusaurus-theme-classic/src/theme/Heading/styles.module.css

@@ -8,3 +8,8 @@
 .enhancedAnchor {
   top: calc(var(--ifm-navbar-height) * -1 - 0.5rem);
 }
+
+.h1Heading {
+  font-size: 3rem;
+  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
+}

packages/docusaurus-theme-classic/src/types.d.ts

@@ -114,6 +114,7 @@ declare module '@theme/Heading' {
 
   const Heading: (Tag: HeadingType) => (props: Props) => JSX.Element;
   export default Heading;
+  export const MainHeading: (props: Props) => JSX.Element;
 }
 
 declare module '@theme/hooks/useAnnouncementBar' {

packages/docusaurus-utils/src/__tests__/markdownParser.test.ts

@@ -357,22 +357,6 @@ Lorem Ipsum
     });
   });
 
-  test('Should parse markdown h1 title at the top but keep it in content', () => {
-    const markdown = dedent`
-
-          # Markdown Title
-
-          Lorem Ipsum
-
-        `;
-    expect(
-      parseMarkdownContentTitle(markdown, {keepContentTitle: true}),
-    ).toEqual({
-      content: markdown.trim(),
-      contentTitle: 'Markdown Title',
-    });
-  });
-
   test('Should not parse markdown h1 title in the middle of a doc', () => {
     const markdown = dedent`
 
@@ -544,34 +528,6 @@ describe('parseMarkdownString', () => {
     `);
   });
 
-  test('should not warn for duplicate title if keepContentTitle=true', () => {
-    expect(
-      parseMarkdownString(
-        dedent`
-        ---
-        title: Frontmatter title
-        ---
-
-        # Markdown Title
-
-        Some text
-        `,
-        {keepContentTitle: true},
-      ),
-    ).toMatchInlineSnapshot(`
-      Object {
-        "content": "# Markdown Title
-
-      Some text",
-        "contentTitle": "Markdown Title",
-        "excerpt": "Some text",
-        "frontMatter": Object {
-          "title": "Frontmatter title",
-        },
-      }
-    `);
-  });
-
   test('should not warn for duplicate title if markdown title is not at the top', () => {
     expect(
       parseMarkdownString(dedent`
@@ -597,24 +553,6 @@ describe('parseMarkdownString', () => {
     `);
   });
 
-  test('should parse markdown title and keep it in content', () => {
-    expect(
-      parseMarkdownString(
-        dedent`
-          # Markdown Title
-          `,
-        {keepContentTitle: true},
-      ),
-    ).toMatchInlineSnapshot(`
-      Object {
-        "content": "# Markdown Title",
-        "contentTitle": "Markdown Title",
-        "excerpt": undefined,
-        "frontMatter": Object {},
-      }
-    `);
-  });
-
   test('should delete only first heading', () => {
     expect(
       parseMarkdownString(dedent`

packages/docusaurus-utils/src/markdownParser.ts

@@ -78,12 +78,17 @@ export function parseFrontMatter(
   };
 }
 
+// Unwrap possible inline code blocks (# `config.js`)
+function cleanContentTitle(contentTitle: string): string {
+  if (contentTitle.startsWith('`') && contentTitle.endsWith('`')) {
+    return contentTitle.substring(1, contentTitle.length - 1);
+  }
+  return contentTitle;
+}
+
 export function parseMarkdownContentTitle(
   contentUntrimmed: string,
-  options?: {keepContentTitle?: boolean},
 ): {content: string; contentTitle: string | undefined} {
-  const keepContentTitleOption = options?.keepContentTitle ?? false;
-
   const content = contentUntrimmed.trim();
 
   const IMPORT_STATEMENT = /import\s+(([\w*{}\s\n,]+)from\s+)?["'\s]([@\w/_.-]+)["'\s];?|\n/
@@ -106,16 +111,12 @@ export function parseMarkdownContentTitle(
 
   if (!pattern || !title) {
     return {content, contentTitle: undefined};
+  } else {
+    return {
+      content,
+      contentTitle: cleanContentTitle(title.trim()).trim(),
+    };
   }
-
-  const newContent = keepContentTitleOption
-    ? content
-    : content.replace(pattern, '');
-
-  return {
-    content: newContent.trim(),
-    contentTitle: title.trim(),
-  };
 }
 
 type ParsedMarkdown = {
@@ -127,22 +128,14 @@ type ParsedMarkdown = {
 
 export function parseMarkdownString(
   markdownFileContent: string,
-  options?: {
-    keepContentTitle?: boolean;
-  },
 ): ParsedMarkdown {
   try {
-    const keepContentTitle = options?.keepContentTitle ?? false;
-
     const {frontMatter, content: contentWithoutFrontMatter} = parseFrontMatter(
       markdownFileContent,
     );
 
     const {content, contentTitle} = parseMarkdownContentTitle(
       contentWithoutFrontMatter,
-      {
-        keepContentTitle,
-      },
     );
 
     const excerpt = createExcerpt(content);

website/docs/api/docusaurus.config.js.md

@@ -1,10 +1,11 @@
 ---
 id: docusaurus.config.js
-title: docusaurus.config.js
 description: API reference for Docusaurus configuration file.
 slug: /docusaurus.config.js
 ---
 
+# `docusaurus.config.js`
+
 ## Overview {#overview}
 
 `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.