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,7 +9,7 @@ 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 {Overwrite} from 'utility-types';
 
   export type Assets = {
@@ -263,6 +263,17 @@ declare module '@docusaurus/plugin-content-blog' {
     copyright: string;
     /** Language of the feed. */
     language?: string;
+    /** 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[]>;
   };
 
   /**
@@ -451,6 +462,52 @@ declare module '@docusaurus/plugin-content-blog' {
     content: string;
   };
 
+  export type BlogFeedItem = {
+    title: string;
+    id?: string;
+    link: string;
+    date: Date;
+    description?: string;
+    content?: string;
+    category?: Category[];
+    guid?: string;
+    image?: string | Enclosure;
+    audio?: string | Enclosure;
+    video?: string | Enclosure;
+    enclosure?: Enclosure;
+    author?: BlogFeedItemAuthor[];
+    contributor?: BlogFeedItemAuthor[];
+    published?: Date;
+    copyright?: string;
+    extensions?: Extension[];
+  };
+
+  export type BlogFeedItemAuthor = {
+    name?: string;
+    email?: string;
+    link?: string;
+  };
+
+  export type Enclosure = {
+    url: string;
+    type?: string;
+    length?: number;
+    title?: string;
+    duration?: number;
+  };
+
+  export type Extension = {
+    name: string;
+    objects: unknown;
+  };
+
+  export type Category = {
+    name?: string;
+    domain?: string;
+    scheme?: string;
+    term?: string;
+  };
+
   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',