chore: backport retro compatible commits for the Docusaurus v2.3 release (#8585)

Co-authored-by: stnor <stefan@selessia.com>
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Matija Sirk <matija.sirk@kopit.si>
Co-authored-by: AHMET BAYHAN BAYRAMOGLU <49499275+ABB65@users.noreply.github.com>
Co-authored-by: Stefan Norberg <stefan@norberg.org>
Co-authored-by: Josh Goldberg <git@joshuakgoldberg.com>
Co-authored-by: Muhammad Hammad <33136628+mhnaeem@users.noreply.github.com>
Co-authored-by: Denis Al-Khelali <denis.al-khelali@itechart-group.com>
Co-authored-by: Balthasar Hofer <lebalz@outlook.com>
Co-authored-by: Danny Kim <0916dhkim@gmail.com>
Co-authored-by: Frieder Bluemle <frieder.bluemle@gmail.com>
Co-authored-by: John Reilly <johnny_reilly@hotmail.com>
Co-authored-by: Robert Lawrence <62929526+r-lawrence@users.noreply.github.com>
Co-authored-by: Sadegh Karimi <sadegh.krmi@gmail.com>
Co-authored-by: Lachlan Heywood <lachieh@users.noreply.github.com>
Co-authored-by: mturoci <64769322+mturoci@users.noreply.github.com>
Co-authored-by: 宋锦丰 <36468758+SJFCS@users.noreply.github.com>
Co-authored-by: Nguyễn Thành Nam <namnguyenthanh.work@gmail.com>
Co-authored-by: Dongjoon Lee <djunnni@gmail.com>
Co-authored-by: Thomas.CA <44041651+Thomascogez@users.noreply.github.com>
Co-authored-by: Riccardo <riccardo.odone@gmail.com>
Co-authored-by: Lane Goolsby <lanegoolsby@yahoo.com>
Co-authored-by: Mariusz Krzaczkowski <m.krzaczkowski@yetiforce.com>
Co-authored-by: Matija Sirk <sirkmatija@gmail.com>
Co-authored-by: Jiří <zmrhal.j@gmail.com>

packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts

@@ -143,4 +143,56 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
     ).toMatchSnapshot();
     fsMock.mockClear();
   });
+
+  it('filters to the first two entries', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const outDir = path.join(siteDir, 'build-snap');
+    const siteConfig = {
+      title: 'Hello',
+      baseUrl: '/myBaseUrl/',
+      url: 'https://docusaurus.io',
+      favicon: 'image/favicon.ico',
+    };
+
+    // Build is quite difficult to mock, so we built the blog beforehand and
+    // copied the output to the fixture...
+    await testGenerateFeeds(
+      {
+        siteDir,
+        siteConfig,
+        i18n: DefaultI18N,
+        outDir,
+      } as LoadContext,
+      {
+        path: 'blog',
+        routeBasePath: 'blog',
+        tagsBasePath: 'tags',
+        authorsMapPath: 'authors.yml',
+        include: DEFAULT_OPTIONS.include,
+        exclude: DEFAULT_OPTIONS.exclude,
+        feedOptions: {
+          type: [feedType],
+          copyright: 'Copyright',
+          createFeedItems: async (params) => {
+            const {blogPosts, defaultCreateFeedItems, ...rest} = params;
+            const blogPostsFiltered = blogPosts.filter(
+              (item, index) => index < 2,
+            );
+            return defaultCreateFeedItems({
+              blogPosts: blogPostsFiltered,
+              ...rest,
+            });
+          },
+        },
+        readingTime: ({content, defaultReadingTime}) =>
+          defaultReadingTime({content}),
+        truncateMarker: /<!--\s*truncate\s*-->/,
+      } as PluginOptions,
+    );
+
+    expect(
+      fsMock.mock.calls.map((call) => call[1] as string),
+    ).toMatchSnapshot();
+    fsMock.mockClear();
+  });
 });

packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import escapeStringRegexp from 'escape-string-regexp';
+import {escapeRegexp} from '@docusaurus/utils';
 import {validateBlogPostFrontMatter} from '../frontMatter';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
@@ -57,7 +57,7 @@ function testField(params: {
         } catch (err) {
           // eslint-disable-next-line jest/no-conditional-expect
           expect((err as Error).message).toMatch(
-            new RegExp(escapeStringRegexp(message)),
+            new RegExp(escapeRegexp(message)),
           );
         }
       });

packages/docusaurus-plugin-content-blog/src/feed.ts

