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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "0.0.0-5983",
+  "version": "0.0.0-5985",
   "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-5985",
+    "@docusaurus/logger": "0.0.0-5985",
+    "@docusaurus/mdx-loader": "0.0.0-5985",
+    "@docusaurus/types": "0.0.0-5985",
+    "@docusaurus/utils": "0.0.0-5985",
+    "@docusaurus/utils-common": "0.0.0-5985",
+    "@docusaurus/utils-validation": "0.0.0-5985",
     "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": "01e2896b49cfb78bed86b3c8854728377792a90a"
 }

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';
     };
 
   /**