@docusaurus/plugin-content-blog 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/src/__tests__/blogFrontMatter.test.ts

@@ -11,6 +11,8 @@ import {
 } from '../blogFrontMatter';
 import escapeStringRegexp from 'escape-string-regexp';
 
+// TODO this abstraction reduce verbosity but it makes it harder to debug
+// It would be preferable to just expose helper methods
 function testField(params: {
   fieldName: keyof BlogPostFrontMatter;
   validFrontMatters: BlogPostFrontMatter[];
@@ -99,7 +101,30 @@ describe('validateBlogPostFrontMatter id', () => {
   testField({
     fieldName: 'id',
     validFrontMatters: [{id: '123'}, {id: 'id'}],
-    invalidFrontMatters: [[{id: ''}, 'is not allowed to be empty']],
+    invalidFrontMatters: [[{id: ''}, 'not allowed to be empty']],
+  });
+});
+
+describe('validateBlogPostFrontMatter handles legacy/new author frontmatter', () => {
+  test('allow legacy author frontmatter', () => {
+    const frontMatter: BlogPostFrontMatter = {
+      author: 'Sebastien',
+      author_url: 'https://sebastienlorber.com',
+      author_title: 'maintainer',
+      author_image_url: 'https://github.com/slorber.png',
+    };
+    expect(validateBlogPostFrontMatter(frontMatter)).toEqual(frontMatter);
+  });
+
+  test('allow new authors frontmatter', () => {
+    const frontMatter: BlogPostFrontMatter = {
+      authors: [
+        'slorber',
+        {name: 'Yangshun'},
+        {key: 'JMarcey', title: 'creator', random: '42'},
+      ],
+    };
+    expect(validateBlogPostFrontMatter(frontMatter)).toEqual(frontMatter);
   });
 });
 
@@ -107,21 +132,24 @@ describe('validateBlogPostFrontMatter author', () => {
   testField({
     fieldName: 'author',
     validFrontMatters: [{author: '123'}, {author: 'author'}],
-    invalidFrontMatters: [[{author: ''}, 'is not allowed to be empty']],
+    invalidFrontMatters: [[{author: ''}, 'not allowed to be empty']],
   });
 });
 
 describe('validateBlogPostFrontMatter author_title', () => {
   testField({
     fieldName: 'author_title',
-    validFrontMatters: [{author_title: '123'}, {author_title: 'author_title'}],
-    invalidFrontMatters: [[{author_title: ''}, 'is not allowed to be empty']],
+    validFrontMatters: [
+      {author: '123', author_title: '123'},
+      {author: '123', author_title: 'author_title'},
+    ],
+    invalidFrontMatters: [[{author_title: ''}, 'not allowed to be empty']],
   });
 
   testField({
     fieldName: 'authorTitle',
     validFrontMatters: [{authorTitle: '123'}, {authorTitle: 'authorTitle'}],
-    invalidFrontMatters: [[{authorTitle: ''}, 'is not allowed to be empty']],
+    invalidFrontMatters: [[{authorTitle: ''}, 'not allowed to be empty']],
   });
 });
 
@@ -136,7 +164,7 @@ describe('validateBlogPostFrontMatter author_url', () => {
     invalidFrontMatters: [
       [
         {author_url: ''},
-        '"author_url" does not match any of the allowed types',
+        '"author_url" does not look like a valid url (value=\'\')',
       ],
     ],
   });
@@ -150,7 +178,10 @@ describe('validateBlogPostFrontMatter author_url', () => {
     ],
 
     invalidFrontMatters: [
-      [{authorURL: ''}, '"authorURL" does not match any of the allowed types'],
+      [
+        {authorURL: ''},
+        '"authorURL" does not look like a valid url (value=\'\')',
+      ],
     ],
   });
 });
@@ -166,7 +197,7 @@ describe('validateBlogPostFrontMatter author_image_url', () => {
     invalidFrontMatters: [
       [
         {author_image_url: ''},
-        '"author_image_url" does not match any of the allowed types',
+        '"author_image_url" does not look like a valid url (value=\'\')',
       ],
     ],
   });
