@docusaurus/plugin-content-blog 3.3.2 → 3.5.0

package/src/feed.ts

@@ -7,22 +7,29 @@
 
 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 type {DocusaurusConfig} from '@docusaurus/types';
+import logger from '@docusaurus/logger';
+import type {BlogContentPaths} from './types';
+import type {DocusaurusConfig, HtmlTags, LoadContext} from '@docusaurus/types';
 import type {
   FeedType,
   PluginOptions,
   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,7 +371,65 @@ export async function createBlogFeedFiles({
         feed,
         feedType,
         generatePath: path.join(outDir, options.routeBasePath),
+        feedOptions: options.feedOptions,
+        contentPaths,
       }),
     ),
   );
 }
+
+export function createFeedHtmlHeadTags({
+  context,
+  options,
+}: {
+  context: LoadContext;
+  options: PluginOptions;
+}): HtmlTags {
+  const feedTypes = options.feedOptions.type;
+  if (!feedTypes) {
+    return [];
+  }
+  const feedTitle = options.feedOptions.title ?? context.siteConfig.title;
+  const feedsConfig = {
+    rss: {
+      type: 'application/rss+xml',
+      path: 'rss.xml',
+      title: `${feedTitle} RSS Feed`,
+    },
+    atom: {
+      type: 'application/atom+xml',
+      path: 'atom.xml',
+      title: `${feedTitle} Atom Feed`,
+    },
+    json: {
+      type: 'application/json',
+      path: 'feed.json',
+      title: `${feedTitle} JSON Feed`,
+    },
+  };
+  const headTags: HtmlTags = [];
+
+  feedTypes.forEach((feedType) => {
+    const {
+      type,
+      path: feedConfigPath,
+      title: feedConfigTitle,
+    } = feedsConfig[feedType];
+
+    headTags.push({
+      tagName: 'link',
+      attributes: {
+        rel: 'alternate',
+        type,
+        href: normalizeUrl([
+          context.siteConfig.baseUrl,
+          options.routeBasePath,
+          feedConfigPath,
+        ]),
+        title: feedConfigTitle,
+      },
+    });
+  });
+
+  return headTags;
+}

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});