diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts index f5ca63694c65..2ef1184eadd6 100644 --- 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,7 +105,11 @@ 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'], @@ -111,6 +117,21 @@ describe('validateBlogPostFrontMatter title_meta', () => { }); }); +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 index 4bd03a56cb3f..b0267b8a43bc 100644 --- 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 index 0e822258290b..244eb565f90a 100644 --- 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({ 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 index 1606aaa5f5e8..9e8c3850add1 100644 --- 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,7 +145,6 @@ 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; /** @@ -153,6 +152,10 @@ declare module '@docusaurus/plugin-content-blog' { * @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 index df7afbb42563..b8fac4d1925d 100644 --- 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 index 180d6c6db846..a7409557478d 100644 --- 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 index 17f545d19329..a3d7a3f7421f 100644 --- 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. |