@@ -181,7 +212,55 @@ describe('validateBlogPostFrontMatter author_image_url', () => {
     invalidFrontMatters: [
       [
         {authorImageURL: ''},
-        '"authorImageURL" does not match any of the allowed types',
+        '"authorImageURL" does not look like a valid url (value=\'\')',
+      ],
+    ],
+  });
+});
+
+describe('validateBlogPostFrontMatter authors', () => {
+  testField({
+    fieldName: 'author',
+    validFrontMatters: [
+      {authors: []},
+      {authors: 'authorKey'},
+      {authors: ['authorKey1', 'authorKey2']},
+      {
+        authors: {
+          name: 'Author Name',
+          imageURL: '/absolute',
+        },
+      },
+      {
+        authors: {
+          key: 'authorKey',
+          title: 'Author title',
+        },
+      },
+      {
+        authors: [
+          'authorKey1',
+          {key: 'authorKey3'},
+          'authorKey3',
+          {name: 'Author Name 4'},
+          {key: 'authorKey5'},
+        ],
+      },
+    ],
+
+    invalidFrontMatters: [
+      [{authors: ''}, '"authors" is not allowed to be empty'],
+      [
+        {authors: [undefined]},
+        '"authors[0]" does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).',
+      ],
+      [
+        {authors: [null]},
+        '"authors[0]" does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).',
+      ],
+      [
+        {authors: [{}]},
+        '"authors[0]" does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).',
       ],
     ],
   });
@@ -200,7 +279,7 @@ describe('validateBlogPostFrontMatter slug', () => {
       {slug: '/api/plugins/@docusaurus/plugin-debug'},
       {slug: '@site/api/asset/image.png'},
     ],
-    invalidFrontMatters: [[{slug: ''}, 'is not allowed to be empty']],
+    invalidFrontMatters: [[{slug: ''}, 'not allowed to be empty']],
   });
 });
 
@@ -219,7 +298,7 @@ describe('validateBlogPostFrontMatter image', () => {
       {image: '@site/api/asset/image.png'},
     ],
     invalidFrontMatters: [
-      [{image: ''}, '"image" does not match any of the allowed types'],
+      [{image: ''}, '"image" does not look like a valid url (value=\'\')'],
     ],
   });
 });
