@docusaurus/plugin-content-blog 0.0.0-6012 → 0.0.0-6016

package/src/index.ts

@@ -34,6 +34,7 @@ import {translateContent, getTranslationFiles} from './translations';
 import {createBlogFeedFiles, createFeedHtmlHeadTags} from './feed';
 
 import {createAllRoutes} from './routes';
+import {checkAuthorsMapPermalinkCollisions, getAuthorsMap} from './authorsMap';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {
@@ -160,11 +161,30 @@ export default async function pluginContentBlog(
         blogTitle,
         blogSidebarTitle,
         pageBasePath,
+        authorsBasePath,
+        authorsMapPath,
       } = options;
 
       const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
       const blogTagsListPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
-      let blogPosts = await generateBlogPosts(contentPaths, context, options);
+
+      const authorsMap = await getAuthorsMap({
+        contentPaths,
+        authorsMapPath,
+        authorsBaseRoutePath: normalizeUrl([
+          baseUrl,
+          routeBasePath,
+          authorsBasePath,
+        ]),
+      });
+      checkAuthorsMapPermalinkCollisions(authorsMap);
+
+      let blogPosts = await generateBlogPosts(
+        contentPaths,
+        context,
+        options,
+        authorsMap,
+      );
       blogPosts = await applyProcessBlogPosts({
         blogPosts,
         processBlogPosts: options.processBlogPosts,
@@ -178,6 +198,7 @@ export default async function pluginContentBlog(
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath,
+          authorsMap,
         };
       }
 
@@ -226,6 +247,7 @@ export default async function pluginContentBlog(
         blogListPaginated,
         blogTags,
         blogTagsListPath,
+        authorsMap,
       };
     },
 
@@ -366,6 +388,7 @@ export default async function pluginContentBlog(
         outDir,
         siteConfig,
         locale: currentLocale,
+        contentPaths,
       });
     },
 

package/src/options.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import path from 'path';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -19,11 +20,20 @@ import type {
   PluginOptions,
   Options,
   FeedType,
+  FeedXSLTOptions,
 } from '@docusaurus/plugin-content-blog';
 import type {OptionValidationContext} from '@docusaurus/types';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
-  feedOptions: {type: ['rss', 'atom'], copyright: '', limit: 20},
+  feedOptions: {
+    type: ['rss', 'atom'],
+    copyright: '',
+    limit: 20,
+    xslt: {
+      rss: null,
+      atom: null,
+    },
+  },
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: true,
@@ -34,6 +44,8 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   showReadingTime: true,
   blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
   blogTagsListComponent: '@theme/BlogTagsListPage',
+  blogAuthorsPostsComponent: '@theme/Blog/Pages/BlogAuthorsPostsPage',
+  blogAuthorsListComponent: '@theme/Blog/Pages/BlogAuthorsListPage',
   blogPostComponent: '@theme/BlogPostPage',
   blogListComponent: '@theme/BlogListPage',
   blogArchiveComponent: '@theme/BlogArchivePage',
@@ -58,9 +70,98 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   processBlogPosts: async () => undefined,
   onInlineTags: 'warn',
   tags: undefined,
+  authorsBasePath: 'authors',
   onInlineAuthors: 'warn',
 };
 
