@docusaurus/plugin-content-blog 3.4.0 → 3.5.1

package/lib/routes.js

@@ -6,22 +6,28 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildAllRoutes = exports.createAllRoutes = void 0;
+exports.createAllRoutes = createAllRoutes;
+exports.buildAllRoutes = buildAllRoutes;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const blogUtils_1 = require("./blogUtils");
 const props_1 = require("./props");
+const authors_1 = require("./authors");
 async function createAllRoutes(param) {
     const routes = await buildAllRoutes(param);
     routes.forEach(param.actions.addRoute);
 }
-exports.createAllRoutes = createAllRoutes;
 async function buildAllRoutes({ baseUrl, content, actions, options, aliasedSource, }) {
-    const { blogListComponent, blogPostComponent, blogTagsListComponent, blogTagsPostsComponent, blogArchiveComponent, routeBasePath, archiveBasePath, blogTitle, } = options;
+    const { blogListComponent, blogPostComponent, blogTagsListComponent, blogAuthorsListComponent, blogAuthorsPostsComponent, blogTagsPostsComponent, blogArchiveComponent, routeBasePath, archiveBasePath, blogTitle, authorsBasePath, postsPerPage, blogDescription, } = options;
     const pluginId = options.id;
     const { createData } = actions;
-    const { blogSidebarTitle, blogPosts, blogListPaginated, blogTags, blogTagsListPath, } = content;
+    const { blogSidebarTitle, blogPosts, blogListPaginated, blogTags, blogTagsListPath, authorsMap, } = content;
+    const authorsListPath = (0, utils_1.normalizeUrl)([
+        baseUrl,
+        routeBasePath,
+        authorsBasePath,
+    ]);
     const listedBlogPosts = blogPosts.filter(blogUtils_1.shouldBeListed);
     const blogPostsById = lodash_1.default.keyBy(blogPosts, (post) => post.id);
     function getBlogPostById(id) {
@@ -35,21 +41,18 @@ async function buildAllRoutes({ baseUrl, content, actions, options, aliasedSourc
         ? blogPosts
         : blogPosts.slice(0, options.blogSidebarCount);
     async function createSidebarModule() {
-        const sidebar = {
-            title: blogSidebarTitle,
-            items: sidebarBlogPosts.map((blogPost) => ({
-                title: blogPost.metadata.title,
-                permalink: blogPost.metadata.permalink,
-                unlisted: blogPost.metadata.unlisted,
-            })),
-        };
-        const modulePath = await createData(`blog-post-list-prop-${pluginId}.json`, sidebar);
+        const sidebarProp = (0, props_1.toBlogSidebarProp)({
+            blogSidebarTitle,
+            blogPosts: sidebarBlogPosts,
+        });
+        const modulePath = await createData(`blog-post-list-prop-${pluginId}.json`, sidebarProp);
         return aliasedSource(modulePath);
     }
     async function createBlogMetadataModule() {
         const blogMetadata = {
             blogBasePath: (0, utils_1.normalizeUrl)([baseUrl, routeBasePath]),
             blogTitle,
+            authorsListPath,
         };
         const modulePath = await createData(`blogMetadata-${pluginId}.json`, blogMetadata);
         return aliasedSource(modulePath);
@@ -172,11 +175,76 @@ async function buildAllRoutes({ baseUrl, content, actions, options, aliasedSourc
         const tagsPaginatedRoutes = Object.values(blogTags).flatMap(createTagPaginatedRoutes);
         return [tagsListRoute, ...tagsPaginatedRoutes];
     }
+    function createAuthorsRoutes() {
+        if (authorsMap === undefined || Object.keys(authorsMap).length === 0) {
+            return [];
+        }
+        const blogPostsByAuthorKey = (0, authors_1.groupBlogPostsByAuthorKey)({
+            authorsMap,
+            blogPosts,
+        });
+        const authors = Object.values(authorsMap);
+        return [
+            createAuthorListRoute(),
+            ...authors.flatMap(createAuthorPaginatedRoute),
+        ];
+        function createAuthorListRoute() {
+            return {
+                path: authorsListPath,
+                component: blogAuthorsListComponent,
+                exact: true,
+                modules: {
+                    sidebar: sidebarModulePath,
+                },
+                props: {
+                    authors: authors.map((author) => (0, props_1.toAuthorItemProp)({
+                        author,
+                        count: blogPostsByAuthorKey[author.key]?.length ?? 0,
+                    })),
+                },
+                context: {
+                    blogMetadata: blogMetadataModulePath,
+                },
+            };
+        }
+        function createAuthorPaginatedRoute(author) {
+            const authorBlogPosts = blogPostsByAuthorKey[author.key] ?? [];
+            if (!author.page) {
+                return [];
+            }
+            const pages = (0, blogUtils_1.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: (0, props_1.toAuthorItemProp)({ author, count: authorBlogPosts.length }),
+                        listMetadata: metadata,
+                    },
+                    context: {
+                        blogMetadata: blogMetadataModulePath,
+                    },
+                };
+            });
+        }
+    }
     return [
         ...createBlogPostRoutes(),
         ...createBlogPostsPaginatedRoutes(),
         ...createTagsRoutes(),
         ...createArchiveRoute(),
+        ...createAuthorsRoutes(),
     ];
 }
-exports.buildAllRoutes = buildAllRoutes;

package/lib/translations.d.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference path="../src/plugin-content-blog.d.ts" />
 import type { TranslationFile } from '@docusaurus/types';
 import type { PluginOptions, BlogContent } from '@docusaurus/plugin-content-blog';
 export declare function getTranslationFiles(options: PluginOptions): TranslationFile[];

package/lib/translations.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.translateContent = exports.getTranslationFiles = void 0;
+exports.getTranslationFiles = getTranslationFiles;
+exports.translateContent = translateContent;
 function translateListPage(blogListPaginated, translations) {
     return blogListPaginated.map((page) => {
         const { items, metadata } = page;
@@ -41,7 +42,6 @@ function getTranslationFiles(options) {
         },
     ];
 }
-exports.getTranslationFiles = getTranslationFiles;
 function translateContent(content, translationFiles) {
     const { content: optionsTranslations } = translationFiles[0];
     return {
@@ -50,4 +50,3 @@ function translateContent(content, translationFiles) {
         blogListPaginated: translateListPage(content.blogListPaginated, optionsTranslations),
     };
 }
-exports.translateContent = translateContent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,14 +31,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.4.0",
-    "@docusaurus/logger": "3.4.0",
-    "@docusaurus/mdx-loader": "3.4.0",
-    "@docusaurus/types": "3.4.0",
-    "@docusaurus/utils": "3.4.0",
-    "@docusaurus/utils-common": "3.4.0",
-    "@docusaurus/utils-validation": "3.4.0",
-    "cheerio": "^1.0.0-rc.12",
+    "@docusaurus/core": "3.5.1",
+    "@docusaurus/logger": "3.5.1",
+    "@docusaurus/mdx-loader": "3.5.1",
+    "@docusaurus/theme-common": "3.5.1",
+    "@docusaurus/types": "3.5.1",
+    "@docusaurus/utils": "3.5.1",
+    "@docusaurus/utils-common": "3.5.1",
+    "@docusaurus/utils-validation": "3.5.1",
+    "cheerio": "1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
@@ -50,6 +51,7 @@
     "webpack": "^5.88.1"
   },
   "peerDependencies": {
+    "@docusaurus/plugin-content-docs": "*",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
@@ -57,7 +59,8 @@
     "node": ">=18.0"
   },
   "devDependencies": {
-    "@total-typescript/shoehorn": "^0.1.2"
+    "@total-typescript/shoehorn": "^0.1.2",
+    "tree-node-cli": "^1.6.0"
   },
-  "gitHead": "49e9a2143274a8dd795659b417b470bc42abbd6e"
+  "gitHead": "5acbc57bd62f3f808ef72007cd67d4c410d13829"
 }

package/src/authors.ts

@@ -5,66 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {getDataFileData, normalizeUrl} from '@docusaurus/utils';
-import {Joi, URISchema} from '@docusaurus/utils-validation';
-import type {BlogContentPaths} from './types';
+import _ from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
 import type {
   Author,
+  AuthorsMap,
+  BlogPost,
   BlogPostFrontMatter,
   BlogPostFrontMatterAuthor,
-  BlogPostFrontMatterAuthors,
 } from '@docusaurus/plugin-content-blog';
 
-export type AuthorsMap = {[authorKey: string]: Author};
-
-const AuthorsMapSchema = Joi.object<AuthorsMap>()
-  .pattern(
-    Joi.string(),
-    Joi.object({
-      name: Joi.string(),
-      url: URISchema,
-      imageURL: URISchema,
-      title: Joi.string(),
-      email: Joi.string(),
-    })
-      .rename('image_url', 'imageURL')
-      .or('name', 'imageURL')
-      .unknown()
-      .required()
-      .messages({
-        'object.base':
-          '{#label} should be an author object containing properties like name, title, and imageURL.',
-        'any.required':
-          '{#label} cannot be undefined. It should be an author object containing properties like name, title, and imageURL.',
-      }),
-  )
-  .messages({
-    'object.base':
-      "The authors map file should contain an object where each entry contains an author key and the corresponding author's data.",
-  });
-
-export function validateAuthorsMap(content: unknown): AuthorsMap {
-  const {error, value} = AuthorsMapSchema.validate(content);
-  if (error) {
-    throw error;
-  }
-  return value;
-}
-
-export async function getAuthorsMap(params: {
-  authorsMapPath: string;
-  contentPaths: BlogContentPaths;
-}): Promise<AuthorsMap | undefined> {
-  return getDataFileData(
-    {
-      filePath: params.authorsMapPath,
-      contentPaths: params.contentPaths,
-      fileType: 'authors map',
-    },
-    validateAuthorsMap,
-  );
-}
-
 type AuthorsParam = {
   frontMatter: BlogPostFrontMatter;
   authorsMap: AuthorsMap | undefined;
@@ -85,6 +35,7 @@ function normalizeImageUrl({
 
 // Legacy v1/early-v2 front matter fields
 // We may want to deprecate those in favor of using only frontMatter.authors
+// TODO Docusaurus v4: remove this legacy front matter
 function getFrontMatterAuthorLegacy({
   baseUrl,
   frontMatter,
@@ -106,37 +57,40 @@ function getFrontMatterAuthorLegacy({
       title,
       url,
       imageURL,
+      // legacy front matter authors do not have an author key/page
+      key: null,
+      page: null,
     };
   }
 
   return undefined;
 }
 
-function normalizeFrontMatterAuthors(
-  frontMatterAuthors: BlogPostFrontMatterAuthors = [],
-): BlogPostFrontMatterAuthor[] {
-  function normalizeAuthor(
-    authorInput: string | Author,
-  ): BlogPostFrontMatterAuthor {
-    if (typeof authorInput === 'string') {
-      // Technically, we could allow users to provide an author's name here, but
-      // we only support keys, otherwise, a typo in a key would fallback to
-      // becoming a name and may end up unnoticed
-      return {key: authorInput};
+function getFrontMatterAuthors(params: AuthorsParam): Author[] {
+  const {authorsMap, frontMatter, baseUrl} = params;
+  return normalizeFrontMatterAuthors().map(toAuthor);
+
+  function normalizeFrontMatterAuthors(): BlogPostFrontMatterAuthor[] {
+    if (frontMatter.authors === undefined) {
+      return [];
     }
-    return authorInput;
-  }
 
-  return Array.isArray(frontMatterAuthors)
-    ? frontMatterAuthors.map(normalizeAuthor)
-    : [normalizeAuthor(frontMatterAuthors)];
-}
+    function normalizeAuthor(
+      authorInput: string | BlogPostFrontMatterAuthor,
+    ): BlogPostFrontMatterAuthor {
+      if (typeof authorInput === 'string') {
+        // We could allow users to provide an author's name here, but we only
+        // support keys, otherwise, a typo in a key would fall back to
+        // becoming a name and may end up unnoticed
+        return {key: authorInput};
+      }
+      return authorInput;
+    }
 
-function getFrontMatterAuthors(params: AuthorsParam): Author[] {
-  const {authorsMap} = params;
-  const frontMatterAuthors = normalizeFrontMatterAuthors(
-    params.frontMatter.authors,
-  );
+    return Array.isArray(frontMatter.authors)
+      ? frontMatter.authors.map(normalizeAuthor)
+      : [normalizeAuthor(frontMatter.authors)];
+  }
 
   function getAuthorsMapAuthor(key: string | undefined): Author | undefined {
     if (key) {
@@ -158,36 +112,29 @@ ${Object.keys(authorsMap)
   }
 
   function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
-    return {
+    const author = {
       // Author def from authorsMap can be locally overridden by front matter
       ...getAuthorsMapAuthor(frontMatterAuthor.key),
       ...frontMatterAuthor,
     };
-  }
-
-  return frontMatterAuthors.map(toAuthor);
-}
 
-function fixAuthorImageBaseURL(
-  authors: Author[],
-  {baseUrl}: {baseUrl: string},
-) {
-  return authors.map((author) => ({
-    ...author,
-    imageURL: normalizeImageUrl({imageURL: author.imageURL, baseUrl}),
-  }));
+    return {
+      ...author,
+      key: author.key ?? null,
+      page: author.page ?? null,
+      imageURL: normalizeImageUrl({imageURL: author.imageURL, baseUrl}),
+    };
+  }
 }
 
 export function getBlogPostAuthors(params: AuthorsParam): Author[] {
   const authorLegacy = getFrontMatterAuthorLegacy(params);
   const authors = getFrontMatterAuthors(params);
 
-  const updatedAuthors = fixAuthorImageBaseURL(authors, params);
-
   if (authorLegacy) {
     // Technically, we could allow mixing legacy/authors front matter, but do we
     // really want to?
-    if (updatedAuthors.length > 0) {
+    if (authors.length > 0) {
       throw new Error(
         `To declare blog post authors, use the 'authors' front matter in priority.
 Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.`,
@@ -196,5 +143,21 @@ Don't mix 'authors' with other existing 'author_*' front matter. Choose one or t
     return [authorLegacy];
   }
 
-  return updatedAuthors;
+  return authors;
+}
+
+/**
+ * Group blog posts by author key
+ * Blog posts with only inline authors are ignored
+ */
+export function groupBlogPostsByAuthorKey({
+  blogPosts,
+  authorsMap,
+}: {
+  blogPosts: BlogPost[];
+  authorsMap: AuthorsMap | undefined;
+}): Record<string, BlogPost[]> {
+  return _.mapValues(authorsMap, (author, key) =>
+    blogPosts.filter((p) => p.metadata.authors.some((a) => a.key === key)),
+  );
 }

package/src/authorsMap.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 _ from 'lodash';
+import {readDataFile, normalizeUrl} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import {AuthorSocialsSchema, normalizeSocials} from './authorsSocials';
+import type {BlogContentPaths} from './types';
+import type {
+  Author,
+  AuthorAttributes,
+  AuthorPage,
+  AuthorsMap,
+} from '@docusaurus/plugin-content-blog';
+
+type AuthorInput = AuthorAttributes & {
+  page?: boolean | AuthorPage;
+};
+
+export type AuthorsMapInput = {[authorKey: string]: AuthorInput};
+
+const AuthorPageSchema = Joi.object<AuthorPage>({
+  permalink: Joi.string().required(),
+});
+
+const AuthorsMapInputSchema = Joi.object<AuthorsMapInput>()
+  .pattern(
+    Joi.string(),
+    Joi.object({
+      name: Joi.string(),
+      url: URISchema,
+      imageURL: URISchema,
+      title: Joi.string(),
+      email: Joi.string(),
+      page: Joi.alternatives(Joi.bool(), AuthorPageSchema),
+      socials: AuthorSocialsSchema,
+      description: Joi.string(),
+    })
+      .rename('image_url', 'imageURL')
+      .or('name', 'imageURL')
+      .unknown()
+      .required()
+      .messages({
+        'object.base':
+          '{#label} should be an author object containing properties like name, title, and imageURL.',
+        'any.required':
+          '{#label} cannot be undefined. It should be an author object containing properties like name, title, and imageURL.',
+      }),
+  )
+  .messages({
+    'object.base':
+      "The authors map file should contain an object where each entry contains an author key and the corresponding author's data.",
+  });
+
+export function checkAuthorsMapPermalinkCollisions(
+  authorsMap: AuthorsMap | undefined,
+): void {
+  if (!authorsMap) {
+    return;
+  }
+
+  const permalinkCounts = _(authorsMap)
+    // Filter to keep only authors with a page
+    .pickBy((author) => !!author.page)
+    // Group authors by their permalink
+    .groupBy((author) => author.page?.permalink)
+    // Filter to keep only permalinks with more than one author
+    .pickBy((authors) => authors.length > 1)
+    // Transform the object into an array of [permalink, authors] pairs
+    .toPairs()
+    .value();
+
+  if (permalinkCounts.length > 0) {
+    const errorMessage = permalinkCounts
+      .map(
+        ([permalink, authors]) =>
+          `Permalink: ${permalink}\nAuthors: ${authors
+            .map((author) => author.name || 'Unknown')
+            .join(', ')}`,
+      )
+      .join('\n');
+
+    throw new Error(
+      `The following permalinks are duplicated:\n${errorMessage}`,
+    );
+  }
+}
+
+function normalizeAuthor({
+  authorsBaseRoutePath,
+  authorKey,
+  author,
+}: {
+  authorsBaseRoutePath: string;
+  authorKey: string;
+  author: AuthorInput;
+}): Author & {key: string} {
+  function getAuthorPage(): AuthorPage | null {
+    if (!author.page) {
+      return null;
+    }
+    const slug =
+      author.page === true ? _.kebabCase(authorKey) : author.page.permalink;
+    return {
+      permalink: normalizeUrl([authorsBaseRoutePath, slug]),
+    };
+  }
+
+  return {
+    ...author,
+    key: authorKey,
+    page: getAuthorPage(),
+    socials: author.socials ? normalizeSocials(author.socials) : undefined,
+  };
+}
+
+function normalizeAuthorsMap({
+  authorsBaseRoutePath,
+  authorsMapInput,
+}: {
+  authorsBaseRoutePath: string;
+  authorsMapInput: AuthorsMapInput;
+}): AuthorsMap {
+  return _.mapValues(authorsMapInput, (author, authorKey) => {
+    return normalizeAuthor({authorsBaseRoutePath, authorKey, author});
+  });
+}
+
+export function validateAuthorsMapInput(content: unknown): AuthorsMapInput {
+  const {error, value} = AuthorsMapInputSchema.validate(content);
+  if (error) {
+    throw error;
+  }
+  return value;
+}
+
+async function getAuthorsMapInput(params: {
+  authorsMapPath: string;
+  contentPaths: BlogContentPaths;
+}): Promise<AuthorsMapInput | undefined> {
+  const content = await readDataFile({
+    filePath: params.authorsMapPath,
+    contentPaths: params.contentPaths,
+  });
+  return content ? validateAuthorsMapInput(content) : undefined;
+}
+
+export async function getAuthorsMap(params: {
+  authorsMapPath: string;
+  authorsBaseRoutePath: string;
+  contentPaths: BlogContentPaths;
+}): Promise<AuthorsMap | undefined> {
+  const authorsMapInput = await getAuthorsMapInput(params);
+  if (!authorsMapInput) {
+    return undefined;
+  }
+  const authorsMap = normalizeAuthorsMap({authorsMapInput, ...params});
+  return authorsMap;
+}
+
+export function validateAuthorsMap(content: unknown): AuthorsMapInput {
+  const {error, value} = AuthorsMapInputSchema.validate(content);
+  if (error) {
+    throw error;
+  }
+  return value;
+}

package/src/authorsProblems.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 _ from 'lodash';
+import logger from '@docusaurus/logger';
+import type {Author, PluginOptions} from '@docusaurus/plugin-content-blog';
+
+export function reportAuthorsProblems(params: {
+  authors: Author[];
+  blogSourceRelative: string;
+  options: Pick<PluginOptions, 'onInlineAuthors' | 'authorsMapPath'>;
+}): void {
+  reportInlineAuthors(params);
+  reportDuplicateAuthors(params);
+}
+
+export function reportInlineAuthors({
+  authors,
+  blogSourceRelative,
+  options: {onInlineAuthors, authorsMapPath},
+}: {
+  authors: Author[];
+  blogSourceRelative: string;
+  options: Pick<PluginOptions, 'onInlineAuthors' | 'authorsMapPath'>;
+}): void {
+  if (onInlineAuthors === 'ignore') {
+    return;
+  }
+  const inlineAuthors = authors.filter((author) => !author.key);
+  if (inlineAuthors.length > 0) {
+    logger.report(onInlineAuthors)(
+      logger.interpolate`Some blog authors used in path=${blogSourceRelative} are not defined in path=${authorsMapPath}:
+- ${inlineAuthors.map(authorToString).join('\n- ')}
+
+Note that we recommend to declare authors once in a path=${authorsMapPath} file and reference them by key in blog posts front matter to avoid author info duplication.
+But if you want to allow inline blog authors, you can disable this message by setting onInlineAuthors: 'ignore' in your blog plugin options.
+More info at url=${'https://docusaurus.io/docs/blog'}
+`,
+    );
+  }
+}
+
+export function reportDuplicateAuthors({
+  authors,
+  blogSourceRelative,
+}: {
+  authors: Author[];
+  blogSourceRelative: string;
+}): void {
+  const duplicateAuthors = _(authors)
+    // for now we only check for predefined authors duplicates
+    .filter((author) => !!author.key)
+    .groupBy((author) => author.key)
+    .pickBy((authorsByKey) => authorsByKey.length > 1)
+    // We only keep the "test" of all the duplicate groups
+    // The first author of a group is not really a duplicate...
+    .flatMap(([, ...rest]) => rest)
+    .value();
+
+  if (duplicateAuthors.length > 0) {
+    throw new Error(logger.interpolate`Duplicate blog post authors were found in blog post path=${blogSourceRelative} front matter:
+- ${duplicateAuthors.map(authorToString).join('\n- ')}`);
+  }
+}
+
+function authorToString(author: Author) {
+  return JSON.stringify(author);
+}