feat(blog): Add frontMatter.title_meta to override title for SEO (#10586)

ilg-ul · slorber · web-flow · commit 5cf2c39836f9 · 2024-10-31T11:59:35.000+01:00
Co-authored-by: sebastien &lt;lorber.sebastien@gmail.com&gt;
diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts
@@ -93,6 +93,21 @@ describe('validateBlogPostFrontMatter title', () => {
       {title: ''},
       {title: 'title'},
     ],
+    invalidFrontMatters: [
+      [{title: null}, 'must be a string'],
+      [{title: false}, 'must be a string'],
+    ],
+  });
+});
+
+describe('validateBlogPostFrontMatter title_meta', () => {
+  testField({
+    prefix: 'title_meta',
+    validFrontMatters: [{title: ''}, {title_meta: 'title'}],
+    invalidFrontMatters: [
+      [{title_meta: null}, 'must be a string'],
+      [{title_meta: false}, 'must be a string'],
+    ],
   });
 });
 
diff --git a/packages/docusaurus-plugin-content-blog/src/frontMatter.ts b/packages/docusaurus-plugin-content-blog/src/frontMatter.ts
@@ -33,6 +33,7 @@ const FrontMatterAuthorErrorMessage =
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
+  title_meta: Joi.string(),
   description: Joi.string().allow(''),
   tags: FrontMatterTagsSchema,
   date: Joi.date().raw(),
diff --git a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts
@@ -143,6 +143,11 @@ declare module '@docusaurus/plugin-content-blog' {
      * @see {@link BlogPostMetadata.title}
      */
     title?: string;
+    /**
+     * Will be used for SEO page metadata and override BlogPostMetadata.title.
+     * @see {@link BlogPostMetadata.title_meta}
+     */
+    title_meta?: string;
     /**
      * Will override the default excerpt.
      * @see {@link BlogPostMetadata.description}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx
@@ -17,7 +17,7 @@ export default function BlogPostPageMetadata(): JSX.Element {
   const image = assets.image ?? frontMatter.image;
   return (
     <PageMetadata
-      title={title}
+      title={frontMatter.title_meta ?? title}
       description={description}
       keywords={keywords}
       image={image}>
diff --git a/website/docs/api/plugins/plugin-content-docs.mdx b/website/docs/api/plugins/plugin-content-docs.mdx
@@ -278,6 +278,7 @@ Accepted fields:
 | --- | --- | --- | --- |
 | `id` | `string` | file path (including folders, without the extension) | A unique document ID. |
 | `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
+| `title_meta` | `string` | `frontMatter.title` | The SEO metadata title of your document used in `<head>` for `<title>` and `og:title`. Permits to override `frontMatter.title` when the displayed title and SEO title should be different. |
 | `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar/autogenerated#autogenerated-sidebar-metadata). |
