feat(blog): add options.createFeedItems to filter/limit/transform feed items

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 (options) => {
+            const {blogPosts, defaultCreateFeedItems, ...others} = options;
+            const blogPostsFiltered = blogPosts.filter(
+              (item, index) => index < 2,
+            );
+            return defaultCreateFeedItems({
+              blogPosts: blogPostsFiltered,
+              ...others,
+            });
+          },
+        },
+        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/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,11 +55,35 @@ async function generateBlogFeed({
     copyright: feedOptions.copyright,
   });
 
+  const feedItems = await (feedOptions.createFeedItems
+    ? feedOptions.createFeedItems({
+        blogPosts,
+        siteConfig,
+        outDir,
+        defaultCreateFeedItems,
+      })
+    : defaultCreateFeedItems({blogPosts, siteConfig, outDir}));
+  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(
+  const items = await Promise.all(
     blogPosts.map(async (post) => {
       const {
         metadata: {
@@ -79,7 +104,7 @@ async function generateBlogFeed({
       const $ = cheerioLoad(content);
 
       const link = normalizeUrl([siteUrl, permalink]);
-      const feedItem: FeedItem = {
+      const feedItem: BlogFeedItem = {
         title: metadataTitle,
         id: link,
         link,
@@ -99,9 +124,8 @@ async function generateBlogFeed({
 
       return feedItem;
     }),
-  ).then((items) => items.forEach(feed.addItem));
-
-  return feed;
+  );
+  return items;
 }
 
 async function createBlogFeedFile({

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

@@ -122,6 +122,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`.
      */
@@ -263,6 +270,22 @@ declare module '@docusaurus/plugin-content-blog' {
     copyright: string;
     /** Language of the feed. */
     language?: string;
+    /** Allow control over the construction of BlogFeedItems */
+    createFeedItems?: (
+      options: CreateFeedItemsOptions,
+    ) => Promise<BlogFeedItem[]>;
+  };
+
+  type DefaultCreateFeedItemsOptions = {
+    blogPosts: BlogPost[];
+    siteConfig: DocusaurusConfig;
+    outDir: string;
+  };
+
+  type CreateFeedItemsOptions = DefaultCreateFeedItemsOptions & {
+    defaultCreateFeedItems: (
+      params: DefaultCreateFeedItemsOptions,
+    ) => Promise<BlogFeedItem[]>;
   };
 
   /**
@@ -451,6 +474,8 @@ declare module '@docusaurus/plugin-content-blog' {
     content: string;
   };
 
+  export type BlogFeedItem = FeedItem;
+
   export type BlogPaginatedMetadata = {
     /** Title of the entire blog. */
     readonly blogTitle: string;

website/docs/blog.mdx

@@ -511,6 +511,17 @@ type BlogOptions = {
     description?: string;
     copyright: string;
     language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
+    /** Allow control over the construction of BlogFeedItems */
+    createFeedItems?: (options: {
+      blogPosts: BlogPost[];
+      siteConfig: DocusaurusConfig;
+      outDir: string;
+      defaultCreateFeedItems: (params: {
+        blogPosts: BlogPost[];
+        siteConfig: DocusaurusConfig;
+        outDir: string;
+      }) => Promise<BlogFeedItem[]>;
+    }) => Promise<BlogFeedItem[]>;
   };
 };
 ```
@@ -529,6 +540,16 @@ module.exports = {
           feedOptions: {
             type: 'all',
             copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
+            createFeedItems: async (options) => {
+              const {blogPosts, defaultCreateFeedItems, ...others} = options;
+              const blogPostsFiltered = blogPosts.filter(
+                (item, index) => index < 2,
+              );
+              return defaultCreateFeedItems({
+                blogPosts: blogPostsFiltered,
+                ...others,
+              });
+            },
           },
           // highlight-end
         },

website/docusaurus.config.js

@@ -341,6 +341,11 @@ const config = {
           feedOptions: {
             type: 'all',
             copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
+            createFeedItems: async (options) => {
+              const { blogPosts, defaultCreateFeedItems, ...others } = options;
+              const blogPostsFiltered = blogPosts.filter((item, index) => index < 2);
+              return defaultCreateFeedItems({ blogPosts: blogPostsFiltered, ...others });
+            }
           },
           blogSidebarCount: 'ALL',
           blogSidebarTitle: 'All our posts',