@docusaurus/plugin-content-blog 2.0.0-beta.ff31de0ff → 2.0.0-rc.1

package/src/blogUtils.ts

@@ -6,253 +6,378 @@
  */
 
 import fs from 'fs-extra';
-import globby from 'globby';
-import chalk from 'chalk';
 import path from 'path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
 import readingTime from 'reading-time';
-import {Feed} from 'feed';
-import {keyBy, mapValues} from 'lodash';
 import {
-  PluginOptions,
-  BlogPost,
-  DateLink,
-  BlogContentPaths,
-  BlogMarkdownLoaderOptions,
-} from './types';
-import {
-  parseMarkdownFile,
+  parseMarkdownString,
   normalizeUrl,
   aliasedSitePath,
   getEditUrl,
   getFolderContainingFile,
   posixPath,
   replaceMarkdownLinks,
+  Globby,
+  normalizeFrontMatterTags,
+  groupTaggedItems,
+  getFileCommitDate,
+  getContentPathList,
 } from '@docusaurus/utils';
-import {LoadContext} from '@docusaurus/types';
-import {validateBlogPostFrontMatter} from './blogFrontMatter';
+import {validateBlogPostFrontMatter} from './frontMatter';
+import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import type {LoadContext} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  ReadingTimeFunction,
+  BlogPost,
+  BlogTags,
+  BlogPaginated,
+} from '@docusaurus/plugin-content-blog';
+import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 
 export function truncate(fileString: string, truncateMarker: RegExp): string {
   return fileString.split(truncateMarker, 1).shift()!;
 }
 