+export const XSLTBuiltInPaths = {
+  rss: path.resolve(__dirname, '..', 'assets', 'rss.xsl'),
+  atom: path.resolve(__dirname, '..', 'assets', 'atom.xsl'),
+};
+
+function normalizeXsltOption(
+  option: string | null | boolean,
+  type: 'rss' | 'atom',
+): string | null {
+  if (typeof option === 'string') {
+    return option;
+  }
+  if (option === true) {
+    return XSLTBuiltInPaths[type];
+  }
+  return null;
+}
+
+function createXSLTFilePathSchema(type: 'atom' | 'rss') {
+  return Joi.alternatives()
+    .try(
+      Joi.string().required(),
+      Joi.boolean()
+        .allow(null, () => undefined)
+        .custom((val) => normalizeXsltOption(val, type)),
+    )
+    .optional()
+    .default(null);
+}
+
+const FeedXSLTOptionsSchema = Joi.alternatives()
+  .try(
+    Joi.object<FeedXSLTOptions>({
+      rss: createXSLTFilePathSchema('rss'),
+      atom: createXSLTFilePathSchema('atom'),
+    }).required(),
+    Joi.boolean()
+      .allow(null, () => undefined)
+      .custom((val) => ({
+        rss: normalizeXsltOption(val, 'rss'),
+        atom: normalizeXsltOption(val, 'atom'),
+      })),
+  )
+  .optional()
+  .custom((val) => {
+    if (val === null) {
+      return {
+        rss: null,
+        atom: null,
+      };
+    }
+    return val;
+  })
+  .default(DEFAULT_OPTIONS.feedOptions.xslt);
+
+const FeedOptionsSchema = Joi.object({
+  type: Joi.alternatives()
+    .try(
+      Joi.array().items(Joi.string().equal('rss', 'atom', 'json')),
+      Joi.alternatives().conditional(
+        Joi.string().equal('all', 'rss', 'atom', 'json'),
+        {
+          then: Joi.custom((val: FeedType | 'all') =>
+            val === 'all' ? ['rss', 'atom', 'json'] : [val],
+          ),
+        },
+      ),
+    )
+    .allow(null)
+    .default(DEFAULT_OPTIONS.feedOptions.type),
+  xslt: FeedXSLTOptionsSchema,
+  title: Joi.string().allow(''),
+  description: Joi.string().allow(''),
+  // Only add default value when user actually wants a feed (type is not null)
+  copyright: Joi.when('type', {
+    is: Joi.any().valid(null),
+    then: Joi.string().optional(),
+    otherwise: Joi.string()
+      .allow('')
+      .default(DEFAULT_OPTIONS.feedOptions.copyright),
+  }),
+  language: Joi.string(),
+  createFeedItems: Joi.function(),
+  limit: Joi.alternatives()
+    .try(Joi.number(), Joi.valid(null), Joi.valid(false))
+    .default(DEFAULT_OPTIONS.feedOptions.limit),
+}).default(DEFAULT_OPTIONS.feedOptions);
+
 const PluginOptionSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
   archiveBasePath: Joi.string()
@@ -82,6 +183,12 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   blogTagsPostsComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogTagsPostsComponent,
   ),
+  blogAuthorsPostsComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogAuthorsPostsComponent,
+  ),
+  blogAuthorsListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogAuthorsListComponent,
+  ),
   blogArchiveComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogArchiveComponent,
   ),
@@ -107,37 +214,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),
-  feedOptions: Joi.object({
-    type: Joi.alternatives()
-      .try(
-        Joi.array().items(Joi.string().equal('rss', 'atom', 'json')),
-        Joi.alternatives().conditional(
-          Joi.string().equal('all', 'rss', 'atom', 'json'),
-          {
-            then: Joi.custom((val: FeedType | 'all') =>
-              val === 'all' ? ['rss', 'atom', 'json'] : [val],
-            ),
-          },
-        ),
-      )
-      .allow(null)
-      .default(DEFAULT_OPTIONS.feedOptions.type),
-    title: Joi.string().allow(''),
-    description: Joi.string().allow(''),
-    // Only add default value when user actually wants a feed (type is not null)
-    copyright: Joi.when('type', {
-      is: Joi.any().valid(null),
-      then: Joi.string().optional(),
-      otherwise: Joi.string()
-        .allow('')
-        .default(DEFAULT_OPTIONS.feedOptions.copyright),
-    }),
-    language: Joi.string(),
-    createFeedItems: Joi.function(),
-    limit: Joi.alternatives()
-      .try(Joi.number(), Joi.valid(null), Joi.valid(false))
-      .default(DEFAULT_OPTIONS.feedOptions.limit),
-  }).default(DEFAULT_OPTIONS.feedOptions),
+  feedOptions: FeedOptionsSchema,
   authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
   readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),
   sortPosts: Joi.string()
@@ -157,6 +234,9 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     .disallow('')
     .allow(null, false)
     .default(() => DEFAULT_OPTIONS.tags),
+  authorsBasePath: Joi.string()
+    .default(DEFAULT_OPTIONS.authorsBasePath)
+    .disallow(''),
   onInlineAuthors: Joi.string()
     .equal('ignore', 'log', 'warn', 'throw')
     .default(DEFAULT_OPTIONS.onInlineAuthors),

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.
      */
@@ -289,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. */
@@ -427,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. */
@@ -471,10 +517,20 @@ 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';
     };
 
+  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
    */
@@ -483,6 +539,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;
     }
   >;
   /**
@@ -508,17 +566,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 +742,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(),
   ];
 }