@docusaurus/plugin-content-blog 2.0.0-beta.6f366f4b4 → 2.0.0-beta.7

package/src/authors.ts

@@ -0,0 +1,202 @@
+/**
+ * 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 fs from 'fs-extra';
+import chalk from 'chalk';
+import path from 'path';
+import {Author, BlogContentPaths} from './types';
+import {findFolderContainingFile} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import {
+  BlogPostFrontMatter,
+  BlogPostFrontMatterAuthor,
+  BlogPostFrontMatterAuthors,
+} from './blogFrontMatter';
+import {getContentPathList} from './blogUtils';
+import Yaml from 'js-yaml';
+
+export type AuthorsMap = Record<string, Author>;
+
+const AuthorsMapSchema = Joi.object<AuthorsMap>().pattern(
+  Joi.string(),
+  Joi.object({
+    name: Joi.string().required(),
+    url: URISchema,
+    imageURL: URISchema,
+    title: Joi.string(),
+  })
+    .rename('image_url', 'imageURL')
+    .unknown()
+    .required(),
+);
+
+export function validateAuthorsMapFile(content: unknown): AuthorsMap {
+  return Joi.attempt(content, AuthorsMapSchema);
+}
+
+export async function readAuthorsMapFile(
+  filePath: string,
+): Promise<AuthorsMap | undefined> {
+  if (await fs.pathExists(filePath)) {
+    const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
+    const parse =
+      filePath.endsWith('.yml') || filePath.endsWith('.yaml')
+        ? Yaml.load
+        : JSON.parse;
+    try {
+      const unsafeContent = parse(contentString);
+      return validateAuthorsMapFile(unsafeContent);
+    } catch (e) {
+      // TODO replace later by error cause: see https://v8.dev/features/error-cause
+      console.error(chalk.red('The author list file looks invalid!'));
+      throw e;
+    }
+  }
+  return undefined;
+}
+
+type AuthorsMapParams = {
+  authorsMapPath: string;
+  contentPaths: BlogContentPaths;
+};
+
+export async function getAuthorsMapFilePath({
+  authorsMapPath,
+  contentPaths,
+}: AuthorsMapParams): Promise<string | undefined> {
+  // Useful to load an eventually localize authors map
+  const contentPath = await findFolderContainingFile(
+    getContentPathList(contentPaths),
+    authorsMapPath,
+  );
+
+  if (contentPath) {
+    return path.join(contentPath, authorsMapPath);
+  }
+
+  return undefined;
+}
+
+export async function getAuthorsMap(
+  params: AuthorsMapParams,
+): Promise<AuthorsMap | undefined> {
+  const filePath = await getAuthorsMapFilePath(params);
+  if (!filePath) {
+    return undefined;
+  }
+  try {
+    return await readAuthorsMapFile(filePath);
+  } catch (e) {
+    // TODO replace later by error cause, see https://v8.dev/features/error-cause
+    console.error(
+      chalk.red(`Couldn't read blog authors map at path ${filePath}`),
+    );
+    throw e;
+  }
+}
+
+type AuthorsParam = {
+  frontMatter: BlogPostFrontMatter;
+  authorsMap: AuthorsMap | undefined;
+};
+
+// Legacy v1/early-v2 frontmatter fields
+// We may want to deprecate those in favor of using only frontMatter.authors
+function getFrontMatterAuthorLegacy(
+  frontMatter: BlogPostFrontMatter,
+): BlogPostFrontMatterAuthor | undefined {
+  const name = frontMatter.author;
+  const title = frontMatter.author_title ?? frontMatter.authorTitle;
+  const url = frontMatter.author_url ?? frontMatter.authorURL;
+  const imageURL = frontMatter.author_image_url ?? frontMatter.authorImageURL;
+
+  // Shouldn't we require at least an author name?
+  if (name || title || url || imageURL) {
+    return {
+      name,
+      title,
+      url,
+      imageURL,
+    };
+  }
+
+  return undefined;
+}
+
+function normalizeFrontMatterAuthors(
+  frontMatterAuthors: BlogPostFrontMatterAuthors = [],
+): BlogPostFrontMatterAuthor[] {
+  function normalizeAuthor(
+    authorInput: string | BlogPostFrontMatterAuthor,
+  ): BlogPostFrontMatterAuthor {
+    if (typeof authorInput === 'string') {
+      // Technically, we could allow users to provide an author's name here
+      // IMHO it's better to only support keys here
+      // Reason: a typo in a key would fallback to becoming a name and may end-up un-noticed
+      return {key: authorInput};
+    }
+    return authorInput;
+  }
+
+  return Array.isArray(frontMatterAuthors)
+    ? frontMatterAuthors.map(normalizeAuthor)
+    : [normalizeAuthor(frontMatterAuthors)];
+}
+
+function getFrontMatterAuthors(params: AuthorsParam): Author[] {
+  const {authorsMap} = params;
+  const frontMatterAuthors = normalizeFrontMatterAuthors(
+    params.frontMatter.authors,
+  );
+
+  function getAuthorsMapAuthor(key: string | undefined): Author | undefined {
+    if (key) {
+      if (!authorsMap || Object.keys(authorsMap).length === 0) {
+        throw new Error(`Can't reference blog post authors by a key (such as '${key}') because no authors map file could be loaded.
+Please double-check your blog plugin config (in particular 'authorsMapPath'), ensure the file exists at the configured path, is not empty, and is valid!`);
+      }
+      const author = authorsMap[key];
+      if (!author) {
+        throw Error(`Blog author with key "${key}" not found in the authors map file.
+Valid author keys are:
+${Object.keys(authorsMap)
+  .map((validKey) => `- ${validKey}`)
+  .join('\n')}`);
+      }
+      return author;
+    }
+    return undefined;
+  }
+
+  function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
+    return {
+      // Author def from authorsMap can be locally overridden by frontmatter
+      ...getAuthorsMapAuthor(frontMatterAuthor.key),
+      ...frontMatterAuthor,
+    };
+  }
+
+  return frontMatterAuthors.map(toAuthor);
+}
+
+export function getBlogPostAuthors(params: AuthorsParam): Author[] {
+  const authorLegacy = getFrontMatterAuthorLegacy(params.frontMatter);
+  const authors = getFrontMatterAuthors(params);
+
+  if (authorLegacy) {
+    // Technically, we could allow mixing legacy/authors frontmatter, but do we really want to?
+    if (authors.length > 0) {
+      throw new Error(
+        `To declare blog post authors, use the 'authors' FrontMatter in priority.
+Don't mix 'authors' with other existing 'author_*' FrontMatter. Choose one or the other, not both at the same time.`,
+      );
+    }
+    return [authorLegacy];
+  }
+
+  return authors;
+}

package/src/blogFrontMatter.ts

@@ -5,81 +5,121 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
   validateFrontMatter,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
 } from '@docusaurus/utils-validation';
-import {Tag} from './types';
+import type {FrontMatterTag} from '@docusaurus/utils';
+
+export type BlogPostFrontMatterAuthor = Record<string, unknown> & {
+  key?: string;
+  name?: string;
+  imageURL?: string;
+  url?: string;
+  title?: string;
+};
+
+// All the possible variants that the user can use for convenience
+export type BlogPostFrontMatterAuthors =
+  | string
+  | BlogPostFrontMatterAuthor
+  | (string | BlogPostFrontMatterAuthor)[];
+
+const BlogPostFrontMatterAuthorSchema = Joi.object({
+  key: Joi.string(),
+  name: Joi.string(),
+  title: Joi.string(),
+  url: URISchema,
+  imageURL: Joi.string(),
+})
+  .or('key', 'name')
+  .rename('image_url', 'imageURL', {alias: true});
 
 export type BlogPostFrontMatter = {
+  /* eslint-disable camelcase */
   id?: string;
   title?: string;
   description?: string;
