@docusaurus/plugin-content-blog 0.0.0-6012 → 0.0.0-6016

package/src/authors.ts

@@ -5,83 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import * as _ from 'lodash';
-import {getDataFileData, normalizeUrl} from '@docusaurus/utils';
-import {Joi, URISchema} from '@docusaurus/utils-validation';
-import {AuthorSocialsSchema, normalizeSocials} from './authorsSocials';
-import type {BlogContentPaths} from './types';
+import _ from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
 import type {
   Author,
+  AuthorsMap,
+  BlogPost,
   BlogPostFrontMatter,
   BlogPostFrontMatterAuthor,
-  BlogPostFrontMatterAuthors,
 } from '@docusaurus/plugin-content-blog';
 
-export type AuthorsMap = {[authorKey: string]: Author};
-
-const AuthorsMapSchema = Joi.object<AuthorsMap>()
-  .pattern(
-    Joi.string(),
-    Joi.object<Author>({
-      name: Joi.string(),
-      url: URISchema,
-      imageURL: URISchema,
-      title: Joi.string(),
-      email: Joi.string(),
-      socials: AuthorSocialsSchema,
-    })
-      .rename('image_url', 'imageURL')
-      .or('name', 'imageURL')
-      .unknown()
-      .required()
-      .messages({
-        'object.base':
-          '{#label} should be an author object containing properties like name, title, and imageURL.',
-        'any.required':
-          '{#label} cannot be undefined. It should be an author object containing properties like name, title, and imageURL.',
-      }),
-  )
-  .messages({
-    'object.base':
-      "The authors map file should contain an object where each entry contains an author key and the corresponding author's data.",
-  });
-
-export function validateAuthorsMap(content: unknown): AuthorsMap {
-  const {error, value} = AuthorsMapSchema.validate(content);
-  if (error) {
-    throw error;
-  }
-  return value;
-}
-
-function normalizeAuthor(author: Author): Author {
-  return {
-    ...author,
-    socials: author.socials ? normalizeSocials(author.socials) : undefined,
-  };
-}
-
-function normalizeAuthorsMap(authorsMap: AuthorsMap): AuthorsMap {
-  return _.mapValues(authorsMap, normalizeAuthor);
-}
-
-export async function getAuthorsMap(params: {
-  authorsMapPath: string;
-  contentPaths: BlogContentPaths;
-}): Promise<AuthorsMap | undefined> {
-  const authorsMap = await getDataFileData(
-    {
-      filePath: params.authorsMapPath,
-      contentPaths: params.contentPaths,
-      fileType: 'authors map',
-    },
-    // TODO annoying to test: tightly coupled FS reads + validation...
-    validateAuthorsMap,
-  );
-
-  return authorsMap ? normalizeAuthorsMap(authorsMap) : undefined;
-}
-
 type AuthorsParam = {
   frontMatter: BlogPostFrontMatter;
   authorsMap: AuthorsMap | undefined;
@@ -102,6 +35,7 @@ function normalizeImageUrl({
 
 // Legacy v1/early-v2 front matter fields
 // We may want to deprecate those in favor of using only frontMatter.authors
+// TODO Docusaurus v4: remove this legacy front matter
 function getFrontMatterAuthorLegacy({
   baseUrl,
   frontMatter,
@@ -123,37 +57,40 @@ function getFrontMatterAuthorLegacy({
       title,
       url,
       imageURL,
+      // legacy front matter authors do not have an author key/page
+      key: null,
+      page: null,
     };
   }
 
   return undefined;
 }
 
-function normalizeFrontMatterAuthors(
-  frontMatterAuthors: BlogPostFrontMatterAuthors = [],
-): BlogPostFrontMatterAuthor[] {
-  function normalizeFrontMatterAuthor(
-    authorInput: string | Author,
-  ): BlogPostFrontMatterAuthor {
-    if (typeof authorInput === 'string') {
-      // Technically, we could allow users to provide an author's name here, but
-      // we only support keys, otherwise, a typo in a key would fallback to
-      // becoming a name and may end up unnoticed
-      return {key: authorInput};
+function getFrontMatterAuthors(params: AuthorsParam): Author[] {
+  const {authorsMap, frontMatter, baseUrl} = params;
+  return normalizeFrontMatterAuthors().map(toAuthor);
+
+  function normalizeFrontMatterAuthors(): BlogPostFrontMatterAuthor[] {
+    if (frontMatter.authors === undefined) {
+      return [];
     }
-    return authorInput;
-  }
 
-  return Array.isArray(frontMatterAuthors)
-    ? frontMatterAuthors.map(normalizeFrontMatterAuthor)
-    : [normalizeFrontMatterAuthor(frontMatterAuthors)];
-}
+    function normalizeAuthor(
+      authorInput: string | BlogPostFrontMatterAuthor,
+    ): BlogPostFrontMatterAuthor {
+      if (typeof authorInput === 'string') {
+        // We could allow users to provide an author's name here, but we only
+        // support keys, otherwise, a typo in a key would fall back to
+        // becoming a name and may end up unnoticed
+        return {key: authorInput};
+      }
+      return authorInput;
+    }
 
-function getFrontMatterAuthors(params: AuthorsParam): Author[] {
-  const {authorsMap} = params;
-  const frontMatterAuthors = normalizeFrontMatterAuthors(
-    params.frontMatter.authors,
-  );
+    return Array.isArray(frontMatter.authors)
+      ? frontMatter.authors.map(normalizeAuthor)
+      : [normalizeAuthor(frontMatter.authors)];
+  }
 
   function getAuthorsMapAuthor(key: string | undefined): Author | undefined {
     if (key) {
@@ -175,36 +112,29 @@ ${Object.keys(authorsMap)
   }
 
   function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
-    return normalizeAuthor({
+    const author = {
       // Author def from authorsMap can be locally overridden by front matter
       ...getAuthorsMapAuthor(frontMatterAuthor.key),
       ...frontMatterAuthor,
-    });
-  }
-
-  return frontMatterAuthors.map(toAuthor);
-}
+    };
 
-function fixAuthorImageBaseURL(
-  authors: Author[],
-  {baseUrl}: {baseUrl: string},
-) {
-  return authors.map((author) => ({
-    ...author,
-    imageURL: normalizeImageUrl({imageURL: author.imageURL, baseUrl}),
-  }));
+    return {
+      ...author,
+      key: author.key ?? null,
+      page: author.page ?? null,
+      imageURL: normalizeImageUrl({imageURL: author.imageURL, baseUrl}),
+    };
+  }
 }
 
 export function getBlogPostAuthors(params: AuthorsParam): Author[] {
   const authorLegacy = getFrontMatterAuthorLegacy(params);
   const authors = getFrontMatterAuthors(params);
 
-  const updatedAuthors = fixAuthorImageBaseURL(authors, params);
-
   if (authorLegacy) {
     // Technically, we could allow mixing legacy/authors front matter, but do we
     // really want to?
-    if (updatedAuthors.length > 0) {
+    if (authors.length > 0) {
       throw new Error(
         `To declare blog post authors, use the 'authors' front matter in priority.
 Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.`,
@@ -213,5 +143,21 @@ Don't mix 'authors' with other existing 'author_*' front matter. Choose one or t
     return [authorLegacy];
   }
 
-  return updatedAuthors;
+  return authors;
+}
+
+/**
+ * Group blog posts by author key
+ * Blog posts with only inline authors are ignored
+ */
+export function groupBlogPostsByAuthorKey({
+  blogPosts,
+  authorsMap,
+}: {
+  blogPosts: BlogPost[];
+  authorsMap: AuthorsMap | undefined;
+}): Record<string, BlogPost[]> {
+  return _.mapValues(authorsMap, (author, key) =>
+    blogPosts.filter((p) => p.metadata.authors.some((a) => a.key === key)),
+  );
 }

package/src/authorsMap.ts

@@ -0,0 +1,171 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import _ from 'lodash';
+import {readDataFile, normalizeUrl} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import {AuthorSocialsSchema, normalizeSocials} from './authorsSocials';
+import type {BlogContentPaths} from './types';
+import type {
+  Author,
+  AuthorAttributes,
+  AuthorPage,
+  AuthorsMap,
+} from '@docusaurus/plugin-content-blog';
+
+type AuthorInput = AuthorAttributes & {
+  page?: boolean | AuthorPage;
+};
+
+export type AuthorsMapInput = {[authorKey: string]: AuthorInput};
+
+const AuthorPageSchema = Joi.object<AuthorPage>({
+  permalink: Joi.string().required(),
+});
+
+const AuthorsMapInputSchema = Joi.object<AuthorsMapInput>()
+  .pattern(
+    Joi.string(),
+    Joi.object({
+      name: Joi.string(),
+      url: URISchema,
+      imageURL: URISchema,
+      title: Joi.string(),
+      email: Joi.string(),
+      page: Joi.alternatives(Joi.bool(), AuthorPageSchema),
+      socials: AuthorSocialsSchema,
+      description: Joi.string(),
+    })
+      .rename('image_url', 'imageURL')
+      .or('name', 'imageURL')
+      .unknown()
+      .required()
+      .messages({
+        'object.base':
+          '{#label} should be an author object containing properties like name, title, and imageURL.',
+        'any.required':
+          '{#label} cannot be undefined. It should be an author object containing properties like name, title, and imageURL.',
+      }),
+  )
+  .messages({
+    'object.base':
+      "The authors map file should contain an object where each entry contains an author key and the corresponding author's data.",
+  });
+
+export function checkAuthorsMapPermalinkCollisions(
+  authorsMap: AuthorsMap | undefined,
+): void {
+  if (!authorsMap) {
+    return;
+  }
+
+  const permalinkCounts = _(authorsMap)
+    // Filter to keep only authors with a page
+    .pickBy((author) => !!author.page)
+    // Group authors by their permalink
+    .groupBy((author) => author.page?.permalink)
+    // Filter to keep only permalinks with more than one author
+    .pickBy((authors) => authors.length > 1)
+    // Transform the object into an array of [permalink, authors] pairs
+    .toPairs()
+    .value();
+
+  if (permalinkCounts.length > 0) {
+    const errorMessage = permalinkCounts
+      .map(
+        ([permalink, authors]) =>
+          `Permalink: ${permalink}\nAuthors: ${authors
+            .map((author) => author.name || 'Unknown')
+            .join(', ')}`,
+      )
+      .join('\n');
+
+    throw new Error(
+      `The following permalinks are duplicated:\n${errorMessage}`,
+    );
+  }
+}
+
+function normalizeAuthor({
+  authorsBaseRoutePath,
+  authorKey,
+  author,
+}: {
+  authorsBaseRoutePath: string;
+  authorKey: string;
+  author: AuthorInput;
+}): Author & {key: string} {
+  function getAuthorPage(): AuthorPage | null {
+    if (!author.page) {
+      return null;
+    }
+    const slug =
+      author.page === true ? _.kebabCase(authorKey) : author.page.permalink;
+    return {
+      permalink: normalizeUrl([authorsBaseRoutePath, slug]),
+    };
+  }
+
+  return {
+    ...author,
+    key: authorKey,
+    page: getAuthorPage(),
+    socials: author.socials ? normalizeSocials(author.socials) : undefined,
+  };
+}
+
+function normalizeAuthorsMap({
+  authorsBaseRoutePath,
+  authorsMapInput,
+}: {
+  authorsBaseRoutePath: string;
+  authorsMapInput: AuthorsMapInput;
+}): AuthorsMap {
+  return _.mapValues(authorsMapInput, (author, authorKey) => {
+    return normalizeAuthor({authorsBaseRoutePath, authorKey, author});
+  });
+}
+
+export function validateAuthorsMapInput(content: unknown): AuthorsMapInput {
+  const {error, value} = AuthorsMapInputSchema.validate(content);
+  if (error) {
+    throw error;
+  }
+  return value;
+}
+
+async function getAuthorsMapInput(params: {
+  authorsMapPath: string;
+  contentPaths: BlogContentPaths;
+}): Promise<AuthorsMapInput | undefined> {
+  const content = await readDataFile({
+    filePath: params.authorsMapPath,
+    contentPaths: params.contentPaths,
+  });
+  return content ? validateAuthorsMapInput(content) : undefined;
+}
+
+export async function getAuthorsMap(params: {
+  authorsMapPath: string;
+  authorsBaseRoutePath: string;
+  contentPaths: BlogContentPaths;
+}): Promise<AuthorsMap | undefined> {
+  const authorsMapInput = await getAuthorsMapInput(params);
+  if (!authorsMapInput) {
+    return undefined;
+  }
+  const authorsMap = normalizeAuthorsMap({authorsMapInput, ...params});
+  return authorsMap;
+}
+
+export function validateAuthorsMap(content: unknown): AuthorsMapInput {
+  const {error, value} = AuthorsMapInputSchema.validate(content);
+  if (error) {
+    throw error;
+  }
+  return value;
+}

package/src/blogUtils.ts

@@ -29,11 +29,12 @@ import {
 } from '@docusaurus/utils';
 import {getTagsFile} from '@docusaurus/utils-validation';
 import {validateBlogPostFrontMatter} from './frontMatter';
-import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import {getBlogPostAuthors} from './authors';
 import {reportAuthorsProblems} from './authorsProblems';
 import type {TagsFile} from '@docusaurus/utils';
 import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
+  AuthorsMap,
   PluginOptions,
   ReadingTimeFunction,
   BlogPost,
@@ -64,7 +65,7 @@ export function paginateBlogPosts({
   const totalCount = blogPosts.length;
   const postsPerPage =
     postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
-  const numberOfPages = Math.ceil(totalCount / postsPerPage);
+  const numberOfPages = Math.max(1, Math.ceil(totalCount / postsPerPage));
 
   const pages: BlogPaginated[] = [];
 
@@ -366,6 +367,7 @@ export async function generateBlogPosts(
   contentPaths: BlogContentPaths,
   context: LoadContext,
   options: PluginOptions,
+  authorsMap?: AuthorsMap,
 ): Promise<BlogPost[]> {
   const {include, exclude} = options;
 
@@ -378,11 +380,6 @@ export async function generateBlogPosts(
     ignore: exclude,
   });
 
-  const authorsMap = await getAuthorsMap({
-    contentPaths,
-    authorsMapPath: options.authorsMapPath,
-  });
-
   const tagsFile = await getTagsFile({contentPaths, tags: options.tags});
 
   async function doProcessBlogSourceFile(blogSourceFile: string) {

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