@@ -8,7 +8,7 @@
 import path from 'path';
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
-import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed';
+import {Feed, type Author as FeedAuthor} from 'feed';
 import {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
 import {blogPostContainerID} from '@docusaurus/utils-common';
 import {load as cheerioLoad} from 'cheerio';
@@ -18,6 +18,7 @@ import type {
   PluginOptions,
   Author,
   BlogPost,
+  BlogFeedItem,
 } from '@docusaurus/plugin-content-blog';
 
 async function generateBlogFeed({
@@ -54,14 +55,39 @@ async function generateBlogFeed({
     copyright: feedOptions.copyright,
   });
 
+  const createFeedItems =
+    options.feedOptions.createFeedItems ?? defaultCreateFeedItems;
+
+  const feedItems = await createFeedItems({
+    blogPosts,
+    siteConfig,
+    outDir,
+    defaultCreateFeedItems,
+  });
+
+  feedItems.forEach(feed.addItem);
+
+  return feed;
+}
+
+async function defaultCreateFeedItems({
+  blogPosts,
+  siteConfig,
+  outDir,
+}: {
+  blogPosts: BlogPost[];
+  siteConfig: DocusaurusConfig;
+  outDir: string;
+}): Promise<BlogFeedItem[]> {
+  const {url: siteUrl} = siteConfig;
+
   function toFeedAuthor(author: Author): FeedAuthor {
     return {name: author.name, link: author.url, email: author.email};
   }
 
-  await Promise.all(
+  return Promise.all(
     blogPosts.map(async (post) => {
       const {
-        id,
         metadata: {
           title: metadataTitle,
           permalink,
@@ -79,10 +105,11 @@ async function generateBlogFeed({
       );
       const $ = cheerioLoad(content);
 
-      const feedItem: FeedItem = {
+      const link = normalizeUrl([siteUrl, permalink]);
+      const feedItem: BlogFeedItem = {
         title: metadataTitle,
-        id,
-        link: normalizeUrl([siteUrl, permalink]),
+        id: link,
+        link,
         date,
         description,
         // Atom feed demands the "term", while other feeds use "name"
@@ -99,9 +126,7 @@ async function generateBlogFeed({
 
       return feedItem;
     }),
-  ).then((items) => items.forEach(feed.addItem));
-
-  return feed;
+  );
 }
 
 async function createBlogFeedFile({

packages/docusaurus-plugin-content-blog/src/options.ts

@@ -124,6 +124,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
         .default(DEFAULT_OPTIONS.feedOptions.copyright),
     }),
     language: Joi.string(),
+    createFeedItems: Joi.function(),
   }).default(DEFAULT_OPTIONS.feedOptions),
   authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
   readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -9,12 +9,19 @@ declare module '@docusaurus/plugin-content-blog' {
   import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {MDXOptions} from '@docusaurus/mdx-loader';
   import type {FrontMatterTag, Tag} from '@docusaurus/utils';
-  import type {Plugin, LoadContext} from '@docusaurus/types';
+  import type {DocusaurusConfig, Plugin, LoadContext} from '@docusaurus/types';
+  import type {Item as FeedItem} from 'feed';
   import type {Overwrite} from 'utility-types';
 
   export type Assets = {
     /**
-     * If `metadata.image` is a collocated image path, this entry will be the
+     * If `metadata.yarn workspace website typecheck
+4
+yarn workspace v1.22.19yarn workspace website typecheck
+4
+yarn workspace v1.22.19yarn workspace website typecheck
+4
+yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      * bundler-generated image path. Otherwise, it's empty, and the image URL
      * should be accessed through `frontMatter.image`.
      */
@@ -255,6 +262,24 @@ declare module '@docusaurus/plugin-content-blog' {
     copyright: string;
     /** Language of the feed. */
     language?: string;
+    /** Allow control over the construction of BlogFeedItems */
+    createFeedItems?: CreateFeedItemsFn;
+  };
+
+  type DefaultCreateFeedItemsParams = {
+    blogPosts: BlogPost[];
+    siteConfig: DocusaurusConfig;
+    outDir: string;
+  };
+
+  type CreateFeedItemsFn = (
+    params: CreateFeedItemsParams,
+  ) => Promise<BlogFeedItem[]>;
+
+  type CreateFeedItemsParams = DefaultCreateFeedItemsParams & {
+    defaultCreateFeedItems: (
+      params: DefaultCreateFeedItemsParams,
+    ) => Promise<BlogFeedItem[]>;
   };
 
   /**
@@ -436,6 +461,8 @@ declare module '@docusaurus/plugin-content-blog' {
     content: string;
   };
 
+  export type BlogFeedItem = FeedItem;
+
   export type BlogPaginatedMetadata = {
     /** Title of the entire blog. */
     readonly blogTitle: string;