-  tags?: (string | Tag)[];
+  tags?: FrontMatterTag[];
   slug?: string;
   draft?: boolean;
-  date?: Date;
+  date?: Date | string; // Yaml automagically convert some string patterns as Date, but not all
+
+  authors?: BlogPostFrontMatterAuthors;
 
+  // We may want to deprecate those older author frontmatter fields later:
   author?: string;
   author_title?: string;
   author_url?: string;
   author_image_url?: string;
 
-  image?: string;
-  keywords?: string[];
-  hide_table_of_contents?: boolean;
-
   /** @deprecated */
   authorTitle?: string;
+  /** @deprecated */
   authorURL?: string;
+  /** @deprecated */
   authorImageURL?: string;
+
+  image?: string;
+  keywords?: string[];
+  hide_table_of_contents?: boolean;
+  toc_min_heading_level?: number;
+  toc_max_heading_level?: number;
+  /* eslint-enable camelcase */
 };
 
-// NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
-// While the user did not provide those values explicitly
-// We use default values in code instead
-const BlogTagSchema = Joi.alternatives().try(
-  Joi.string().required(),
-  Joi.object<Tag>({
-    label: Joi.string().required(),
-    permalink: Joi.string().required(),
-  }),
-);
+const FrontMatterAuthorErrorMessage =
+  '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).';
 
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
   description: Joi.string().allow(''),
-  tags: Joi.array().items(BlogTagSchema),
+  tags: FrontMatterTagsSchema,
   draft: Joi.boolean(),
   date: Joi.date().raw(),
 
+  // New multi-authors frontmatter:
+  authors: Joi.alternatives()
+    .try(
+      Joi.string(),
+      BlogPostFrontMatterAuthorSchema,
+      Joi.array()
+        .items(Joi.string(), BlogPostFrontMatterAuthorSchema)
+        .messages({
+          'array.sparse': FrontMatterAuthorErrorMessage,
+          'array.includes': FrontMatterAuthorErrorMessage,
+        }),
+    )
+    .messages({
+      'alternatives.match': FrontMatterAuthorErrorMessage,
+    }),
+  // Legacy author frontmatter
   author: Joi.string(),
   author_title: Joi.string(),
   author_url: URISchema,
   author_image_url: URISchema,
-  slug: Joi.string(),
-  image: URISchema,
-  keywords: Joi.array().items(Joi.string().required()),
-  hide_table_of_contents: Joi.boolean(),
-
-  // TODO re-enable warnings later, our v1 blog posts use those older frontmatter fields
+  // TODO enable deprecation warnings later
   authorURL: URISchema,
   // .warning('deprecate.error', { alternative: '"author_url"'}),
   authorTitle: Joi.string(),
   // .warning('deprecate.error', { alternative: '"author_title"'}),
   authorImageURL: URISchema,
   // .warning('deprecate.error', { alternative: '"author_image_url"'}),
-})
-  .unknown()
-  .messages({
-    'deprecate.error':
-      '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
-  });
+
+  slug: Joi.string(),
+  image: URISchema,
+  keywords: Joi.array().items(Joi.string().required()),
+  hide_table_of_contents: Joi.boolean(),
+
+  ...FrontMatterTOCHeadingLevels,
+}).messages({
+  'deprecate.error':
+    '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
+});
 
 export function validateBlogPostFrontMatter(
   frontMatter: Record<string, unknown>,