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

package/src/__tests__/blogFrontMatter.test.ts

@@ -9,6 +9,7 @@ import {
   BlogPostFrontMatter,
   validateBlogPostFrontMatter,
 } from '../blogFrontMatter';
+import escapeStringRegexp from 'escape-string-regexp';
 
 function testField(params: {
   fieldName: keyof BlogPostFrontMatter;
@@ -41,7 +42,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 +71,9 @@ describe('validateBlogPostFrontMatter', () => {
     const frontMatter = {abc: '1'};
     expect(validateBlogPostFrontMatter(frontMatter)).toEqual(frontMatter);
   });
+});
 
+describe('validateBlogPostFrontMatter description', () => {
   testField({
     fieldName: 'description',
     validFrontMatters: [
@@ -66,7 +82,9 @@ describe('validateBlogPostFrontMatter', () => {
       {description: 'description'},
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter title', () => {
   testField({
     fieldName: 'title',
     validFrontMatters: [
@@ -75,25 +93,25 @@ describe('validateBlogPostFrontMatter', () => {
       {title: 'title'},
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter id', () => {
   testField({
     fieldName: 'id',
     validFrontMatters: [{id: '123'}, {id: 'id'}],
     invalidFrontMatters: [[{id: ''}, 'is not allowed to be empty']],
   });
+});
 
+describe('validateBlogPostFrontMatter author', () => {
   testField({
     fieldName: 'author',
     validFrontMatters: [{author: '123'}, {author: 'author'}],
     invalidFrontMatters: [[{author: ''}, 'is not allowed to be empty']],
   });
+});
 
-  testField({
-    fieldName: 'authorTitle',
-    validFrontMatters: [{authorTitle: '123'}, {authorTitle: 'authorTitle'}],
-    invalidFrontMatters: [[{authorTitle: ''}, 'is not allowed to be empty']],
-  });
-
+describe('validateBlogPostFrontMatter author_title', () => {
   testField({
     fieldName: 'author_title',
     validFrontMatters: [{author_title: '123'}, {author_title: 'author_title'}],
@@ -101,49 +119,75 @@ describe('validateBlogPostFrontMatter', () => {
   });
 
   testField({
-    fieldName: 'authorURL',
-    validFrontMatters: [{authorURL: 'https://docusaurus.io'}],
-    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'],
-    ],
+    fieldName: 'authorTitle',
+    validFrontMatters: [{authorTitle: '123'}, {authorTitle: 'authorTitle'}],
+    invalidFrontMatters: [[{authorTitle: ''}, 'is not allowed to be empty']],
   });
+});
 
+describe('validateBlogPostFrontMatter author_url', () => {
   testField({
     fieldName: 'author_url',
-    validFrontMatters: [{author_url: 'https://docusaurus.io'}],
+    validFrontMatters: [
+      {author_url: 'https://docusaurus.io'},
+      {author_url: '../../relative'},
+      {author_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_url: ''},
+        '"author_url" does not match any of the allowed types',
+      ],
     ],
   });
 
   testField({
-    fieldName: 'authorImageURL',
+    fieldName: 'authorURL',
     validFrontMatters: [
-      {authorImageURL: 'https://docusaurus.io/asset/image.png'},
+      {authorURL: 'https://docusaurus.io'},
+      {authorURL: '../../relative'},
+      {authorURL: '/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'],
+      [{authorURL: ''}, '"authorURL" does not match any of the allowed types'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter author_image_url', () => {
   testField({
     fieldName: 'author_image_url',
     validFrontMatters: [
       {author_image_url: 'https://docusaurus.io/asset/image.png'},
+      {author_image_url: '../../relative'},
+      {author_image_url: '/absolute'},
     ],
     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'],
+      [
+        {author_image_url: ''},
+        '"author_image_url" does not match any of the allowed types',
+      ],
     ],
   });
 
+  testField({
+    fieldName: 'authorImageURL',
+    validFrontMatters: [
+      {authorImageURL: 'https://docusaurus.io/asset/image.png'},
+      {authorImageURL: '../../relative'},
+      {authorImageURL: '/absolute'},
+    ],
+    invalidFrontMatters: [
+      [
+        {authorImageURL: ''},
+        '"authorImageURL" does not match any of the allowed types',
+      ],
+    ],
+  });
+});
+
+describe('validateBlogPostFrontMatter slug', () => {
   testField({
     fieldName: 'slug',
     validFrontMatters: [
@@ -158,10 +202,13 @@ describe('validateBlogPostFrontMatter', () => {
     ],
     invalidFrontMatters: [[{slug: ''}, 'is 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 +219,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 match any of the allowed types'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter tags', () => {
   testField({
     fieldName: 'tags',
     validFrontMatters: [
@@ -203,7 +247,9 @@ describe('validateBlogPostFrontMatter', () => {
       ],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter keywords', () => {
   testField({
     fieldName: 'keywords',
     validFrontMatters: [
@@ -218,7 +264,9 @@ describe('validateBlogPostFrontMatter', () => {
       [{keywords: []}, 'does not contain 1 required value(s)'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter draft', () => {
   testField({
     fieldName: 'draft',
     validFrontMatters: [{draft: true}, {draft: false}],
@@ -231,7 +279,9 @@ describe('validateBlogPostFrontMatter', () => {
       [{draft: 'no'}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter hide_table_of_contents', () => {
   testField({
     fieldName: 'hide_table_of_contents',
     validFrontMatters: [
@@ -247,7 +297,9 @@ describe('validateBlogPostFrontMatter', () => {
       [{hide_table_of_contents: 'no'}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateBlogPostFrontMatter date', () => {
   testField({
     fieldName: 'date',
     validFrontMatters: [

package/src/__tests__/generateBlogFeed.test.ts

@@ -32,7 +32,7 @@ function getBlogContentPaths(siteDir: string): BlogContentPaths {
 describe('blogFeed', () => {
   (['atom', 'rss'] as const).forEach((feedType) => {
     describe(`${feedType}`, () => {
-      test('can show feed without posts', async () => {
+      test('should not show feed without posts', async () => {
         const siteDir = __dirname;
         const siteConfig = {
           title: 'Hello',
@@ -68,7 +68,7 @@ describe('blogFeed', () => {
         const generatedFilesDir = path.resolve(siteDir, '.docusaurus');
         const siteConfig = {
           title: 'Hello',
-          baseUrl: '/',
+          baseUrl: '/myBaseUrl/',
           url: 'https://docusaurus.io',
           favicon: 'image/favicon.ico',
         };

package/src/blogFrontMatter.ts

@@ -9,6 +9,7 @@
 
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
+  URISchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
 import {Tag} from './types';
@@ -59,19 +60,19 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
 
   author: Joi.string(),
   author_title: Joi.string(),
-  author_url: Joi.string().uri(),
-  author_image_url: Joi.string().uri(),
+  author_url: URISchema,
+  author_image_url: URISchema,
   slug: Joi.string(),
-  image: Joi.string().uri({relativeOnly: true}),
+  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
-  authorURL: Joi.string().uri(),
+  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()

package/src/blogUtils.ts

@@ -55,6 +55,19 @@ function toUrl({date, link}: DateLink) {
     .replace(/-/g, '/')}/${link}`;
 }
 
+function formatBlogPostDate(locale: string, date: Date): string {
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }).format(date);
+  } catch (e) {
+    throw new Error(`Can't format blog post date "${date}"`);
+  }
+}
+
 export async function generateBlogFeed(
   contentPaths: BlogContentPaths,
   context: LoadContext,
@@ -62,18 +75,18 @@ export async function generateBlogFeed(
 ): Promise<Feed | null> {
   if (!options.feedOptions) {
     throw new Error(
-      'Invalid options - `feedOptions` is not expected to be null.',
+      'Invalid options: "feedOptions" is not expected to be null.',
     );
   }
   const {siteConfig} = context;
   const blogPosts = await generateBlogPosts(contentPaths, context, options);
-  if (blogPosts == null) {
+  if (!blogPosts.length) {
     return null;
   }
 
   const {feedOptions, routeBasePath} = options;
-  const {url: siteUrl, title, favicon} = siteConfig;
-  const blogBaseUrl = normalizeUrl([siteUrl, routeBasePath]);
+  const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
+  const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, routeBasePath]);
 
   const updated =
     (blogPosts[0] && blogPosts[0].metadata.date) ||
@@ -86,7 +99,7 @@ export async function generateBlogFeed(
     language: feedOptions.language,
     link: blogBaseUrl,
     description: feedOptions.description || `${siteConfig.title} Blog`,
-    favicon: normalizeUrl([siteUrl, favicon]),
+    favicon: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
     copyright: feedOptions.copyright,
   });
 
@@ -131,121 +144,126 @@ export async function generateBlogPosts(
 
   const blogPosts: BlogPost[] = [];
 
-  await Promise.all(
-    blogSourceFiles.map(async (blogSourceFile: string) => {
-      // Lookup in localized folder in priority
-      const blogDirPath = await getFolderContainingFile(
-        getContentPathList(contentPaths),
-        blogSourceFile,
-      );
+  async function processBlogSourceFile(blogSourceFile: string) {
+    // Lookup in localized folder in priority
+    const blogDirPath = await getFolderContainingFile(
+      getContentPathList(contentPaths),
+      blogSourceFile,
+    );
 
-      const source = path.join(blogDirPath, blogSourceFile);
+    const source = path.join(blogDirPath, blogSourceFile);
 
-      const {
-        frontMatter: unsafeFrontMatter,
-        content,
-        contentTitle,
-        excerpt,
-      } = await parseMarkdownFile(source);
-      const frontMatter = validateBlogPostFrontMatter(unsafeFrontMatter);
+    const {
+      frontMatter: unsafeFrontMatter,
+      content,
+      contentTitle,
+      excerpt,
+    } = await parseMarkdownFile(source, {removeContentTitle: true});
+    const frontMatter = validateBlogPostFrontMatter(unsafeFrontMatter);
+
+    const aliasedSource = aliasedSitePath(source, siteDir);
+
+    const blogFileName = path.basename(blogSourceFile);
+
+    if (frontMatter.draft && process.env.NODE_ENV === 'production') {
+      return;
+    }
+
+    if (frontMatter.id) {
+      console.warn(
+        chalk.yellow(
+          `"id" header option is deprecated in ${blogFileName} file. Please use "slug" option instead.`,
+        ),
+      );
+    }
 
-      const aliasedSource = aliasedSitePath(source, siteDir);
+    let date: Date | undefined;
+    // Extract date and title from filename.
+    const dateFilenameMatch = blogFileName.match(DATE_FILENAME_PATTERN);
+    let linkName = blogFileName.replace(/\.mdx?$/, '');
 
-      const blogFileName = path.basename(blogSourceFile);
+    if (dateFilenameMatch) {
+      const [, dateString, name] = dateFilenameMatch;
+      // Always treat dates as UTC by adding the `Z`
+      date = new Date(`${dateString}Z`);
+      linkName = name;
+    }
 
-      if (frontMatter.draft && process.env.NODE_ENV === 'production') {
-        return;
-      }
+    // Prefer user-defined date.
+    if (frontMatter.date) {
+      date = frontMatter.date;
+    }
 
-      if (frontMatter.id) {
-        console.warn(
-          chalk.yellow(
-            `${blogFileName} - 'id' header option is deprecated. Please use 'slug' option instead.`,
-          ),
-        );
-      }
+    // Use file create time for blog.
+    date = date ?? (await fs.stat(source)).birthtime;
+    const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
 
-      let date: Date | undefined;
-      // Extract date and title from filename.
-      const dateFilenameMatch = blogFileName.match(DATE_FILENAME_PATTERN);
-      let linkName = blogFileName.replace(/\.mdx?$/, '');
+    const title = frontMatter.title ?? contentTitle ?? linkName;
+    const description = frontMatter.description ?? excerpt ?? '';
 
-      if (dateFilenameMatch) {
-        const [, dateString, name] = dateFilenameMatch;
-        date = new Date(dateString);
-        linkName = name;
-      }
+    const slug =
+      frontMatter.slug ||
+      (dateFilenameMatch ? toUrl({date, link: linkName}) : linkName);
 
-      // Prefer user-defined date.
-      if (frontMatter.date) {
-        date = frontMatter.date;
-      }
-
-      // Use file create time for blog.
-      date = date ?? (await fs.stat(source)).birthtime;
-      const formattedDate = new Intl.DateTimeFormat(i18n.currentLocale, {
-        day: 'numeric',
-        month: 'long',
-        year: 'numeric',
-      }).format(date);
+    const permalink = normalizeUrl([baseUrl, routeBasePath, slug]);
 
-      const title = frontMatter.title ?? contentTitle ?? linkName;
-      const description = frontMatter.description ?? excerpt ?? '';
+    function getBlogEditUrl() {
+      const blogPathRelative = path.relative(blogDirPath, path.resolve(source));
 
-      const slug =
-        frontMatter.slug ||
-        (dateFilenameMatch ? toUrl({date, link: linkName}) : linkName);
-
-      const permalink = normalizeUrl([baseUrl, routeBasePath, slug]);
+      if (typeof editUrl === 'function') {
+        return editUrl({
+          blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
+          blogPath: posixPath(blogPathRelative),
+          permalink,
+          locale: i18n.currentLocale,
+        });
+      } else if (typeof editUrl === 'string') {
+        const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
+        const fileContentPath =
+          isLocalized && options.editLocalizedFiles
+            ? contentPaths.contentPathLocalized
+            : contentPaths.contentPath;
+
+        const contentPathEditUrl = normalizeUrl([
+          editUrl,
+          posixPath(path.relative(siteDir, fileContentPath)),
+        ]);
+
+        return getEditUrl(blogPathRelative, contentPathEditUrl);
+      } else {
+        return undefined;
+      }
+    }
+
+    blogPosts.push({
+      id: frontMatter.slug ?? title,
+      metadata: {
+        permalink,
+        editUrl: getBlogEditUrl(),
+        source: aliasedSource,
+        title,
+        description,
+        date,
+        formattedDate,
+        tags: frontMatter.tags ?? [],
+        readingTime: showReadingTime ? readingTime(content).minutes : undefined,
+        truncated: truncateMarker?.test(content) || false,
+      },
+    });
+  }
 
-      function getBlogEditUrl() {
-        const blogPathRelative = path.relative(
-          blogDirPath,
-          path.resolve(source),
+  await Promise.all(
+    blogSourceFiles.map(async (blogSourceFile: string) => {
+      try {
+        return await processBlogSourceFile(blogSourceFile);
+      } catch (e) {
+        console.error(
+          chalk.red(
+            `Processing of blog source file failed for path "${blogSourceFile}"`,
+          ),
         );
-
-        if (typeof editUrl === 'function') {
-          return editUrl({
-            blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
-            blogPath: posixPath(blogPathRelative),
-            permalink,
-            locale: i18n.currentLocale,
-          });
-        } else if (typeof editUrl === 'string') {
-          const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
-          const fileContentPath =
-            isLocalized && options.editLocalizedFiles
-              ? contentPaths.contentPathLocalized
-              : contentPaths.contentPath;
-
-          const contentPathEditUrl = normalizeUrl([
-            editUrl,
-            posixPath(path.relative(siteDir, fileContentPath)),
-          ]);
-
-          return getEditUrl(blogPathRelative, contentPathEditUrl);
-        } else {
-          return undefined;
-        }
+        throw e;
       }
-
-      blogPosts.push({
-        id: frontMatter.slug ?? title,
-        metadata: {
-          permalink,
-          editUrl: getBlogEditUrl(),
-          source: aliasedSource,
-          title,
-          description,
-          date,
-          formattedDate,
-          tags: frontMatter.tags ?? [],
-          readingTime: showReadingTime
-            ? readingTime(content).minutes
-            : undefined,
-          truncated: truncateMarker?.test(content) || false,
-        },
-      });
     }),
   );