@docusaurus/plugin-content-blog 2.0.0-beta.12faed89d → 2.0.0-beta.14

package/src/blogFrontMatter.ts

@@ -5,81 +5,119 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
   validateFrontMatter,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
 } from '@docusaurus/utils-validation';
-import {Tag} from './types';
+import type {FrontMatterTag} from '@docusaurus/utils';
+
+export type BlogPostFrontMatterAuthor = Record<string, unknown> & {
+  key?: string;
+  name?: string;
+  imageURL?: string;
+  url?: string;
+  title?: string;
+};
+
+// All the possible variants that the user can use for convenience
+export type BlogPostFrontMatterAuthors =
+  | string
+  | BlogPostFrontMatterAuthor
+  | (string | BlogPostFrontMatterAuthor)[];
+
+const BlogPostFrontMatterAuthorSchema = Joi.object({
+  key: Joi.string(),
+  name: Joi.string(),
+  title: Joi.string(),
+  url: URISchema,
+  imageURL: Joi.string(),
+})
+  .or('key', 'name')
+  .rename('image_url', 'imageURL', {alias: true});
 
 export type BlogPostFrontMatter = {
   id?: string;
   title?: string;
   description?: string;
-  tags?: (string | Tag)[];
+  tags?: FrontMatterTag[];
   slug?: string;
   draft?: boolean;
-  date?: Date;
+  date?: Date | string; // Yaml automagically convert some string patterns as Date, but not all
+
+  authors?: BlogPostFrontMatterAuthors;
 
+  // We may want to deprecate those older author frontmatter fields later:
   author?: string;
   author_title?: string;
   author_url?: string;
   author_image_url?: string;
 
-  image?: string;
-  keywords?: string[];
-  hide_table_of_contents?: boolean;
-
   /** @deprecated */
   authorTitle?: string;
+  /** @deprecated */
   authorURL?: string;
+  /** @deprecated */
   authorImageURL?: string;
+
+  image?: string;
+  keywords?: string[];
+  hide_table_of_contents?: boolean;
+  toc_min_heading_level?: number;
+  toc_max_heading_level?: number;
 };
 
-// NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
-// While the user did not provide those values explicitly
-// We use default values in code instead
-const BlogTagSchema = Joi.alternatives().try(
-  Joi.string().required(),
-  Joi.object<Tag>({
-    label: Joi.string().required(),
-    permalink: Joi.string().required(),
-  }),
-);
+const FrontMatterAuthorErrorMessage =
+  '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).';
 
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
   description: Joi.string().allow(''),
-  tags: Joi.array().items(BlogTagSchema),
+  tags: FrontMatterTagsSchema,
   draft: Joi.boolean(),
   date: Joi.date().raw(),
 
+  // New multi-authors frontmatter:
+  authors: Joi.alternatives()
+    .try(
+      Joi.string(),
+      BlogPostFrontMatterAuthorSchema,
+      Joi.array()
+        .items(Joi.string(), BlogPostFrontMatterAuthorSchema)
+        .messages({
+          'array.sparse': FrontMatterAuthorErrorMessage,
+          'array.includes': FrontMatterAuthorErrorMessage,
+        }),
+    )
+    .messages({
+      'alternatives.match': FrontMatterAuthorErrorMessage,
+    }),
+  // Legacy author frontmatter
   author: Joi.string(),
   author_title: Joi.string(),
   author_url: URISchema,
   author_image_url: URISchema,
-  slug: Joi.string(),
-  image: URISchema,
-  keywords: Joi.array().items(Joi.string().required()),
-  hide_table_of_contents: Joi.boolean(),
-
-  // TODO re-enable warnings later, our v1 blog posts use those older frontmatter fields
+  // TODO enable deprecation warnings later
   authorURL: URISchema,
   // .warning('deprecate.error', { alternative: '"author_url"'}),
   authorTitle: Joi.string(),
   // .warning('deprecate.error', { alternative: '"author_title"'}),
   authorImageURL: URISchema,
   // .warning('deprecate.error', { alternative: '"author_image_url"'}),