-export function getSourceToPermalink(
-  blogPosts: BlogPost[],
-): Record<string, string> {
-  return mapValues(
-    keyBy(blogPosts, (item) => item.metadata.source),
-    (v) => v.metadata.permalink,
+export function getSourceToPermalink(blogPosts: BlogPost[]): {
+  [aliasedPath: string]: string;
+} {
+  return Object.fromEntries(
+    blogPosts.map(({metadata: {source, permalink}}) => [source, permalink]),
   );
 }
 
-// YYYY-MM-DD-{name}.mdx?
-// Prefer named capture, but older Node versions do not support it.
-const DATE_FILENAME_PATTERN = /^(\d{4}-\d{1,2}-\d{1,2})-?(.*?).mdx?$/;
+export function paginateBlogPosts({
+  blogPosts,
+  basePageUrl,
+  blogTitle,
+  blogDescription,
+  postsPerPageOption,
+}: {
+  blogPosts: BlogPost[];
+  basePageUrl: string;
+  blogTitle: string;
+  blogDescription: string;
+  postsPerPageOption: number | 'ALL';
+}): BlogPaginated[] {
+  const totalCount = blogPosts.length;
+  const postsPerPage =
+    postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
+  const numberOfPages = Math.ceil(totalCount / postsPerPage);
+
+  const pages: BlogPaginated[] = [];
+
+  function permalink(page: number) {
+    return page > 0
+      ? normalizeUrl([basePageUrl, `page/${page + 1}`])
+      : basePageUrl;
+  }
+
+  for (let page = 0; page < numberOfPages; page += 1) {
+    pages.push({
+      items: blogPosts
+        .slice(page * postsPerPage, (page + 1) * postsPerPage)
+        .map((item) => item.id),
+      metadata: {
+        permalink: permalink(page),
+        page: page + 1,
+        postsPerPage,
+        totalPages: numberOfPages,
+        totalCount,
+        previousPage: page !== 0 ? permalink(page - 1) : undefined,
+        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : undefined,
+        blogDescription,
+        blogTitle,
+      },
+    });
+  }
+
+  return pages;
+}
+
+export function getBlogTags({
+  blogPosts,
+  ...params
+}: {
+  blogPosts: BlogPost[];
+  blogTitle: string;
+  blogDescription: string;
+  postsPerPageOption: number | 'ALL';
+}): BlogTags {
+  const groups = groupTaggedItems(
+    blogPosts,
+    (blogPost) => blogPost.metadata.tags,
+  );
 
-function toUrl({date, link}: DateLink) {
-  return `${date
-    .toISOString()
-    .substring(0, '2019-01-01'.length)
-    .replace(/-/g, '/')}/${link}`;
+  return _.mapValues(groups, ({tag, items: tagBlogPosts}) => ({
+    label: tag.label,
+    items: tagBlogPosts.map((item) => item.id),
+    permalink: tag.permalink,
+    pages: paginateBlogPosts({
+      blogPosts: tagBlogPosts,
+      basePageUrl: tag.permalink,
+      ...params,
+    }),
+  }));
 }
 
-export async function generateBlogFeed(
-  contentPaths: BlogContentPaths,
-  context: LoadContext,
-  options: PluginOptions,
-): Promise<Feed | null> {
-  if (!options.feedOptions) {
-    throw new Error(
-      'Invalid options - `feedOptions` is not expected to be null.',
-    );
-  }
-  const {siteConfig} = context;
-  const blogPosts = await generateBlogPosts(contentPaths, context, options);
-  if (blogPosts == null) {
-    return null;
+const DATE_FILENAME_REGEX =
+  /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(?:\/index)?.mdx?$/;
+
+type ParsedBlogFileName = {
+  date: Date | undefined;
+  text: string;
+  slug: string;
+};
+
+export function parseBlogFileName(
+  blogSourceRelative: string,
+): ParsedBlogFileName {
+  const dateFilenameMatch = blogSourceRelative.match(DATE_FILENAME_REGEX);
+  if (dateFilenameMatch) {
+    const {folder, text, date: dateString} = dateFilenameMatch.groups!;
+    // Always treat dates as UTC by adding the `Z`
+    const date = new Date(`${dateString!}Z`);
+    const slugDate = dateString!.replace(/-/g, '/');
+    const slug = `/${slugDate}/${folder!}${text!}`;
+    return {date, text: text!, slug};
   }
+  const text = blogSourceRelative.replace(/(?:\/index)?\.mdx?$/, '');
+  const slug = `/${text}`;
+  return {date: undefined, text, slug};
+}
 
-  const {feedOptions, routeBasePath} = options;
-  const {url: siteUrl, title, favicon} = siteConfig;
-  const blogBaseUrl = normalizeUrl([siteUrl, routeBasePath]);
-
-  const updated =
-    (blogPosts[0] && blogPosts[0].metadata.date) ||
-    new Date('2015-10-25T16:29:00.000-07:00');
-
-  const feed = new Feed({
-    id: blogBaseUrl,
-    title: feedOptions.title || `${title} Blog`,
-    updated,
-    language: feedOptions.language,
-    link: blogBaseUrl,
-    description: feedOptions.description || `${siteConfig.title} Blog`,
-    favicon: normalizeUrl([siteUrl, favicon]),
-    copyright: feedOptions.copyright,
-  });
+function formatBlogPostDate(
+  locale: string,
+  date: Date,
+  calendar: string,
+): string {
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC',
+      calendar,
+    }).format(date);
+  } catch (err) {
+    logger.error`Can't format blog post date "${String(date)}"`;
+    throw err;
+  }
+}
 
-  blogPosts.forEach((post) => {
-    const {
-      id,
-      metadata: {title: metadataTitle, permalink, date, description},
-    } = post;
-    feed.addItem({
-      title: metadataTitle,
-      id,
-      link: normalizeUrl([siteUrl, permalink]),
-      date,
-      description,
+async function parseBlogPostMarkdownFile(blogSourceAbsolute: string) {
+  const markdownString = await fs.readFile(blogSourceAbsolute, 'utf-8');
+  try {
+    const result = parseMarkdownString(markdownString, {
+      removeContentTitle: true,
     });
-  });
-
-  return feed;
+    return {
+      ...result,
+      frontMatter: validateBlogPostFrontMatter(result.frontMatter),
+    };
+  } catch (err) {
+    logger.error`Error while parsing blog post file path=${blogSourceAbsolute}.`;
+    throw err;
+  }
 }
 
-export async function generateBlogPosts(
+const defaultReadingTime: ReadingTimeFunction = ({content, options}) =>
+  readingTime(content, options).minutes;
+
+async function processBlogSourceFile(
+  blogSourceRelative: string,
   contentPaths: BlogContentPaths,
-  {siteConfig, siteDir, i18n}: LoadContext,
+  context: LoadContext,
   options: PluginOptions,
-): Promise<BlogPost[]> {
+  authorsMap?: AuthorsMap,
+): Promise<BlogPost | undefined> {
+  const {
+    siteConfig: {baseUrl},
+    siteDir,
+    i18n,
+  } = context;
   const {
-    include,
     routeBasePath,
+    tagsBasePath: tagsRouteBasePath,
     truncateMarker,
     showReadingTime,
     editUrl,
   } = options;
 
-  if (!fs.existsSync(contentPaths.contentPath)) {
-    return [];
-  }
-
-  const {baseUrl = ''} = siteConfig;
-  const blogSourceFiles = await globby(include, {
-    cwd: contentPaths.contentPath,
-  });
+  // Lookup in localized folder in priority
+  const blogDirPath = await getFolderContainingFile(
+    getContentPathList(contentPaths),
+    blogSourceRelative,
+  );
 
-  const blogPosts: BlogPost[] = [];
+  const blogSourceAbsolute = path.join(blogDirPath, blogSourceRelative);
 
-  await Promise.all(
-    blogSourceFiles.map(async (blogSourceFile: string) => {
-      // Lookup in localized folder in priority
-      const blogDirPath = await getFolderContainingFile(
-        getContentPathList(contentPaths),
-        blogSourceFile,
-      );
+  const {frontMatter, content, contentTitle, excerpt} =
+    await parseBlogPostMarkdownFile(blogSourceAbsolute);
 
-      const source = path.join(blogDirPath, blogSourceFile);
+  const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir);
 
-      const {
-        frontMatter: unsafeFrontMatter,
-        content,
-        contentTitle,
-        excerpt,
-      } = await parseMarkdownFile(source);
-      const frontMatter = validateBlogPostFrontMatter(unsafeFrontMatter);
+  if (frontMatter.draft && process.env.NODE_ENV === 'production') {
+    return undefined;
+  }
 
-      const aliasedSource = aliasedSitePath(source, siteDir);
+  if (frontMatter.id) {
+    logger.warn`name=${'id'} header option is deprecated in path=${blogSourceRelative} file. Please use name=${'slug'} option instead.`;
+  }
 
-      const blogFileName = path.basename(blogSourceFile);
+  const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
 
-      if (frontMatter.draft && process.env.NODE_ENV === 'production') {
-        return;
+  async function getDate(): Promise<Date> {
+    // Prefer user-defined date.
+    if (frontMatter.date) {
+      if (typeof frontMatter.date === 'string') {
+        // Always treat dates as UTC by adding the `Z`
+        return new Date(`${frontMatter.date}Z`);
       }
+      // YAML only converts YYYY-MM-DD to dates and leaves others as strings.
+      return frontMatter.date;
+    } else if (parsedBlogFileName.date) {
+      return parsedBlogFileName.date;
+    }
+
+    try {
+      const result = getFileCommitDate(blogSourceAbsolute, {
+        age: 'oldest',
+        includeAuthor: false,
+      });
+      return result.date;
+    } catch (err) {
+      logger.warn(err);
+      return (await fs.stat(blogSourceAbsolute)).birthtime;
+    }
+  }
 
-      if (frontMatter.id) {
-        console.warn(
-          chalk.yellow(
-            `${blogFileName} - 'id' header option is deprecated. Please use 'slug' option instead.`,
-          ),
-        );
-      }
+  const date = await getDate();
+  const formattedDate = formatBlogPostDate(
+    i18n.currentLocale,
+    date,
+    i18n.localeConfigs[i18n.currentLocale]!.calendar,
+  );
 
-      let date: Date | undefined;
-      // Extract date and title from filename.
-      const dateFilenameMatch = blogFileName.match(DATE_FILENAME_PATTERN);
-      let linkName = blogFileName.replace(/\.mdx?$/, '');
+  const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
+  const description = frontMatter.description ?? excerpt ?? '';
 
-      if (dateFilenameMatch) {
-        const [, dateString, name] = dateFilenameMatch;
-        date = new Date(dateString);
-        linkName = name;
-      }
+  const slug = frontMatter.slug ?? parsedBlogFileName.slug;
 
-      // Prefer user-defined date.
-      if (frontMatter.date) {
-        date = frontMatter.date;
-      }
+  const permalink = normalizeUrl([baseUrl, routeBasePath, slug]);
 
-      // Use file create time for blog.
-      date = date ?? (await fs.stat(source)).birthtime;
-      const formattedDate = new Intl.DateTimeFormat(i18n.currentLocale, {
-        day: 'numeric',
-        month: 'long',
-        year: 'numeric',
-      }).format(date);
-
-      const title = frontMatter.title ?? contentTitle ?? linkName;
-      const description = frontMatter.description ?? excerpt ?? '';
-
-      const slug =
-        frontMatter.slug ||
-        (dateFilenameMatch ? toUrl({date, link: linkName}) : linkName);
-
-      const permalink = normalizeUrl([baseUrl, routeBasePath, slug]);
-
-      function getBlogEditUrl() {
-        const blogPathRelative = path.relative(
-          blogDirPath,
-          path.resolve(source),
-        );
-
-        if (typeof editUrl === 'function') {
-          return editUrl({
-            blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
-            blogPath: posixPath(blogPathRelative),
-            permalink,
-            locale: i18n.currentLocale,
-          });
-        } else if (typeof editUrl === 'string') {
-          const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
-          const fileContentPath =
-            isLocalized && options.editLocalizedFiles
-              ? contentPaths.contentPathLocalized
-              : contentPaths.contentPath;
-
-          const contentPathEditUrl = normalizeUrl([
-            editUrl,
-            posixPath(path.relative(siteDir, fileContentPath)),
-          ]);
-
-          return getEditUrl(blogPathRelative, contentPathEditUrl);
-        } else {
-          return undefined;
-        }
-      }
+  function getBlogEditUrl() {
+    const blogPathRelative = path.relative(
+      blogDirPath,
+      path.resolve(blogSourceAbsolute),
+    );
 
-      blogPosts.push({
-        id: frontMatter.slug ?? title,
-        metadata: {
-          permalink,
-          editUrl: getBlogEditUrl(),
-          source: aliasedSource,
-          title,
-          description,
-          date,
-          formattedDate,
-          tags: frontMatter.tags ?? [],
-          readingTime: showReadingTime
-            ? readingTime(content).minutes
-            : undefined,
-          truncated: truncateMarker?.test(content) || false,
-        },
+    if (typeof editUrl === 'function') {
+      return editUrl({
+        blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
+        blogPath: posixPath(blogPathRelative),
+        permalink,
+        locale: i18n.currentLocale,
       });
-    }),
-  );
+    } else if (typeof editUrl === 'string') {
+      const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
+      const fileContentPath =
+        isLocalized && options.editLocalizedFiles
+          ? contentPaths.contentPathLocalized
+          : contentPaths.contentPath;
+
+      const contentPathEditUrl = normalizeUrl([
+        editUrl,
+        posixPath(path.relative(siteDir, fileContentPath)),
+      ]);
+
+      return getEditUrl(blogPathRelative, contentPathEditUrl);
+    }
+    return undefined;
+  }
+
+  const tagsBasePath = normalizeUrl([
+    baseUrl,
+    routeBasePath,
+    tagsRouteBasePath,
+  ]);
+  const authors = getBlogPostAuthors({authorsMap, frontMatter});
+
+  return {
+    id: slug,
+    metadata: {
+      permalink,
+      editUrl: getBlogEditUrl(),
+      source: aliasedSource,
+      title,
+      description,
+      date,
+      formattedDate,
+      tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
+      readingTime: showReadingTime
+        ? options.readingTime({
+            content,
+            frontMatter,
+            defaultReadingTime,
+          })
+        : undefined,
+      hasTruncateMarker: truncateMarker.test(content),
+      authors,
+      frontMatter,
+    },
+    content,
+  };
+}
+
+export async function generateBlogPosts(
+  contentPaths: BlogContentPaths,
+  context: LoadContext,
+  options: PluginOptions,
+): Promise<BlogPost[]> {
+  const {include, exclude} = options;
+
+  if (!(await fs.pathExists(contentPaths.contentPath))) {
+    return [];
+  }
+
+  const blogSourceFiles = await Globby(include, {
+    cwd: contentPaths.contentPath,
+    ignore: exclude,
+  });
+
+  const authorsMap = await getAuthorsMap({
+    contentPaths,
+    authorsMapPath: options.authorsMapPath,
+  });
+
+  const blogPosts = (
+    await Promise.all(
+      blogSourceFiles.map(async (blogSourceFile: string) => {
+        try {
+          return await processBlogSourceFile(
+            blogSourceFile,
+            contentPaths,
+            context,
+            options,
+            authorsMap,
+          );
+        } catch (err) {
+          logger.error`Processing of blog source file path=${blogSourceFile} failed.`;
+          throw err;
+        }
+      }),
+    )
+  ).filter(Boolean) as BlogPost[];
 
   blogPosts.sort(
     (a, b) => b.metadata.date.getTime() - a.metadata.date.getTime(),
   );
 
+  if (options.sortPosts === 'ascending') {
+    return blogPosts.reverse();
+  }
   return blogPosts;
 }
 
@@ -284,8 +409,3 @@ export function linkify({
 
   return newContent;
 }
-
-// Order matters: we look in priority in localized folder
-export function getContentPathList(contentPaths: BlogContentPaths): string[] {
-  return [contentPaths.contentPathLocalized, contentPaths.contentPath];
-}