@docusaurus/plugin-content-blog 0.0.0-6010 → 0.0.0-6014

package/src/plugin-content-blog.d.ts

@@ -22,13 +22,7 @@ declare module '@docusaurus/plugin-content-blog' {
 
   export type Assets = {
     /**
-     * If `metadata.yarn workspace website typecheck
-4
-yarn workspace v1.22.19yarn workspace website typecheck
-4
-yarn workspace v1.22.19yarn workspace website typecheck
-4
-yarn workspace v1.22.19image` is a collocated image path, this entry will be the
+     * If `metadata.image` is a collocated image path, this entry will be the
      * bundler-generated image path. Otherwise, it's empty, and the image URL
      * should be accessed through `frontMatter.image`.
      */
@@ -66,9 +60,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     [customAuthorSocialPlatform: string]: string;
   };
 
-  export type Author = {
-    key?: string; // TODO temporary, need refactor
-
+  export type AuthorAttributes = {
     /**
      * If `name` doesn't exist, an `imageURL` is expected.
      */
@@ -98,11 +90,45 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      */
     socials?: AuthorSocials;
     /**
-     * Unknown keys are allowed, so that we can pass custom fields to authors,
+     * Description of the author.
+     */
+    description?: string;
+    /**
+     * Unknown keys are allowed, so that we can pass custom fields to authors.
      */
     [customAuthorAttribute: string]: unknown;
   };
 
+  /**
+   * Metadata of the author's page, if it exists.
+   */
+  export type AuthorPage = {permalink: string};
+
+  /**
+   * Normalized author metadata.
+   */
+  export type Author = AuthorAttributes & {
+    /**
+     * Author key, if the author was loaded from the authors map.
+     * `null` means the author was declared inline.
+     */
+    key: string | null;
+    /**
+     * Metadata of the author's page.
+     * `null` means the author doesn't have a dedicated author page.
+     */
+    page: AuthorPage | null;
+  };
+
+  /** Authors coming from the AuthorsMap always have a key */
+  export type AuthorWithKey = Author & {key: string};
+
+  /** What the authors list page should know about each author. */
+  export type AuthorItemProp = AuthorWithKey & {
+    /** Number of blog posts with this author. */
+    count: number;
+  };
+
   /**
    * Everything is partial/unnormalized, because front matter is always
    * preserved as-is. Default values will be applied when generating metadata
@@ -194,7 +220,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     last_update?: FrontMatterLastUpdate;
   };
 
-  export type BlogPostFrontMatterAuthor = Author & {
+  export type BlogPostFrontMatterAuthor = AuthorAttributes & {
     /**
      * Will be normalized into the `imageURL` prop.
      */
@@ -427,6 +453,10 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
       blogTagsListComponent: string;
       /** Root component of the "posts containing tag" page. */
       blogTagsPostsComponent: string;
+      /** Root component of the authors list page. */
+      blogAuthorsListComponent: string;
+      /** Root component of the "posts containing author" page. */
+      blogAuthorsPostsComponent: string;
       /** Root component of the blog archive page. */
       blogArchiveComponent: string;
       /** Blog page title for better SEO. */
@@ -471,6 +501,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
        *  (filter, modify, delete, etc...).
        */
       processBlogPosts: ProcessBlogPostsFn;
+      /* Base path for the authors page */
+      authorsBasePath: string;
       /** The behavior of Docusaurus when it finds inline authors. */
       onInlineAuthors: 'ignore' | 'log' | 'warn' | 'throw';
     };
@@ -508,17 +540,22 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     items: BlogSidebarItem[];
   };
 
+  export type AuthorsMap = {[authorKey: string]: AuthorWithKey};
+
   export type BlogContent = {
     blogSidebarTitle: string;
     blogPosts: BlogPost[];
     blogListPaginated: BlogPaginated[];
     blogTags: BlogTags;
     blogTagsListPath: string;
+    authorsMap?: AuthorsMap;
   };
 
   export type BlogMetadata = {
     /** the path to the base of the blog */
     blogBasePath: string;
+    /** the path to the authors list page */
+    authorsListPath: string;
     /** title of the overall blog */
     blogTitle: string;
   };
@@ -679,6 +716,47 @@ declare module '@theme/BlogTagsListPage' {
   export default function BlogTagsListPage(props: Props): JSX.Element;
 }
 