-})
-  .unknown()
-  .messages({
-    'deprecate.error':
-      '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
-  });
+
+  slug: Joi.string(),
+  image: URISchema,
+  keywords: Joi.array().items(Joi.string().required()),
+  hide_table_of_contents: Joi.boolean(),
+
+  ...FrontMatterTOCHeadingLevels,
+}).messages({
+  'deprecate.error':
+    '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
+});
 
 export function validateBlogPostFrontMatter(
   frontMatter: Record<string, unknown>,

package/src/blogUtils.ts

@@ -6,18 +6,16 @@
  */
 
 import fs from 'fs-extra';
-import globby from 'globby';
-import chalk from 'chalk';
 import path from 'path';
 import readingTime from 'reading-time';
-import {Feed} from 'feed';
 import {keyBy, mapValues} from 'lodash';
 import {
   PluginOptions,
   BlogPost,
-  DateLink,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
+  BlogTags,
+  ReadingTimeFunction,
 } from './types';
 import {
   parseMarkdownFile,
@@ -27,9 +25,14 @@ import {
   getFolderContainingFile,
   posixPath,
   replaceMarkdownLinks,
+  Globby,
+  normalizeFrontMatterTags,
+  groupTaggedItems,
 } from '@docusaurus/utils';
 import {LoadContext} from '@docusaurus/types';
 import {validateBlogPostFrontMatter} from './blogFrontMatter';
+import {AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import logger from '@docusaurus/logger';
 
 export function truncate(fileString: string, truncateMarker: RegExp): string {
   return fileString.split(truncateMarker, 1).shift()!;
@@ -44,15 +47,44 @@ export function getSourceToPermalink(
   );
 }
 
-// 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 getBlogTags(blogPosts: BlogPost[]): BlogTags {
+  const groups = groupTaggedItems(
+    blogPosts,
+    (blogPost) => blogPost.metadata.tags,
+  );
+  return mapValues(groups, (group) => ({
+    name: group.tag.label,
+    items: group.items.map((item) => item.id),
+    permalink: group.tag.permalink,
+  }));
+}
 
-function toUrl({date, link}: DateLink) {
-  return `${date
-    .toISOString()
-    .substring(0, '2019-01-01'.length)
-    .replace(/-/g, '/')}/${link}`;
+const DATE_FILENAME_REGEX =
+  /^(?<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 dateString = dateFilenameMatch.groups!.date!;
+    const text = dateFilenameMatch.groups!.text!;
+    // Always treat dates as UTC by adding the `Z`
+    const date = new Date(`${dateString}Z`);
+    const slugDate = dateString.replace(/-/g, '/');
+    const slug = `/${slugDate}/${text}`;
+    return {date, text, slug};
+  } else {
+    const text = blogSourceRelative.replace(/(\/index)?\.mdx?$/, '');
+    const slug = `/${text}`;
+    return {date: undefined, text, slug};
+  }
 }
 
 function formatBlogPostDate(locale: string, date: Date): string {
@@ -68,209 +100,192 @@ function formatBlogPostDate(locale: string, date: Date): string {
   }
 }
 
-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.length) {
-    return null;
-  }
-
-  const {feedOptions, routeBasePath} = options;
-  const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
-  const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, 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: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
-    copyright: feedOptions.copyright,
-  });
-
-  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 result = await parseMarkdownFile(blogSourceAbsolute, {
+    removeContentTitle: true,
   });
-
-  return feed;
+  return {
+    ...result,
+    frontMatter: validateBlogPostFrontMatter(result.frontMatter),
+  };
 }
 
-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);
 
-  async function processBlogSourceFile(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, {removeContentTitle: true});
-    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) {
+      return new Date(frontMatter.date);
+    } else if (parsedBlogFileName.date) {
+      return parsedBlogFileName.date;
     }
+    // Fallback to file create time
+    return (await fs.stat(blogSourceAbsolute)).birthtime;
+  }
 
-    if (frontMatter.id) {
-      console.warn(
-        chalk.yellow(
-          `"id" header option is deprecated in ${blogFileName} file. Please use "slug" option instead.`,
-        ),
-      );
-    }
+  const date = await getDate();
+  const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
 
-    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;
-      // Always treat dates as UTC by adding the `Z`
-      date = new Date(`${dateString}Z`);
-      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 = formatBlogPostDate(i18n.currentLocale, 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: {
+    if (typeof editUrl === 'function') {
+      return editUrl({
+        blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
+        blogPath: posixPath(blogPathRelative),
         permalink,
-        editUrl: getBlogEditUrl(),
-        source: aliasedSource,
-        title,
-        description,
-        date,
-        formattedDate,
-        tags: frontMatter.tags ?? [],
-        readingTime: showReadingTime ? readingTime(content).minutes : undefined,
-        truncated: truncateMarker?.test(content) || false,
-      },
-    });
+        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;
   }
 
-  await Promise.all(
-    blogSourceFiles.map(async (blogSourceFile: string) => {
-      try {
-        return await processBlogSourceFile(blogSourceFile);
-      } catch (e) {
-        console.error(
-          chalk.red(
-            `Processing of blog source file failed for path "${blogSourceFile}"`,
-          ),
-        );
-        throw e;
-      }
-    }),
-  );
+  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,
+      truncated: truncateMarker?.test(content) || false,
+      authors,
+    },
+    content,
+  };
+}
+
+export async function generateBlogPosts(
+  contentPaths: BlogContentPaths,
+  context: LoadContext,
+  options: PluginOptions,
+): Promise<BlogPost[]> {
+  const {include, exclude} = options;
+
+  if (!fs.existsSync(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 (e) {
+          logger.error`Processing of blog source file failed for path path=${blogSourceFile}.`;
+          throw e;
+        }
+      }),
+    )
+  ).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;
 }