fix(v2): fix title logic (meta vs heading) + ignore fixed anchor id s…

…yntax (#4688) * parseMarkdownContentTitle should ignore {#my-anchor-id} syntax * use frontMatter.title in priority for page meta title * parseMarkdownString should ignore fixed anchor ids syntax * docs: make the distinction between headingTitle + metaTitle more clear + add useful todo * docs: make the distinction between headingTitle + metaTitle more clear + add useful todo * writeHeadingIds should ignore top-level md title like "# Title" => we are not supposed to create anchor links for h1 headers * update tests * fix doc tests
facebook · Apr 27, 2021 · 8ebbc17 · 8ebbc17
1 parent bca7965
commit 8ebbc17
Show file tree

Hide file tree

Showing 9 changed files with 124 additions and 77 deletions.
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
@@ -146,7 +146,7 @@ Object {
   \\"unversionedId\\": \\"foo/bar\\",
   \\"id\\": \\"foo/bar\\",
   \\"isDocsHomePage\\": false,
-  \\"title\\": \\"Bar\\",
+  \\"title\\": \\"Remarkable\\",
   \\"description\\": \\"This is custom description\\",
   \\"source\\": \\"@site/docs/foo/bar.md\\",
   \\"sourceDirName\\": \\"foo\\",
@@ -182,7 +182,7 @@ Object {
   },
   \\"sidebar\\": \\"docs\\",
   \\"previous\\": {
-    \\"title\\": \\"Bar\\",
+    \\"title\\": \\"Remarkable\\",
     \\"permalink\\": \\"/docs/foo/bar\\"
   },
   \\"next\\": {
@@ -396,7 +396,7 @@ Object {
             \\"items\\": [
               {
                 \\"type\\": \\"link\\",
-                \\"label\\": \\"Bar\\",
+                \\"label\\": \\"Remarkable\\",
                 \\"href\\": \\"/docs/foo/bar\\"
               },
               {

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts
@@ -181,7 +181,7 @@ describe('simple site', () => {
       isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       slug: '/foo/bar',
-      title: 'Bar',
+      title: 'Remarkable',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',
@@ -255,7 +255,7 @@ describe('simple site', () => {
       isDocsHomePage: true,
       permalink: '/docs/',
       slug: '/',
-      title: 'Bar',
+      title: 'Remarkable',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
@@ -309,7 +309,7 @@ describe('simple website', () => {
         'foo',
         'bar.md',
       ),
-      title: 'Bar',
+      title: 'Remarkable',
       description: 'This is custom description',
       frontMatter: {
         description: 'This is custom description',

diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts
@@ -121,9 +121,7 @@ export function processDocMetadata({
     frontMatter: unsafeFrontMatter,
     contentTitle,
     excerpt,
-  } = parseMarkdownString(content, {
-    source,
-  });
+  } = parseMarkdownString(content);
   const frontMatter = validateDocFrontMatter(unsafeFrontMatter);
 
   const {
@@ -205,8 +203,11 @@ export function processDocMetadata({
         numberPrefixParser: options.numberPrefixParser,
       });
 
-  // Default title is the id.
-  const title: string = frontMatter.title ?? contentTitle ?? baseID;
+  // 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 description: string = frontMatter.description ?? excerpt ?? '';
 
@@ -245,7 +246,7 @@ export function processDocMetadata({
     unversionedId,
     id,
     isDocsHomePage,
-    title,
+    title: headingTitle,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,

diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx
@@ -24,15 +24,13 @@ import {
 
 function DocItem(props: Props): JSX.Element {
   const {content: DocContent} = props;
+  const {metadata, frontMatter} = DocContent;
   const {
-    metadata,
-    frontMatter: {
-      image,
-      keywords,
-      hide_title: hideTitle,
-      hide_table_of_contents: hideTableOfContents,
-    },
-  } = DocContent;
+    image,
+    keywords,
+    hide_title: hideTitle,
+    hide_table_of_contents: hideTableOfContents,
+  } = frontMatter;
   const {
     description,
     title,
@@ -51,9 +49,13 @@ 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;
+
   return (
     <>
-      <Seo {...{title, description, keywords, image}} />
+      <Seo {...{title: metaTitle, description, keywords, image}} />
 
       <div className="row">
         <div