+declare module '@theme/Blog/Pages/BlogAuthorsListPage' {
+  import type {
+    AuthorItemProp,
+    BlogSidebar,
+  } from '@docusaurus/plugin-content-blog';
+
+  export interface Props {
+    /** Blog sidebar. */
+    readonly sidebar: BlogSidebar;
+    /** All authors declared in this blog. */
+    readonly authors: AuthorItemProp[];
+  }
+
+  export default function BlogAuthorsListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/Blog/Pages/BlogAuthorsPostsPage' {
+  import type {Content} from '@theme/BlogPostPage';
+  import type {
+    AuthorItemProp,
+    BlogSidebar,
+    BlogPaginatedMetadata,
+  } from '@docusaurus/plugin-content-blog';
+
+  export interface Props {
+    /** Blog sidebar. */
+    readonly sidebar: BlogSidebar;
+    /** Metadata of this author. */
+    readonly author: AuthorItemProp;
+    /** Looks exactly the same as the posts list page */
+    readonly listMetadata: BlogPaginatedMetadata;
+    /**
+     * Array of blog posts included on this page. Every post's metadata is also
+     * available.
+     */
+    readonly items: readonly {readonly content: Content}[];
+  }
+
+  export default function BlogAuthorsPostsPage(props: Props): JSX.Element;
+}
+
 declare module '@theme/BlogTagsPostsPage' {
   import type {Content} from '@theme/BlogPostPage';
   import type {

package/src/props.ts

@@ -6,6 +6,8 @@
  */
 import type {TagsListItem, TagModule} from '@docusaurus/utils';
 import type {
+  AuthorItemProp,
+  AuthorWithKey,
   BlogPost,
   BlogSidebar,
   BlogTag,
@@ -40,6 +42,19 @@ export function toTagProp({
   };
 }
 
+export function toAuthorItemProp({
+  author,
+  count,
+}: {
+  author: AuthorWithKey;
+  count: number;
+}): AuthorItemProp {
+  return {
+    ...author,
+    count,
+  };
+}
+
 export function toBlogSidebarProp({
   blogSidebarTitle,
   blogPosts,

package/src/routes.ts

@@ -11,9 +11,15 @@ import {
   docuHash,
   aliasedSitePathToRelativePath,
 } from '@docusaurus/utils';
-import {shouldBeListed} from './blogUtils';
+import {paginateBlogPosts, shouldBeListed} from './blogUtils';
 
-import {toBlogSidebarProp, toTagProp, toTagsProp} from './props';
+import {
+  toAuthorItemProp,
+  toBlogSidebarProp,
+  toTagProp,
+  toTagsProp,
+} from './props';
+import {groupBlogPostsByAuthorKey} from './authors';
 import type {
   PluginContentLoadedActions,
   RouteConfig,
@@ -26,6 +32,7 @@ import type {
   BlogContent,
   PluginOptions,
   BlogPost,
+  AuthorWithKey,
 } from '@docusaurus/plugin-content-blog';
 
 type CreateAllRoutesParam = {
@@ -54,11 +61,16 @@ export async function buildAllRoutes({
     blogListComponent,
     blogPostComponent,
     blogTagsListComponent,
+    blogAuthorsListComponent,
+    blogAuthorsPostsComponent,
     blogTagsPostsComponent,
     blogArchiveComponent,
     routeBasePath,
     archiveBasePath,
     blogTitle,
+    authorsBasePath,
+    postsPerPage,
+    blogDescription,
   } = options;
   const pluginId = options.id!;
   const {createData} = actions;
@@ -68,8 +80,15 @@ export async function buildAllRoutes({
     blogListPaginated,
     blogTags,
     blogTagsListPath,
+    authorsMap,
   } = content;
 
+  const authorsListPath = normalizeUrl([
+    baseUrl,
+    routeBasePath,
+    authorsBasePath,
+  ]);
+
   const listedBlogPosts = blogPosts.filter(shouldBeListed);
 
   const blogPostsById = _.keyBy(blogPosts, (post) => post.id);
@@ -102,6 +121,7 @@ export async function buildAllRoutes({
     const blogMetadata: BlogMetadata = {
       blogBasePath: normalizeUrl([baseUrl, routeBasePath]),
       blogTitle,
+      authorsListPath,
     };
     const modulePath = await createData(
       `blogMetadata-${pluginId}.json`,
@@ -249,10 +269,85 @@ export async function buildAllRoutes({
     return [tagsListRoute, ...tagsPaginatedRoutes];
   }
 
+  function createAuthorsRoutes(): RouteConfig[] {
+    if (authorsMap === undefined || Object.keys(authorsMap).length === 0) {
+      return [];
+    }
+
+    const blogPostsByAuthorKey = groupBlogPostsByAuthorKey({
+      authorsMap,
+      blogPosts,
+    });
+    const authors = Object.values(authorsMap);
+
+    return [
+      createAuthorListRoute(),
+      ...authors.flatMap(createAuthorPaginatedRoute),
+    ];
+
+    function createAuthorListRoute(): RouteConfig {
+      return {
+        path: authorsListPath,
+        component: blogAuthorsListComponent,
+        exact: true,
+        modules: {
+          sidebar: sidebarModulePath,
+        },
+        props: {
+          authors: authors.map((author) =>
+            toAuthorItemProp({
+              author,
+              count: blogPostsByAuthorKey[author.key]?.length ?? 0,
+            }),
+          ),
+        },
+        context: {
+          blogMetadata: blogMetadataModulePath,
+        },
+      };
+    }
+
+    function createAuthorPaginatedRoute(author: AuthorWithKey): RouteConfig[] {
+      const authorBlogPosts = blogPostsByAuthorKey[author.key] ?? [];
+      if (!author.page) {
+        return [];
+      }
+
+      const pages = paginateBlogPosts({
+        blogPosts: authorBlogPosts,
+        basePageUrl: author.page.permalink,
+        blogDescription,
+        blogTitle,
+        pageBasePath: authorsBasePath,
+        postsPerPageOption: postsPerPage,
+      });
+
+      return pages.map(({metadata, items}) => {
+        return {
+          path: metadata.permalink,
+          component: blogAuthorsPostsComponent,
+          exact: true,
+          modules: {
+            items: blogPostItemsModule(items),
+            sidebar: sidebarModulePath,
+          },
+          props: {
+            author: toAuthorItemProp({author, count: authorBlogPosts.length}),
+            listMetadata: metadata,
+          },
+          context: {
+            blogMetadata: blogMetadataModulePath,
+          },
+        };
+      });
+    }
+  }
+
   return [
     ...createBlogPostRoutes(),
     ...createBlogPostsPaginatedRoutes(),
     ...createTagsRoutes(),
     ...createArchiveRoute(),
+    ...createAuthorsRoutes(),
   ];
 }