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

package/src/__tests__/blogFrontMatter.test.ts

@@ -9,7 +9,10 @@ import {
   BlogPostFrontMatter,
   validateBlogPostFrontMatter,
 } 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[];
@@ -41,7 +44,20 @@ function testField(params: {
 
     test('throw error for values', () => {
       params.invalidFrontMatters?.forEach(([frontMatter, message]) => {
-        expect(() => validateBlogPostFrontMatter(frontMatter)).toThrow(message);
+        try {
+          validateBlogPostFrontMatter(frontMatter);
+          fail(
+            new Error(
+              `Blog frontmatter is expected to be rejected, but was accepted successfully:\n ${JSON.stringify(
+                frontMatter,
+                null,
+                2,
+              )}`,
+            ),
+          );
+        } catch (e) {
+          expect(e.message).toMatch(new RegExp(escapeStringRegexp(message)));
+        }
       });
     });
   });
@@ -57,7 +73,9 @@ describe('validateBlogPostFrontMatter', () => {
     const frontMatter = {abc: '1'};
     expect(validateBlogPostFrontMatter(frontMatter)).toEqual(frontMatter);
   });
+});
 
+describe('validateBlogPostFrontMatter description', () => {
   testField({
     fieldName: 'description',
     validFrontMatters: [
@@ -66,7 +84,9 @@ describe('validateBlogPostFrontMatter', () => {
       {description: 'description'},
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter title', () => {
   testField({
     fieldName: 'title',
     validFrontMatters: [
@@ -75,48 +95,110 @@ describe('validateBlogPostFrontMatter', () => {
       {title: 'title'},
     ],
   });
+});
 
+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);
+  });
+});
+
+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: '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']],
   });
+});
 
+describe('validateBlogPostFrontMatter author_url', () => {
   testField({
-    fieldName: 'author_title',
-    validFrontMatters: [{author_title: '123'}, {author_title: 'author_title'}],
-    invalidFrontMatters: [[{author_title: ''}, 'is not allowed to be empty']],
+    fieldName: 'author_url',
+    validFrontMatters: [
+      {author_url: 'https://docusaurus.io'},
+      {author_url: '../../relative'},
+      {author_url: '/absolute'},
+    ],
+    invalidFrontMatters: [
+      [
+        {author_url: ''},
+        '"author_url" does not look like a valid url (value=\'\')',
+      ],
+    ],
   });
 
   testField({
     fieldName: 'authorURL',
-    validFrontMatters: [{authorURL: 'https://docusaurus.io'}],
+    validFrontMatters: [
+      {authorURL: 'https://docusaurus.io'},
+      {authorURL: '../../relative'},
+      {authorURL: '/absolute'},
+    ],
+
     invalidFrontMatters: [
-      [{authorURL: ''}, 'is not allowed to be empty'],
-      [{authorURL: '@site/api/author'}, 'must be a valid uri'],
-      [{authorURL: '../../api/author'}, 'must be a valid uri'],
+      [
+        {authorURL: ''},
+        '"authorURL" does not look like a valid url (value=\'\')',
+      ],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter author_image_url', () => {
   testField({
-    fieldName: 'author_url',
-    validFrontMatters: [{author_url: 'https://docusaurus.io'}],
+    fieldName: 'author_image_url',
+    validFrontMatters: [
+      {author_image_url: 'https://docusaurus.io/asset/image.png'},
+      {author_image_url: '../../relative'},
+      {author_image_url: '/absolute'},
+    ],
     invalidFrontMatters: [
-      [{author_url: ''}, 'is not allowed to be empty'],
-      [{author_url: '@site/api/author'}, 'must be a valid uri'],
-      [{author_url: '../../api/author'}, 'must be a valid uri'],
+      [
+        {author_image_url: ''},
+        '"author_image_url" does not look like a valid url (value=\'\')',
+      ],
     ],
   });
 
@@ -124,26 +206,67 @@ describe('validateBlogPostFrontMatter', () => {
     fieldName: 'authorImageURL',
     validFrontMatters: [
       {authorImageURL: 'https://docusaurus.io/asset/image.png'},
+      {authorImageURL: '../../relative'},
+      {authorImageURL: '/absolute'},
     ],
     invalidFrontMatters: [
-      [{authorImageURL: ''}, 'is not allowed to be empty'],
-      [{authorImageURL: '@site/api/asset/image.png'}, 'must be a valid uri'],
-      [{authorImageURL: '../../api/asset/image.png'}, 'must be a valid uri'],
+      [
+        {authorImageURL: ''},
+        '"authorImageURL" does not look like a valid url (value=\'\')',
+      ],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter authors', () => {
   testField({
-    fieldName: 'author_image_url',
+    fieldName: 'author',
     validFrontMatters: [
-      {author_image_url: 'https://docusaurus.io/asset/image.png'},
+      {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: [
-      [{author_image_url: ''}, 'is not allowed to be empty'],
-      [{author_image_url: '@site/api/asset/image.png'}, 'must be a valid uri'],
-      [{author_image_url: '../../api/asset/image.png'}, 'must be a valid uri'],
+      [{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).',
+      ],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter slug', () => {
   testField({
     fieldName: 'slug',
     validFrontMatters: [
@@ -156,12 +279,15 @@ describe('validateBlogPostFrontMatter', () => {
       {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']],
   });
+});
 
+describe('validateBlogPostFrontMatter image', () => {
   testField({
     fieldName: 'image',
     validFrontMatters: [
+      {image: 'https://docusaurus.io/image.png'},
       {image: 'blog/'},
       {image: '/blog'},
       {image: '/blog/'},
@@ -172,15 +298,12 @@ describe('validateBlogPostFrontMatter', () => {
       {image: '@site/api/asset/image.png'},
     ],
     invalidFrontMatters: [
-      [{image: ''}, 'is not allowed to be empty'],
-      [{image: 'https://docusaurus.io'}, 'must be a valid relative uri'],
-      [
-        {image: 'https://docusaurus.io/blog/image.png'},
-        'must be a valid relative uri',
-      ],
+      [{image: ''}, '"image" does not look like a valid url (value=\'\')'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter tags', () => {
   testField({
     fieldName: 'tags',
     validFrontMatters: [
@@ -191,8 +314,8 @@ describe('validateBlogPostFrontMatter', () => {
       {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: [
@@ -203,7 +326,9 @@ describe('validateBlogPostFrontMatter', () => {
       ],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter keywords', () => {
   testField({
     fieldName: 'keywords',
     validFrontMatters: [
@@ -214,11 +339,13 @@ describe('validateBlogPostFrontMatter', () => {
     ],
     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)'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter draft', () => {
   testField({
     fieldName: 'draft',
     validFrontMatters: [{draft: true}, {draft: false}],
@@ -231,7 +358,9 @@ describe('validateBlogPostFrontMatter', () => {
       [{draft: 'no'}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter hide_table_of_contents', () => {
   testField({
     fieldName: 'hide_table_of_contents',
     validFrontMatters: [
@@ -247,14 +376,14 @@ describe('validateBlogPostFrontMatter', () => {
       [{hide_table_of_contents: 'no'}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter date', () => {
   testField({
     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 =