feat(blog): group sidebar items by year (themeConfig.blog.sidebar.groupByYear) (#10252)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-blog/src/__tests__/props.test.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {toTagsProp} from '../props';
+import {fromPartial} from '@total-typescript/shoehorn';
+import {toBlogSidebarProp, toTagsProp} from '../props';
+import type {BlogPost} from '@docusaurus/plugin-content-blog';
 
 describe('toTagsProp', () => {
   type Tags = Parameters<typeof toTagsProp>[0]['blogTags'];
@@ -68,3 +70,59 @@ describe('toTagsProp', () => {
     ]);
   });
 });
+
+describe('toBlogSidebarProp', () => {
+  it('creates sidebar prop', () => {
+    const blogPosts: BlogPost[] = [
+      fromPartial({
+        id: '1',
+        metadata: {
+          title: 'title 1',
+          permalink: '/blog/blog-1',
+          unlisted: false,
+          date: '2021-01-01',
+          frontMatter: {toto: 42},
+          authors: [{name: 'author'}],
+          source: 'xyz',
+          hasTruncateMarker: true,
+        },
+      }),
+      fromPartial({
+        id: '2',
+        metadata: {
+          title: 'title 2',
+          permalink: '/blog/blog-2',
+          unlisted: true,
+          date: '2024-01-01',
+          frontMatter: {hello: 'world'},
+          tags: [{label: 'tag1', permalink: '/tag1', inline: false}],
+        },
+      }),
+    ];
+
+    const sidebarProp = toBlogSidebarProp({
+      blogSidebarTitle: 'sidebar title',
+      blogPosts,
+    });
+
+    expect(sidebarProp).toMatchInlineSnapshot(`
+      {
+        "items": [
+          {
+            "date": "2021-01-01",
+            "permalink": "/blog/blog-1",
+            "title": "title 1",
+            "unlisted": false,
+          },
+          {
+            "date": "2024-01-01",
+            "permalink": "/blog/blog-2",
+            "title": "title 2",
+            "unlisted": true,
+          },
+        ],
+        "title": "sidebar title",
+      }
+    `);
+  });
+});

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -473,6 +473,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     title: string;
     permalink: string;
     unlisted: boolean;
+    date: Date | string;
   };
 
   export type BlogSidebar = {

packages/docusaurus-plugin-content-blog/src/props.ts

@@ -5,7 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type {TagsListItem, TagModule} from '@docusaurus/utils';
-import type {BlogTag, BlogTags} from '@docusaurus/plugin-content-blog';
+import type {
+  BlogPost,
+  BlogSidebar,
+  BlogTag,
+  BlogTags,
+} from '@docusaurus/plugin-content-blog';
 
 export function toTagsProp({blogTags}: {blogTags: BlogTags}): TagsListItem[] {
   return Object.values(blogTags)
@@ -34,3 +39,21 @@ export function toTagProp({
     unlisted: tag.unlisted,
   };
 }
+
+export function toBlogSidebarProp({
+  blogSidebarTitle,
+  blogPosts,
+}: {
+  blogSidebarTitle: string;
+  blogPosts: BlogPost[];
+}): BlogSidebar {
+  return {
+    title: blogSidebarTitle,
+    items: blogPosts.map((blogPost) => ({
+      title: blogPost.metadata.title,
+      permalink: blogPost.metadata.permalink,
+      unlisted: blogPost.metadata.unlisted,
+      date: blogPost.metadata.date,
+    })),
+  };
+}

packages/docusaurus-plugin-content-blog/src/routes.ts

@@ -13,7 +13,7 @@ import {
 } from '@docusaurus/utils';
 import {shouldBeListed} from './blogUtils';
 
-import {toTagProp, toTagsProp} from './props';
+import {toBlogSidebarProp, toTagProp, toTagsProp} from './props';
 import type {
   PluginContentLoadedActions,
   RouteConfig,
@@ -26,7 +26,6 @@ import type {
   BlogContent,
   PluginOptions,
   BlogPost,
-  BlogSidebar,
 } from '@docusaurus/plugin-content-blog';
 
 type CreateAllRoutesParam = {
@@ -88,17 +87,13 @@ export async function buildAllRoutes({
       : blogPosts.slice(0, options.blogSidebarCount);
 
   async function createSidebarModule() {
-    const sidebar: BlogSidebar = {
-      title: blogSidebarTitle,
-      items: sidebarBlogPosts.map((blogPost) => ({
-        title: blogPost.metadata.title,
-        permalink: blogPost.metadata.permalink,
-        unlisted: blogPost.metadata.unlisted,
-      })),
-    };
+    const sidebarProp = toBlogSidebarProp({
+      blogSidebarTitle,
+      blogPosts: sidebarBlogPosts,
+    });
     const modulePath = await createData(
       `blog-post-list-prop-${pluginId}.json`,
-      sidebar,
+      sidebarProp,
     );
     return aliasedSource(modulePath);
   }