@docusaurus/plugin-content-blog 3.4.0 → 3.5.0

package/src/feed.ts

@@ -7,15 +7,20 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import logger from '@docusaurus/logger';
 import {Feed, type Author as FeedAuthor} from 'feed';
 import * as srcset from 'srcset';
-import {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
+import {
+  getDataFilePath,
+  normalizeUrl,
+  readOutputHTMLFile,
+} from '@docusaurus/utils';
 import {
   blogPostContainerID,
   applyTrailingSlash,
 } from '@docusaurus/utils-common';
 import {load as cheerioLoad} from 'cheerio';
+import logger from '@docusaurus/logger';
+import type {BlogContentPaths} from './types';
 import type {DocusaurusConfig, HtmlTags, LoadContext} from '@docusaurus/types';
 import type {
   FeedType,
@@ -23,6 +28,8 @@ import type {
   Author,
   BlogPost,
   BlogFeedItem,
+  FeedOptions,
+  FeedXSLTOptions,
 } from '@docusaurus/plugin-content-blog';
 
 async function generateBlogFeed({
@@ -180,32 +187,144 @@ async function defaultCreateFeedItems({
   );
 }
 
+async function resolveXsltFilePaths({
+  xsltFilePath,
+  contentPaths,
+}: {
+  xsltFilePath: string;
+  contentPaths: BlogContentPaths;
+}) {
+  const xsltAbsolutePath: string = path.isAbsolute(xsltFilePath)
+    ? xsltFilePath
+    : (await getDataFilePath({filePath: xsltFilePath, contentPaths})) ??
+      path.resolve(contentPaths.contentPath, xsltFilePath);
+
+  if (!(await fs.pathExists(xsltAbsolutePath))) {
+    throw new Error(
+      logger.interpolate`Blog feed XSLT file not found at path=${path.relative(
+        process.cwd(),
+        xsltAbsolutePath,
+      )}`,
+    );
+  }
+
+  const parsedPath = path.parse(xsltAbsolutePath);
+  const cssAbsolutePath = path.resolve(
+    parsedPath.dir,
+    `${parsedPath.name}.css`,
+  );
+  if (!(await fs.pathExists(xsltAbsolutePath))) {
+    throw new Error(
+      logger.interpolate`Blog feed XSLT file was found at path=${path.relative(
+        process.cwd(),
+        xsltAbsolutePath,
+      )}
+But its expected co-located CSS file could not be found at path=${path.relative(
+        process.cwd(),
+        cssAbsolutePath,
+      )}
+If you want to provide a custom XSLT file, you must provide a CSS file with the exact same name.`,
+    );
+  }
+
+  return {xsltAbsolutePath, cssAbsolutePath};
+}
+
+async function generateXsltFiles({
+  xsltFilePath,
+  generatePath,
+  contentPaths,
+}: {
+  xsltFilePath: string;
+  generatePath: string;
+  contentPaths: BlogContentPaths;
+}) {
+  const {xsltAbsolutePath, cssAbsolutePath} = await resolveXsltFilePaths({
+    xsltFilePath,
+    contentPaths,
+  });
+  const xsltOutputPath = path.join(
+    generatePath,
+    path.basename(xsltAbsolutePath),
+  );
+  const cssOutputPath = path.join(generatePath, path.basename(cssAbsolutePath));
+  await fs.copy(xsltAbsolutePath, xsltOutputPath);
+  await fs.copy(cssAbsolutePath, cssOutputPath);
+}
+
+// This modifies the XML feed content to add a relative href to the XSLT file
+// Good enough for now: we probably don't need a full XML parser just for that
+// See also https://darekkay.com/blog/rss-styling/
+function injectXslt({
+  feedContent,
+  xsltFilePath,
+}: {
+  feedContent: string;
+  xsltFilePath: string;
+}) {
+  return feedContent.replace(
+    '<?xml version="1.0" encoding="utf-8"?>',
+    `<?xml version="1.0" encoding="utf-8"?><?xml-stylesheet type="text/xsl" href="${path.basename(
+      xsltFilePath,
+    )}"?>`,
+  );
+}
+
+const FeedConfigs: Record<
+  FeedType,
+  {
+    outputFileName: string;
+    getContent: (feed: Feed) => string;
+    getXsltFilePath: (xslt: FeedXSLTOptions) => string | null;
+  }
+> = {
+  rss: {
+    outputFileName: 'rss.xml',
+    getContent: (feed) => feed.rss2(),
+    getXsltFilePath: (xslt) => xslt.rss,
+  },
+  atom: {
+    outputFileName: 'atom.xml',
+    getContent: (feed) => feed.atom1(),
+    getXsltFilePath: (xslt) => xslt.atom,
+  },
+  json: {
+    outputFileName: 'feed.json',
+    getContent: (feed) => feed.json1(),
+    getXsltFilePath: () => null,
+  },
+};
+
 async function createBlogFeedFile({
   feed,
   feedType,
   generatePath,
+  feedOptions,
+  contentPaths,
 }: {
   feed: Feed;
   feedType: FeedType;
   generatePath: string;
+  feedOptions: FeedOptions;
+  contentPaths: BlogContentPaths;
 }) {
-  const [feedContent, feedPath] = (() => {
-    switch (feedType) {
-      case 'rss':
-        return [feed.rss2(), 'rss.xml'];
-      case 'json':
-        return [feed.json1(), 'feed.json'];
-      case 'atom':
-        return [feed.atom1(), 'atom.xml'];
-      default:
-        throw new Error(`Feed type ${feedType} not supported.`);
-    }
-  })();
   try {
-    await fs.outputFile(path.join(generatePath, feedPath), feedContent);
+    const feedConfig = FeedConfigs[feedType];
+
+    let feedContent = feedConfig.getContent(feed);
+
+    const xsltFilePath = feedConfig.getXsltFilePath(feedOptions.xslt);
+    if (xsltFilePath) {
+      await generateXsltFiles({xsltFilePath, contentPaths, generatePath});
+      feedContent = injectXslt({feedContent, xsltFilePath});
+    }
+
+    const outputPath = path.join(generatePath, feedConfig.outputFileName);
+    await fs.outputFile(outputPath, feedContent);
   } catch (err) {
-    logger.error(`Generating ${feedType} feed failed.`);
-    throw err;
+    throw new Error(`Generating ${feedType} feed failed.`, {
+      cause: err as Error,
+    });
   }
 }
 
@@ -222,12 +341,14 @@ export async function createBlogFeedFiles({
   siteConfig,
   outDir,
   locale,
+  contentPaths,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
   outDir: string;
   locale: string;
+  contentPaths: BlogContentPaths;
 }): Promise<void> {
   const blogPosts = allBlogPosts.filter(shouldBeInFeed);
 
@@ -250,6 +371,8 @@ export async function createBlogFeedFiles({
         feed,
         feedType,
         generatePath: path.join(outDir, options.routeBasePath),
+        feedOptions: options.feedOptions,
+        contentPaths,
       }),
     ),
   );

package/src/frontMatter.ts

@@ -13,6 +13,7 @@ import {
   URISchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
+import {AuthorSocialsSchema} from './authorsSocials';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
 const BlogPostFrontMatterAuthorSchema = Joi.object({
@@ -21,6 +22,7 @@ const BlogPostFrontMatterAuthorSchema = Joi.object({
   title: Joi.string(),
   url: URISchema,
   imageURL: Joi.string(),
+  socials: AuthorSocialsSchema,
 })
   .or('key', 'name', 'imageURL')
   .rename('image_url', 'imageURL', {alias: true});

package/src/index.ts

@@ -28,12 +28,14 @@ import {
   shouldBeListed,
   applyProcessBlogPosts,
   generateBlogPosts,
+  reportUntruncatedBlogPosts,
 } from './blogUtils';
 import footnoteIDFixer from './remark/footnoteIDFixer';
 import {translateContent, getTranslationFiles} from './translations';
 import {createBlogFeedFiles, createFeedHtmlHeadTags} from './feed';
 
 import {createAllRoutes} from './routes';
+import {checkAuthorsMapPermalinkCollisions, getAuthorsMap} from './authorsMap';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {
@@ -160,15 +162,38 @@ export default async function pluginContentBlog(
         blogTitle,
         blogSidebarTitle,
         pageBasePath,
+        authorsBasePath,
+        authorsMapPath,
       } = options;
 
       const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
       const blogTagsListPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
-      let blogPosts = await generateBlogPosts(contentPaths, context, options);
+
+      const authorsMap = await getAuthorsMap({
+        contentPaths,
+        authorsMapPath,
+        authorsBaseRoutePath: normalizeUrl([
+          baseUrl,
+          routeBasePath,
+          authorsBasePath,
+        ]),
+      });
+      checkAuthorsMapPermalinkCollisions(authorsMap);
+
+      let blogPosts = await generateBlogPosts(
+        contentPaths,
+        context,
+        options,
+        authorsMap,
+      );
       blogPosts = await applyProcessBlogPosts({
         blogPosts,
         processBlogPosts: options.processBlogPosts,
       });
+      reportUntruncatedBlogPosts({
+        blogPosts,
+        onUntruncatedBlogPosts: options.onUntruncatedBlogPosts,
+      });
       const listedBlogPosts = blogPosts.filter(shouldBeListed);
 
       if (!blogPosts.length) {
@@ -178,6 +203,7 @@ export default async function pluginContentBlog(
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath,
+          authorsMap,
         };
       }
 
@@ -226,6 +252,7 @@ export default async function pluginContentBlog(
         blogListPaginated,
         blogTags,
         blogTagsListPath,
+        authorsMap,
       };
     },
 
@@ -250,6 +277,7 @@ export default async function pluginContentBlog(
         admonitions,
         rehypePlugins,
         remarkPlugins,
+        recmaPlugins,
         truncateMarker,
         beforeDefaultRemarkPlugins,
         beforeDefaultRehypePlugins,
@@ -262,6 +290,7 @@ export default async function pluginContentBlog(
           admonitions,
           remarkPlugins,
           rehypePlugins,
+          recmaPlugins,
           beforeDefaultRemarkPlugins: [
             footnoteIDFixer,
             ...beforeDefaultRemarkPlugins,
@@ -364,6 +393,7 @@ export default async function pluginContentBlog(
         outDir,
         siteConfig,
         locale: currentLocale,
+        contentPaths,
       });
     },
 

package/src/options.ts

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import path from 'path';
 import {
   Joi,
   RemarkPluginsSchema,
   RehypePluginsSchema,
+  RecmaPluginsSchema,
   AdmonitionsSchema,
   RouteBasePathSchema,
   URISchema,
@@ -18,20 +20,32 @@ import type {
   PluginOptions,
   Options,
   FeedType,
+  FeedXSLTOptions,
 } from '@docusaurus/plugin-content-blog';
 import type {OptionValidationContext} from '@docusaurus/types';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
-  feedOptions: {type: ['rss', 'atom'], copyright: '', limit: 20},
+  feedOptions: {
+    type: ['rss', 'atom'],
+    copyright: '',
+    limit: 20,
+    xslt: {
+      rss: null,
+      atom: null,
+    },
+  },
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: true,
   truncateMarker: /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/,
   rehypePlugins: [],
   remarkPlugins: [],
+  recmaPlugins: [],
   showReadingTime: true,
   blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
   blogTagsListComponent: '@theme/BlogTagsListPage',
+  blogAuthorsPostsComponent: '@theme/Blog/Pages/BlogAuthorsPostsPage',
+  blogAuthorsListComponent: '@theme/Blog/Pages/BlogAuthorsListPage',
   blogPostComponent: '@theme/BlogPostPage',
   blogListComponent: '@theme/BlogListPage',
   blogArchiveComponent: '@theme/BlogArchivePage',
@@ -56,8 +70,99 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   processBlogPosts: async () => undefined,
   onInlineTags: 'warn',
   tags: undefined,
+  authorsBasePath: 'authors',
+  onInlineAuthors: 'warn',
+  onUntruncatedBlogPosts: 'warn',
 };
 
+export const XSLTBuiltInPaths = {
+  rss: path.resolve(__dirname, '..', 'assets', 'rss.xsl'),
+  atom: path.resolve(__dirname, '..', 'assets', 'atom.xsl'),
+};
+
+function normalizeXsltOption(
+  option: string | null | boolean,
+  type: 'rss' | 'atom',
+): string | null {
+  if (typeof option === 'string') {
+    return option;
+  }
+  if (option === true) {
+    return XSLTBuiltInPaths[type];
+  }
+  return null;
+}
+
+function createXSLTFilePathSchema(type: 'atom' | 'rss') {
+  return Joi.alternatives()
+    .try(
+      Joi.string().required(),
+      Joi.boolean()
+        .allow(null, () => undefined)
+        .custom((val) => normalizeXsltOption(val, type)),
+    )
+    .optional()
+    .default(null);
+}
+
+const FeedXSLTOptionsSchema = Joi.alternatives()
+  .try(
+    Joi.object<FeedXSLTOptions>({
+      rss: createXSLTFilePathSchema('rss'),
+      atom: createXSLTFilePathSchema('atom'),
+    }).required(),
+    Joi.boolean()
+      .allow(null, () => undefined)
+      .custom((val) => ({
+        rss: normalizeXsltOption(val, 'rss'),
+        atom: normalizeXsltOption(val, 'atom'),
+      })),
+  )
+  .optional()
+  .custom((val) => {
+    if (val === null) {
+      return {
+        rss: null,
+        atom: null,
+      };
+    }
+    return val;
+  })
+  .default(DEFAULT_OPTIONS.feedOptions.xslt);
+
+const FeedOptionsSchema = Joi.object({
+  type: Joi.alternatives()
+    .try(
+      Joi.array().items(Joi.string().equal('rss', 'atom', 'json')),
+      Joi.alternatives().conditional(
+        Joi.string().equal('all', 'rss', 'atom', 'json'),
+        {
+          then: Joi.custom((val: FeedType | 'all') =>
+            val === 'all' ? ['rss', 'atom', 'json'] : [val],
+          ),
+        },
+      ),
+    )
+    .allow(null)
+    .default(DEFAULT_OPTIONS.feedOptions.type),
+  xslt: FeedXSLTOptionsSchema,
+  title: Joi.string().allow(''),
+  description: Joi.string().allow(''),
+  // Only add default value when user actually wants a feed (type is not null)
+  copyright: Joi.when('type', {
+    is: Joi.any().valid(null),
+    then: Joi.string().optional(),
+    otherwise: Joi.string()
+      .allow('')
+      .default(DEFAULT_OPTIONS.feedOptions.copyright),
+  }),
+  language: Joi.string(),
+  createFeedItems: Joi.function(),
+  limit: Joi.alternatives()
+    .try(Joi.number(), Joi.valid(null), Joi.valid(false))
+    .default(DEFAULT_OPTIONS.feedOptions.limit),
+}).default(DEFAULT_OPTIONS.feedOptions);
+
 const PluginOptionSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
   archiveBasePath: Joi.string()
@@ -79,6 +184,12 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   blogTagsPostsComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogTagsPostsComponent,
   ),
+  blogAuthorsPostsComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogAuthorsPostsComponent,
+  ),
+  blogAuthorsListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogAuthorsListComponent,
+  ),
   blogArchiveComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogArchiveComponent,
   ),
@@ -93,6 +204,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   showReadingTime: Joi.bool().default(DEFAULT_OPTIONS.showReadingTime),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
   admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
   editUrl: Joi.alternatives().try(URISchema, Joi.function()),
   editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
@@ -103,37 +215,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),
-  feedOptions: Joi.object({
-    type: Joi.alternatives()
-      .try(
-        Joi.array().items(Joi.string().equal('rss', 'atom', 'json')),
-        Joi.alternatives().conditional(
-          Joi.string().equal('all', 'rss', 'atom', 'json'),
-          {
-            then: Joi.custom((val: FeedType | 'all') =>
-              val === 'all' ? ['rss', 'atom', 'json'] : [val],
-            ),
-          },
-        ),
-      )
-      .allow(null)
-      .default(DEFAULT_OPTIONS.feedOptions.type),
-    title: Joi.string().allow(''),
-    description: Joi.string().allow(''),
-    // Only add default value when user actually wants a feed (type is not null)
-    copyright: Joi.when('type', {
-      is: Joi.any().valid(null),
-      then: Joi.string().optional(),
-      otherwise: Joi.string()
-        .allow('')
-        .default(DEFAULT_OPTIONS.feedOptions.copyright),
-    }),
-    language: Joi.string(),
-    createFeedItems: Joi.function(),
-    limit: Joi.alternatives()
-      .try(Joi.number(), Joi.valid(null), Joi.valid(false))
-      .default(DEFAULT_OPTIONS.feedOptions.limit),
-  }).default(DEFAULT_OPTIONS.feedOptions),
+  feedOptions: FeedOptionsSchema,
   authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
   readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),
   sortPosts: Joi.string()
@@ -153,6 +235,15 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     .disallow('')
     .allow(null, false)
     .default(() => DEFAULT_OPTIONS.tags),
+  authorsBasePath: Joi.string()
+    .default(DEFAULT_OPTIONS.authorsBasePath)
+    .disallow(''),
+  onInlineAuthors: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onInlineAuthors),
+  onUntruncatedBlogPosts: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onUntruncatedBlogPosts),
 }).default(DEFAULT_OPTIONS);
 
 export function validateOptions({