feat(blog): Add frontMatter.sidebar_label (#10729)

facebook · Nov 29, 2024 · a995865 · a995865
1 parent df6f53a
commit a995865
Show file tree

Hide file tree

Showing 7 changed files with 34 additions and 6 deletions.
diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts
@@ -79,6 +79,7 @@ describe('validateBlogPostFrontMatter description', () => {
     prefix: 'description',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+      {description: undefined},
       {description: ''},
       {description: 'description'},
     ],
@@ -90,6 +91,7 @@ describe('validateBlogPostFrontMatter title', () => {
     prefix: 'title',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+      {title: undefined},
       {title: ''},
       {title: 'title'},
     ],
@@ -103,14 +105,33 @@ describe('validateBlogPostFrontMatter title', () => {
 describe('validateBlogPostFrontMatter title_meta', () => {
   testField({
     prefix: 'title_meta',
-    validFrontMatters: [{title: ''}, {title_meta: 'title'}],
+    validFrontMatters: [
+      {title_meta: undefined},
+      {title_meta: ''},
+      {title_meta: 'title'},
+    ],
     invalidFrontMatters: [
       [{title_meta: null}, 'must be a string'],
       [{title_meta: false}, 'must be a string'],
     ],
   });
 });
 
+describe('validateBlogPostFrontMatter sidebar_label', () => {
+  testField({
+    prefix: 'title_meta',
+    validFrontMatters: [
+      {sidebar_label: undefined},
+      {sidebar_label: ''},
+      {sidebar_label: 'title'},
+    ],
+    invalidFrontMatters: [
+      [{sidebar_label: null}, 'must be a string'],
+      [{sidebar_label: false}, 'must be a string'],
+    ],
+  });
+});
+
 describe('validateBlogPostFrontMatter id', () => {
   testField({
     prefix: 'id',

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/props.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/props.test.ts
@@ -94,7 +94,7 @@ describe('toBlogSidebarProp', () => {
           permalink: '/blog/blog-2',
           unlisted: true,
           date: '2024-01-01',
-          frontMatter: {hello: 'world'},
+          frontMatter: {hello: 'world', sidebar_label: 'title 2 (custom)'},
           tags: [{label: 'tag1', permalink: '/tag1', inline: false}],
         },
       }),
@@ -117,7 +117,7 @@ describe('toBlogSidebarProp', () => {
           {
             "date": "2024-01-01",
             "permalink": "/blog/blog-2",
-            "title": "title 2",
+            "title": "title 2 (custom)",
             "unlisted": true,
           },
         ],

diff --git a/packages/docusaurus-plugin-content-blog/src/frontMatter.ts b/packages/docusaurus-plugin-content-blog/src/frontMatter.ts
@@ -33,7 +33,8 @@ const FrontMatterAuthorErrorMessage =
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
-  title_meta: Joi.string(),
+  title_meta: Joi.string().allow(''),
+  sidebar_label: Joi.string().allow(''),
   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
@@ -145,14 +145,17 @@ declare module '@docusaurus/plugin-content-blog' {
     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}
      */
     description?: string;
+    /**
+     * Will override the default excerpt.
+     */
+    sidebar_label?: string;
     /**
      * Front matter tags, unnormalized.
      * @see {@link BlogPostMetadata.tags}

diff --git a/packages/docusaurus-plugin-content-blog/src/props.ts b/packages/docusaurus-plugin-content-blog/src/props.ts
@@ -65,7 +65,8 @@ export function toBlogSidebarProp({
   return {
     title: blogSidebarTitle,
     items: blogPosts.map((blogPost) => ({
-      title: blogPost.metadata.title,
+      title:
+        blogPost.metadata.frontMatter.sidebar_label ?? blogPost.metadata.title,
       permalink: blogPost.metadata.permalink,
       unlisted: blogPost.metadata.unlisted,
       date: blogPost.metadata.date,

diff --git a/website/_dogfooding/_blog tests/2023-08-05.mdx b/website/_dogfooding/_blog tests/2023-08-05.mdx
@@ -1,6 +1,7 @@
 ---
 title: Ensure heading anchor slugs respect GitHub emoji behavior
 date: 2023-08-05
+sidebar_label: 'Ensure heading... (custom label)'
 ---
 
 ## :smiley: This is a friendly header

diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx
@@ -250,6 +250,7 @@ Accepted fields:
 | `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. |
 | `author_title` | `string` | `undefined` | ⚠️ Prefer using `authors`. A description of the author. |
 | `title` | `string` | Markdown title | The blog post title. |
+| `sidebar_label` | `string` | `title` | A custom label for the blog sidebar, replacing the default one (`title`). |
 | `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time. |
 | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. Strings can be a reference to keys of a [tags file](#tags-file) (usually `tags.yml`) |
 | `draft` | `boolean` | `false` | Draft blog posts will only be available during development. |