@docusaurus/plugin-content-blog 2.0.0-beta.0e652730d → 2.0.0-beta.10

package/src/__tests__/index.test.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable @typescript-eslint/no-non-null-assertion */
-
 import fs from 'fs-extra';
 import path from 'path';
 import pluginContentBlog from '../index';
@@ -14,6 +12,7 @@ import {DocusaurusConfig, LoadContext, I18n} from '@docusaurus/types';
 import {PluginOptionSchema} from '../pluginOptionSchema';
 import {PluginOptions, EditUrlFunction, BlogPost} from '../types';
 import {Joi} from '@docusaurus/utils-validation';
+import {posixPath} from '@docusaurus/utils';
 
 function findByTitle(
   blogPosts: BlogPost[],
@@ -60,7 +59,7 @@ describe('loadBlog', () => {
 
   const BaseEditUrl = 'https://baseEditUrl.com/edit';
 
-  const getBlogPosts = async (
+  const getPlugin = async (
     siteDir: string,
     pluginOptions: Partial<PluginOptions> = {},
     i18n: I18n = DefaultI18N,
@@ -71,7 +70,7 @@ describe('loadBlog', () => {
       baseUrl: '/',
       url: 'https://docusaurus.io',
     } as DocusaurusConfig;
-    const plugin = pluginContentBlog(
+    return pluginContentBlog(
       {
         siteDir,
         siteConfig,
@@ -84,11 +83,32 @@ describe('loadBlog', () => {
         ...pluginOptions,
       }),
     );
-    const {blogPosts} = (await plugin.loadContent!())!;
+  };
 
+  const getBlogPosts = async (
+    siteDir: string,
+    pluginOptions: Partial<PluginOptions> = {},
+    i18n: I18n = DefaultI18N,
+  ) => {
+    const plugin = await getPlugin(siteDir, pluginOptions, i18n);
+    const {blogPosts} = (await plugin.loadContent!())!;
     return blogPosts;
   };
 
+  test('getPathsToWatch', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const plugin = await getPlugin(siteDir);
+    const pathsToWatch = plugin.getPathsToWatch!();
+    const relativePathsToWatch = pathsToWatch.map((p) =>
+      posixPath(path.relative(siteDir, p)),
+    );
+    expect(relativePathsToWatch).toEqual([
+      'blog/authors.yml',
+      'i18n/en/docusaurus-plugin-content-blog/**/*.{md,mdx}',
+      'blog/**/*.{md,mdx}',
+    ]);
+  });
+
   test('simple website', async () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
     const blogPosts = await getBlogPosts(siteDir);
@@ -103,6 +123,7 @@ describe('loadBlog', () => {
       source: path.posix.join('@site', PluginPath, 'date-matter.md'),
       title: 'date-matter',
       description: `date inside front matter`,
+      authors: [],
       date: new Date('2019-01-01'),
       formattedDate: 'January 1, 2019',
       prevItem: undefined,
@@ -128,6 +149,16 @@ describe('loadBlog', () => {
       ),
       title: 'Happy 1st Birthday Slash! (translated)',
       description: `Happy birthday! (translated)`,
+      authors: [
+        {
+          name: 'Yangshun Tay (translated)',
+        },
+        {
+          key: 'slorber',
+          name: 'Sébastien Lorber (translated)',
+          title: 'Docusaurus maintainer (translated)',
+        },
+      ],
       date: new Date('2018-12-14'),
       formattedDate: 'December 14, 2018',
       tags: [],
@@ -148,6 +179,7 @@ describe('loadBlog', () => {
       source: path.posix.join('@site', PluginPath, 'complex-slug.md'),
       title: 'Complex Slug',
       description: `complex url slug`,
+      authors: [],
       prevItem: undefined,
       nextItem: {
         permalink: '/blog/simple/slug',
@@ -169,6 +201,14 @@ describe('loadBlog', () => {
       source: path.posix.join('@site', PluginPath, 'simple-slug.md'),
       title: 'Simple Slug',
       description: `simple url slug`,
+      authors: [
+        {
+          name: 'Sébastien Lorber',
+          title: 'Docusaurus maintainer',
+          url: 'https://sebastienlorber.com',
+          imageURL: undefined,
+        },
+      ],
       prevItem: undefined,
       nextItem: {
         permalink: '/blog/draft',
@@ -190,6 +230,7 @@ describe('loadBlog', () => {
       source: path.posix.join('@site', PluginPath, 'heading-as-title.md'),
       title: 'some heading',
       description: '',
+      authors: [],
       date: new Date('2019-01-02'),
       formattedDate: 'January 2, 2019',
       prevItem: undefined,
@@ -205,23 +246,29 @@ describe('loadBlog', () => {
   test('simple website blog dates localized', async () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
     const blogPostsFrench = await getBlogPosts(siteDir, {}, getI18n('fr'));
-    expect(blogPostsFrench).toHaveLength(6);
+    expect(blogPostsFrench).toHaveLength(8);
     expect(blogPostsFrench[0].metadata.formattedDate).toMatchInlineSnapshot(
-      `"16 août 2020"`,
+      `"6 mars 2021"`,
     );
     expect(blogPostsFrench[1].metadata.formattedDate).toMatchInlineSnapshot(
-      `"15 août 2020"`,
+      `"5 mars 2021"`,
     );
     expect(blogPostsFrench[2].metadata.formattedDate).toMatchInlineSnapshot(
-      `"27 février 2020"`,
+      `"16 août 2020"`,
     );
     expect(blogPostsFrench[3].metadata.formattedDate).toMatchInlineSnapshot(
-      `"2 janvier 2019"`,
+      `"15 août 2020"`,
     );
     expect(blogPostsFrench[4].metadata.formattedDate).toMatchInlineSnapshot(
-      `"1 janvier 2019"`,
+      `"27 février 2020"`,
     );
     expect(blogPostsFrench[5].metadata.formattedDate).toMatchInlineSnapshot(
+      `"2 janvier 2019"`,
+    );
+    expect(blogPostsFrench[6].metadata.formattedDate).toMatchInlineSnapshot(
+      `"1 janvier 2019"`,
+    );
+    expect(blogPostsFrench[7].metadata.formattedDate).toMatchInlineSnapshot(
       `"14 décembre 2018"`,
     );
   });
@@ -251,7 +298,8 @@ describe('loadBlog', () => {
       expect(blogPost.metadata.editUrl).toEqual(hardcodedEditUrl);
     });
 
-    expect(editUrlFunction).toHaveBeenCalledTimes(6);
+    expect(editUrlFunction).toHaveBeenCalledTimes(8);
+
     expect(editUrlFunction).toHaveBeenCalledWith({
       blogDirPath: 'blog',
       blogPath: 'date-matter.md',
@@ -264,6 +312,18 @@ describe('loadBlog', () => {
       permalink: '/blog/draft',
       locale: 'en',
     });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'mdx-blog-post.mdx',
+      permalink: '/blog/mdx-blog-post',
+      locale: 'en',
+    });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'mdx-require-blog-post.mdx',
+      permalink: '/blog/mdx-require-blog-post',
+      locale: 'en',
+    });
     expect(editUrlFunction).toHaveBeenCalledWith({
       blogDirPath: 'blog',
       blogPath: 'complex-slug.md',
@@ -325,6 +385,7 @@ describe('loadBlog', () => {
       source: noDateSource,
       title: 'no date',
       description: `no date`,
+      authors: [],
       date: noDateSourceBirthTime,
       formattedDate,
       tags: [],
@@ -333,4 +394,15 @@ describe('loadBlog', () => {
       truncated: false,
     });
   });
+
+  test('test ascending sort direction of blog post', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const normalOrder = await getBlogPosts(siteDir);
+    const reversedOrder = await getBlogPosts(siteDir, {
+      sortPosts: 'ascending',
+    });
+    expect(normalOrder.reverse().map((x) => x.metadata.date)).toEqual(
+      reversedOrder.map((x) => x.metadata.date),
+    );
+  });
 });

package/src/__tests__/pluginOptionSchema.test.ts

@@ -29,7 +29,7 @@ test('should accept correctly defined user options', () => {
   const {value, error} = PluginOptionSchema.validate(userOptions);
   expect(value).toEqual({
     ...userOptions,
-    feedOptions: {type: ['rss'], title: 'myTitle'},
+    feedOptions: {type: ['rss'], title: 'myTitle', copyright: ''},
   });
   expect(error).toBe(undefined);
 });
@@ -78,7 +78,7 @@ test('should convert all feed type to array with other feed type', () => {
   });
   expect(value).toEqual({
     ...DEFAULT_OPTIONS,
-    feedOptions: {type: ['rss', 'atom']},
+    feedOptions: {type: ['rss', 'atom'], copyright: ''},
   });
 });
 
@@ -106,7 +106,7 @@ test('should have array with rss + atom, title for missing feed type', () => {
   });
   expect(value).toEqual({
     ...DEFAULT_OPTIONS,
-    feedOptions: {type: ['rss', 'atom'], title: 'title'},
+    feedOptions: {type: ['rss', 'atom'], title: 'title', copyright: ''},
   });
 });
 

package/src/__tests__/translations.test.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 {BlogPost, BlogContent, PluginOptions} from '../types';
+import {getTranslationFiles, translateContent} from '../translations';
+import {DEFAULT_OPTIONS} from '../pluginOptionSchema';
+import {updateTranslationFileMessages} from '@docusaurus/utils';
+
+const sampleBlogOptions: PluginOptions = {
+  ...DEFAULT_OPTIONS,
+  blogSidebarTitle: 'All my posts',
+  blogTitle: 'My blog',
+  blogDescription: "Someone's random blog",
+};
+
+const sampleBlogPosts: BlogPost[] = [
+  {
+    id: 'hello',
+    metadata: {
+      permalink: '/blog/2021/06/19/hello',
+      source: '/blog/2021/06/19/hello',
+      description: '/blog/2021/06/19/hello',
+      date: new Date(2021, 6, 19),
+      formattedDate: 'June 19, 2021',
+      tags: [],
+      title: 'Hello',
+      truncated: true,
+    },
+  },
+];
+
+const sampleBlogContent: BlogContent = {
+  blogSidebarTitle: sampleBlogOptions.blogSidebarTitle,
+  blogListPaginated: [
+    {
+      items: ['hello'],
+      metadata: {
+        permalink: '/',
+        page: 1,
+        postsPerPage: 10,
+        totalPages: 1,
+        totalCount: 1,
+        previousPage: null,
+        nextPage: null,
+        blogTitle: sampleBlogOptions.blogTitle,
+        blogDescription: sampleBlogOptions.blogDescription,
+      },
+    },
+  ],
+  blogPosts: sampleBlogPosts,
+  blogTags: {},
+  blogTagsListPath: '/tags',
+};
+
+function getSampleTranslationFiles() {
+  return getTranslationFiles(sampleBlogOptions);
+}
+function getSampleTranslationFilesTranslated() {
+  const translationFiles = getSampleTranslationFiles();
+  return translationFiles.map((translationFile) =>
+    updateTranslationFileMessages(
+      translationFile,
+      (message) => `${message} (translated)`,
+    ),
+  );
+}
+
+describe('getContentTranslationFiles', () => {
+  test('should return translation files matching snapshot', async () => {
+    expect(getSampleTranslationFiles()).toMatchSnapshot();
+  });
+});
+
+describe('translateContent', () => {
+  test('should not translate anything if translation files are untranslated', () => {
+    const translationFiles = getSampleTranslationFiles();
+    expect(translateContent(sampleBlogContent, translationFiles)).toEqual(
+      sampleBlogContent,
+    );
+  });
+
+  test('should return translated loaded content matching snapshot', () => {
+    const translationFiles = getSampleTranslationFilesTranslated();
+    expect(
+      translateContent(sampleBlogContent, translationFiles),
+    ).toMatchSnapshot();
+  });
+});

package/src/authors.ts

@@ -0,0 +1,198 @@
+/**
+ * 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'});
+    try {
+      const unsafeContent = Yaml.load(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,80 +5,119 @@
  * 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 = {
   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;
 };
 
-// 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: Joi.string().uri(),
-  author_image_url: Joi.string().uri(),
-  slug: Joi.string(),
-  image: Joi.string().uri({relativeOnly: true}),
-  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
-  authorURL: Joi.string().uri(),
+  author_url: URISchema,
+  author_image_url: URISchema,
+  // TODO enable deprecation warnings later
+  authorURL: URISchema,
   // .warning('deprecate.error', { alternative: '"author_url"'}),
   authorTitle: Joi.string(),
   // .warning('deprecate.error', { alternative: '"author_title"'}),
-  authorImageURL: Joi.string().uri(),
+  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>,