@docusaurus/plugin-content-blog 0.0.0-5983 → 0.0.0-5987

package/lib/authorsProblems.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { Author, PluginOptions } from '@docusaurus/plugin-content-blog';
+export declare function reportAuthorsProblems(params: {
+    authors: Author[];
+    blogSourceRelative: string;
+    options: Pick<PluginOptions, 'onInlineAuthors' | 'authorsMapPath'>;
+}): void;
+export declare function reportInlineAuthors({ authors, blogSourceRelative, options: { onInlineAuthors, authorsMapPath }, }: {
+    authors: Author[];
+    blogSourceRelative: string;
+    options: Pick<PluginOptions, 'onInlineAuthors' | 'authorsMapPath'>;
+}): void;
+export declare function reportDuplicateAuthors({ authors, blogSourceRelative, }: {
+    authors: Author[];
+    blogSourceRelative: string;
+}): void;

package/lib/authorsProblems.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportAuthorsProblems = reportAuthorsProblems;
+exports.reportInlineAuthors = reportInlineAuthors;
+exports.reportDuplicateAuthors = reportDuplicateAuthors;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+function reportAuthorsProblems(params) {
+    reportInlineAuthors(params);
+    reportDuplicateAuthors(params);
+}
+function reportInlineAuthors({ authors, blogSourceRelative, options: { onInlineAuthors, authorsMapPath }, }) {
+    if (onInlineAuthors === 'ignore') {
+        return;
+    }
+    const inlineAuthors = authors.filter((author) => !author.key);
+    if (inlineAuthors.length > 0) {
+        logger_1.default.report(onInlineAuthors)(logger_1.default.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'}
+`);
+    }
+}
+function reportDuplicateAuthors({ authors, blogSourceRelative, }) {
+    const duplicateAuthors = (0, lodash_1.default)(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_1.default.interpolate `Duplicate blog post authors were found in blog post path=${blogSourceRelative} front matter:
+- ${duplicateAuthors.map(authorToString).join('\n- ')}`);
+    }
+}
+function authorToString(author) {
+    return JSON.stringify(author);
+}

package/lib/blogUtils.js

@@ -23,6 +23,7 @@ const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const frontMatter_1 = require("./frontMatter");
 const authors_1 = require("./authors");
+const authorsProblems_1 = require("./authorsProblems");
 function truncate(fileString, truncateMarker) {
     return fileString.split(truncateMarker, 1).shift();
 }
@@ -196,6 +197,11 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
         tagsRouteBasePath,
     ]);
     const authors = (0, authors_1.getBlogPostAuthors)({ authorsMap, frontMatter, baseUrl });
+    (0, authorsProblems_1.reportAuthorsProblems)({
+        authors,
+        blogSourceRelative,
+        options,
+    });
     const tags = (0, utils_1.normalizeTags)({
         options,
         source: blogSourceRelative,

package/lib/options.js

@@ -46,6 +46,7 @@ exports.DEFAULT_OPTIONS = {
     processBlogPosts: async () => undefined,
     onInlineTags: 'warn',
     tags: undefined,
+    onInlineAuthors: 'warn',
 };
 const PluginOptionSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
@@ -123,6 +124,9 @@ const PluginOptionSchema = utils_validation_1.Joi.object({
         .disallow('')
         .allow(null, false)
         .default(() => exports.DEFAULT_OPTIONS.tags),
+    onInlineAuthors: utils_validation_1.Joi.string()
+        .equal('ignore', 'log', 'warn', 'throw')
+        .default(exports.DEFAULT_OPTIONS.onInlineAuthors),
 }).default(exports.DEFAULT_OPTIONS);
 function validateOptions({ validate, options, }) {
     const validatedOptions = validate(PluginOptionSchema, options);

package/lib/props.d.ts

@@ -5,7 +5,7 @@
  * 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 declare function toTagsProp({ blogTags }: {
     blogTags: BlogTags;
 }): TagsListItem[];
@@ -13,3 +13,7 @@ export declare function toTagProp({ blogTagsListPath, tag, }: {
     blogTagsListPath: string;
     tag: BlogTag;
 }): TagModule;
+export declare function toBlogSidebarProp({ blogSidebarTitle, blogPosts, }: {
+    blogSidebarTitle: string;
+    blogPosts: BlogPost[];
+}): BlogSidebar;

package/lib/props.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toTagsProp = toTagsProp;
 exports.toTagProp = toTagProp;
+exports.toBlogSidebarProp = toBlogSidebarProp;
 function toTagsProp({ blogTags }) {
     return Object.values(blogTags)
         .filter((tag) => !tag.unlisted)
@@ -22,3 +23,14 @@ function toTagProp({ blogTagsListPath, tag, }) {
         unlisted: tag.unlisted,
     };
 }
+function toBlogSidebarProp({ blogSidebarTitle, blogPosts, }) {
+    return {
+        title: blogSidebarTitle,
+        items: blogPosts.map((blogPost) => ({
+            title: blogPost.metadata.title,
+            permalink: blogPost.metadata.permalink,
+            unlisted: blogPost.metadata.unlisted,
+            date: blogPost.metadata.date,
+        })),
+    };
+}

package/lib/routes.js

@@ -35,15 +35,11 @@ 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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "0.0.0-5983",
+  "version": "0.0.0-5987",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,13 +31,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5983",
-    "@docusaurus/logger": "0.0.0-5983",
-    "@docusaurus/mdx-loader": "0.0.0-5983",
-    "@docusaurus/types": "0.0.0-5983",
-    "@docusaurus/utils": "0.0.0-5983",
-    "@docusaurus/utils-common": "0.0.0-5983",
-    "@docusaurus/utils-validation": "0.0.0-5983",
+    "@docusaurus/core": "0.0.0-5987",
+    "@docusaurus/logger": "0.0.0-5987",
+    "@docusaurus/mdx-loader": "0.0.0-5987",
+    "@docusaurus/types": "0.0.0-5987",
+    "@docusaurus/utils": "0.0.0-5987",
+    "@docusaurus/utils-common": "0.0.0-5987",
+    "@docusaurus/utils-validation": "0.0.0-5987",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
@@ -59,5 +59,5 @@
   "devDependencies": {
     "@total-typescript/shoehorn": "^0.1.2"
   },
-  "gitHead": "303ced3b8c9e4b7674a42ebbbe73d24debeb211a"
+  "gitHead": "89b1afe104ab4f3fb765d2ba875d34753f77efe8"
 }

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);
+}

package/src/blogUtils.ts

@@ -30,6 +30,7 @@ import {
 import {getTagsFile} from '@docusaurus/utils-validation';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import {reportAuthorsProblems} from './authorsProblems';
 import type {TagsFile} from '@docusaurus/utils';
 import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
@@ -317,7 +318,13 @@ async function processBlogSourceFile(
     routeBasePath,
     tagsRouteBasePath,
   ]);
+
   const authors = getBlogPostAuthors({authorsMap, frontMatter, baseUrl});
+  reportAuthorsProblems({
+    authors,
+    blogSourceRelative,
+    options,
+  });
 
   const tags = normalizeTags({
     options,

package/src/options.ts

@@ -58,6 +58,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   processBlogPosts: async () => undefined,
   onInlineTags: 'warn',
   tags: undefined,
+  onInlineAuthors: 'warn',
 };
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -156,6 +157,9 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     .disallow('')
     .allow(null, false)
     .default(() => DEFAULT_OPTIONS.tags),
+  onInlineAuthors: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onInlineAuthors),
 }).default(DEFAULT_OPTIONS);
 
 export function validateOptions({

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

@@ -44,6 +44,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
   };
 
   export type Author = {
+    key?: string; // TODO temporary, need refactor
+
     /**
      * If `name` doesn't exist, an `imageURL` is expected.
      */
@@ -442,6 +444,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
        *  (filter, modify, delete, etc...).
        */
       processBlogPosts: ProcessBlogPostsFn;
+      /** The behavior of Docusaurus when it finds inline authors. */
+      onInlineAuthors: 'ignore' | 'log' | 'warn' | 'throw';
     };
 
   /**
@@ -469,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 = {

package/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,
+    })),
+  };
+}

package/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);
   }