@@ -235,8 +314,8 @@ describe('validateBlogPostFrontMatter tags', () => {
       {tags: ['hello', {label: 'tagLabel', permalink: '/tagPermalink'}]},
     ],
     invalidFrontMatters: [
-      [{tags: ''}, 'must be an array'],
-      [{tags: ['']}, 'is not allowed to be empty'],
+      [{tags: ''}, '"tags" does not look like a valid FrontMatter Yaml array.'],
+      [{tags: ['']}, 'not allowed to be empty'],
     ],
     // See https://github.com/facebook/docusaurus/issues/4642
     convertibleFrontMatter: [
@@ -260,7 +339,7 @@ describe('validateBlogPostFrontMatter keywords', () => {
     ],
     invalidFrontMatters: [
       [{keywords: ''}, 'must be an array'],
-      [{keywords: ['']}, 'is not allowed to be empty'],
+      [{keywords: ['']}, 'not allowed to be empty'],
       [{keywords: []}, 'does not contain 1 required value(s)'],
     ],
   });
@@ -304,9 +383,7 @@ describe('validateBlogPostFrontMatter date', () => {
     fieldName: 'date',
     validFrontMatters: [
       {date: new Date('2020-01-01')},
-      // @ts-expect-error: string for test
       {date: '2020-01-01'},
-      // @ts-expect-error: string for test
       {date: '2020'},
     ],
     invalidFrontMatters: [

package/src/__tests__/blogUtils.test.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 {parseBlogFileName} from '../blogUtils';
+
+describe('parseBlogFileName', () => {
+  test('parse file', () => {
+    expect(parseBlogFileName('some-post.md')).toEqual({
+      date: undefined,
+      text: 'some-post',
+      slug: '/some-post',
+    });
+  });
+
+  test('parse folder', () => {
+    expect(parseBlogFileName('some-post/index.md')).toEqual({
+      date: undefined,
+      text: 'some-post',
+      slug: '/some-post',
+    });
+  });
+
+  test('parse nested file', () => {
+    expect(parseBlogFileName('some-post/some-file.md')).toEqual({
+      date: undefined,
+      text: 'some-post/some-file',
+      slug: '/some-post/some-file',
+    });
+  });
+
+  test('parse nested folder', () => {
+    expect(parseBlogFileName('some-post/some-subfolder/index.md')).toEqual({
+      date: undefined,
+      text: 'some-post/some-subfolder',
+      slug: '/some-post/some-subfolder',
+    });
+  });
+
+  test('parse file respecting date convention', () => {
+    expect(
+      parseBlogFileName('2021-05-12-announcing-docusaurus-two-beta.md'),
+    ).toEqual({
+      date: new Date('2021-05-12Z'),
+      text: 'announcing-docusaurus-two-beta',
+      slug: '/2021/05/12/announcing-docusaurus-two-beta',
+    });
+  });
+
+  test('parse folder name respecting date convention', () => {
+    expect(
+      parseBlogFileName('2021-05-12-announcing-docusaurus-two-beta/index.md'),
+    ).toEqual({
+      date: new Date('2021-05-12Z'),
+      text: 'announcing-docusaurus-two-beta',
+      slug: '/2021/05/12/announcing-docusaurus-two-beta',
+    });
+  });
+
+  test('parse folder tree respecting date convention', () => {
+    expect(
+      parseBlogFileName('2021/05/12/announcing-docusaurus-two-beta/index.md'),
+    ).toEqual({
+      date: new Date('2021-05-12Z'),
+      text: 'announcing-docusaurus-two-beta',
+      slug: '/2021/05/12/announcing-docusaurus-two-beta',
+    });
+  });
+
+  test('parse folder name/tree (mixed) respecting date convention', () => {
+    expect(
+      parseBlogFileName('2021/05-12-announcing-docusaurus-two-beta/index.md'),
+    ).toEqual({
+      date: new Date('2021-05-12Z'),
+      text: 'announcing-docusaurus-two-beta',
+      slug: '/2021/05/12/announcing-docusaurus-two-beta',
+    });
+  });
+
+  test('parse nested folder tree respecting date convention', () => {
+    expect(
+      parseBlogFileName(
+        '2021/05/12/announcing-docusaurus-two-beta/subfolder/subfile.md',
+      ),
+    ).toEqual({
+      date: new Date('2021-05-12Z'),
+      text: 'announcing-docusaurus-two-beta/subfolder/subfile',
+      slug: '/2021/05/12/announcing-docusaurus-two-beta/subfolder/subfile',
+    });
+  });
+});

package/src/__tests__/{generateBlogFeed.test.ts → feed.test.ts}

@@ -6,9 +6,12 @@
  */
 
 import path from 'path';
-import {generateBlogFeed} from '../blogUtils';
+import {generateBlogFeed} from '../feed';
 import {LoadContext, I18n} from '@docusaurus/types';
 import {PluginOptions, BlogContentPaths} from '../types';
+import {DEFAULT_OPTIONS} from '../pluginOptionSchema';
+import {generateBlogPosts} from '../blogUtils';
+import {Feed} from 'feed';
 
 const DefaultI18N: I18n = {
   currentLocale: 'en',
@@ -29,6 +32,23 @@ function getBlogContentPaths(siteDir: string): BlogContentPaths {
   };
 }
 
+async function testGenerateFeeds(
+  context: LoadContext,
+  options: PluginOptions,
+): Promise<Feed | null> {
+  const blogPosts = await generateBlogPosts(
+    getBlogContentPaths(context.siteDir),
+    context,
+    options,
+  );
+
+  return generateBlogFeed({
+    blogPosts,
+    options,
+    siteConfig: context.siteConfig,
+  });
+}
+
 describe('blogFeed', () => {
   (['atom', 'rss'] as const).forEach((feedType) => {
     describe(`${feedType}`, () => {
@@ -41,8 +61,7 @@ describe('blogFeed', () => {
           favicon: 'image/favicon.ico',
         };
 
-        const feed = await generateBlogFeed(
-          getBlogContentPaths(siteDir),
+        const feed = await testGenerateFeeds(
           {
             siteDir,
             siteConfig,
@@ -51,16 +70,19 @@ describe('blogFeed', () => {
           {
             path: 'invalid-blog-path',
             routeBasePath: 'blog',
+            tagsBasePath: 'tags',
+            authorsMapPath: 'authors.yml',
             include: ['*.md', '*.mdx'],
             feedOptions: {
               type: [feedType],
               copyright: 'Copyright',
             },
+            readingTime: ({content, defaultReadingTime}) =>
+              defaultReadingTime({content}),
           } as PluginOptions,
         );
-        const feedContent =
-          feed && (feedType === 'rss' ? feed.rss2() : feed.atom1());
-        expect(feedContent).toMatchSnapshot();
+
+        expect(feed).toEqual(null);
       });
 
       test('shows feed item for each post', async () => {
@@ -73,8 +95,7 @@ describe('blogFeed', () => {
           favicon: 'image/favicon.ico',
         };
 
-        const feed = await generateBlogFeed(
-          getBlogContentPaths(siteDir),
+        const feed = await testGenerateFeeds(
           {
             siteDir,
             siteConfig,
@@ -84,11 +105,16 @@ describe('blogFeed', () => {
           {
             path: 'blog',
             routeBasePath: 'blog',
-            include: ['*r*.md', '*.mdx'], // skip no-date.md - it won't play nice with snapshots
+            tagsBasePath: 'tags',
+            authorsMapPath: 'authors.yml',
+            include: DEFAULT_OPTIONS.include,
+            exclude: DEFAULT_OPTIONS.exclude,
             feedOptions: {
               type: [feedType],
               copyright: 'Copyright',
             },
+            readingTime: ({content, defaultReadingTime}) =>
+              defaultReadingTime({content}),
           } as PluginOptions,
         );
         const feedContent =

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: ''},
   });
 });