@docusaurus/plugin-content-blog 3.4.0 → 3.5.0

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`.
      */
@@ -43,7 +37,30 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     authorsImageUrls: (string | undefined)[];
   };
 
-  export type Author = {
+  /**
+   * Note we don't pre-define all possible platforms
+   * Users can add their own custom platforms if needed
+   */
+  export type SocialPlatformKey =
+    | 'twitter'
+    | 'github'
+    | 'linkedin'
+    | 'stackoverflow'
+    | 'x';
+
+  /**
+   * Social platforms of the author.
+   * The record value is usually the fully qualified link of the social profile.
+   * For pre-defined platforms, it's possible to pass a handle instead
+   */
+  export type AuthorSocials = Partial<Record<SocialPlatformKey, string>> & {
+    /**
+     * Unknown keys are allowed: users can pass additional social platforms
+     */
+    [customAuthorSocialPlatform: string]: string;
+  };
+
+  export type AuthorAttributes = {
     /**
      * If `name` doesn't exist, an `imageURL` is expected.
      */
@@ -68,10 +85,48 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      */
     email?: string;
     /**
-     * Unknown keys are allowed, so that we can pass custom fields to authors,
-     * e.g., `twitter`.
+     * Social platforms of the author
+     * Usually displayed as a list of social icon links.
+     */
+    socials?: AuthorSocials;
+    /**
+     * 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.
      */
-    [key: string]: unknown;
+    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;
   };
 
   /**
@@ -165,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.
      */
@@ -260,10 +315,26 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
   }) => string | undefined;
 
   export type FeedType = 'rss' | 'atom' | 'json';
+
+  export type FeedXSLTOptions = {
+    /**
+     * RSS XSLT file path, relative to the blog content folder.
+     * If null, no XSLT file is used and the feed will be displayed as raw XML.
+     */
+    rss: string | null;
+    /**
+     * Atom XSLT file path, relative to the blog content folder.
+     * If null, no XSLT file is used and the feed will be displayed as raw XML.
+     */
+    atom: string | null;
+  };
+
   /**
    * Normalized feed options used within code.
    */
   export type FeedOptions = {
+    /** Enable feeds xslt stylesheets */
+    xslt: FeedXSLTOptions;
     /** If `null`, no feed is generated. */
     type?: FeedType[] | null;
     /** Title of generated feed. */
@@ -398,6 +469,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. */
@@ -442,8 +517,22 @@ 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';
+      /** The behavior of Docusaurus when it finds untruncated blog posts. */
+      onUntruncatedBlogPosts: 'ignore' | 'log' | 'warn' | 'throw';
     };
 
+  export type UserFeedXSLTOptions =
+    | boolean
+    | null
+    | {
+        rss?: string | boolean | null;
+        atom?: string | boolean | null;
+      };
+
   /**
    * Feed options, as provided by user config. `type` accepts `all` as shortcut
    */
@@ -452,6 +541,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     {
       /** Type of feed to be generated. Use `null` to disable generation. */
       type?: FeedOptions['type'] | 'all' | FeedType;
+      /** User-provided XSLT config for feeds, un-normalized */
+      xslt?: UserFeedXSLTOptions;
     }
   >;
   /**
@@ -469,6 +560,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 = {
@@ -476,17 +568,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;
   };
@@ -647,6 +744,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

@@ -5,7 +5,14 @@
  * 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 {
+  AuthorItemProp,
+  AuthorWithKey,
+  BlogPost,
+  BlogSidebar,
+  BlogTag,
+  BlogTags,
+} from '@docusaurus/plugin-content-blog';
 
 export function toTagsProp({blogTags}: {blogTags: BlogTags}): TagsListItem[] {
   return Object.values(blogTags)
@@ -34,3 +41,34 @@ export function toTagProp({
     unlisted: tag.unlisted,
   };
 }
+
+export function toAuthorItemProp({
+  author,
+  count,
+}: {
+  author: AuthorWithKey;
+  count: number;
+}): AuthorItemProp {
+  return {
+    ...author,
+    count,
+  };
+}
+
+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,
+    })),
+  };
+}

package/src/routes.ts

@@ -11,9 +11,15 @@ import {
   docuHash,
   aliasedSitePathToRelativePath,
 } from '@docusaurus/utils';
-import {shouldBeListed} from './blogUtils';
+import {paginateBlogPosts, shouldBeListed} from './blogUtils';
 
-import {toTagProp, toTagsProp} from './props';
+import {
+  toAuthorItemProp,
+  toBlogSidebarProp,
+  toTagProp,
+  toTagsProp,
+} from './props';
+import {groupBlogPostsByAuthorKey} from './authors';
 import type {
   PluginContentLoadedActions,
   RouteConfig,
@@ -26,7 +32,7 @@ import type {
   BlogContent,
   PluginOptions,
   BlogPost,
-  BlogSidebar,
+  AuthorWithKey,
 } from '@docusaurus/plugin-content-blog';
 
 type CreateAllRoutesParam = {
@@ -55,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;
@@ -69,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);
@@ -88,17 +106,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);
   }
@@ -107,6 +121,7 @@ export async function buildAllRoutes({
     const blogMetadata: BlogMetadata = {
       blogBasePath: normalizeUrl([baseUrl, routeBasePath]),
       blogTitle,
+      authorsListPath,
     };
     const modulePath = await createData(
       `blogMetadata-${pluginId}.json`,
@@ -254,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(),
   ];
 }

package/src/client/index.ts

@@ -1,20 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import useRouteContext from '@docusaurus/useRouteContext';
-import type {BlogMetadata} from '@docusaurus/plugin-content-blog';
-
-export function useBlogMetadata(): BlogMetadata {
-  const routeContext = useRouteContext();
-  const blogMetadata = routeContext?.data?.blogMetadata;
-  if (!blogMetadata) {
-    throw new Error(
-      "useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context",
-    );
-  }
-  return blogMetadata as BlogMetadata;
-}