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

package/lib/types.d.ts

@@ -4,11 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { RemarkAndRehypePluginOptions } from '@docusaurus/mdx-loader';
 import type { Tag } from '@docusaurus/utils';
 import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
-import { Overwrite } from 'utility-types';
-import { BlogPostFrontMatter } from './blogFrontMatter';
+import type { BlogPostFrontMatter, Author } from '@docusaurus/plugin-content-blog';
 export declare type BlogContentPaths = ContentPaths;
 export interface BlogContent {
     blogSidebarTitle: string;
@@ -17,71 +15,6 @@ export interface BlogContent {
     blogTags: BlogTags;
     blogTagsListPath: string | null;
 }
-export declare type FeedType = 'rss' | 'atom' | 'json';
-export declare type FeedOptions = {
-    type?: FeedType[] | null;
-    title?: string;
-    description?: string;
-    copyright: string;
-    language?: string;
-};
-export declare type UserFeedOptions = Overwrite<Partial<FeedOptions>, {
-    type?: FeedOptions['type'] | 'all';
-}>;
-export declare type EditUrlFunction = (editUrlParams: {
-    blogDirPath: string;
-    blogPath: string;
-    permalink: string;
-    locale: string;
-}) => string | undefined;
-declare type ReadingTimeOptions = {
-    wordsPerMinute?: number;
-    wordBound?: (char: string) => boolean;
-};
-export declare type ReadingTimeFunction = (params: {
-    content: string;
-    frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
-    options?: ReadingTimeOptions;
-}) => number;
-export declare type ReadingTimeFunctionOption = (params: Required<Omit<Parameters<ReadingTimeFunction>[0], 'options'>> & {
-    defaultReadingTime: ReadingTimeFunction;
-}) => number | undefined;
-export declare type PluginOptions = RemarkAndRehypePluginOptions & {
-    id?: string;
-    path: string;
-    routeBasePath: string;
-    tagsBasePath: string;
-    archiveBasePath: string;
-    include: string[];
-    exclude: string[];
-    postsPerPage: number | 'ALL';
-    blogListComponent: string;
-    blogPostComponent: string;
-    blogTagsListComponent: string;
-    blogTagsPostsComponent: string;
-    blogTitle: string;
-    blogDescription: string;
-    blogSidebarCount: number | 'ALL';
-    blogSidebarTitle: string;
-    truncateMarker: RegExp;
-    showReadingTime: boolean;
-    feedOptions: {
-        type?: FeedType[] | null;
-        title?: string;
-        description?: string;
-        copyright: string;
-        language?: string;
-    };
-    editUrl?: string | EditUrlFunction;
-    editLocalizedFiles?: boolean;
-    admonitions: Record<string, unknown>;
-    authorsMapPath: string;
-    readingTime: ReadingTimeFunctionOption;
-    sortPosts: 'ascending' | 'descending';
-};
-export declare type UserPluginOptions = Overwrite<Partial<PluginOptions>, {
-    feedOptions?: UserFeedOptions;
-}>;
 export interface BlogTags {
     [key: string]: BlogTag;
 }
@@ -110,12 +43,6 @@ export interface BlogPaginated {
     metadata: BlogPaginatedMetadata;
     items: string[];
 }
-export interface Author extends Record<string, unknown> {
-    name?: string;
-    imageURL?: string;
-    url?: string;
-    title?: string;
-}
 export interface MetaData {
     permalink: string;
     source: string;
@@ -130,10 +57,7 @@ export interface MetaData {
     truncated: boolean;
     editUrl?: string;
     authors: Author[];
-}
-export interface Assets {
-    image?: string;
-    authorsImageUrls: (string | undefined)[];
+    frontMatter: BlogPostFrontMatter & Record<string, unknown>;
 }
 export interface Paginator {
     title: string;
@@ -160,4 +84,3 @@ export declare type BlogMarkdownLoaderOptions = {
     sourceToPermalink: Record<string, string>;
     onBrokenMarkdownLink: (brokenMarkdownLink: BlogBrokenMarkdownLink) => void;
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.15",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -18,17 +18,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.14",
-    "@docusaurus/logger": "2.0.0-beta.14",
-    "@docusaurus/mdx-loader": "2.0.0-beta.14",
-    "@docusaurus/utils": "2.0.0-beta.14",
-    "@docusaurus/utils-validation": "2.0.0-beta.14",
-    "escape-string-regexp": "^4.0.0",
+    "@docusaurus/core": "2.0.0-beta.15",
+    "@docusaurus/logger": "2.0.0-beta.15",
+    "@docusaurus/mdx-loader": "2.0.0-beta.15",
+    "@docusaurus/utils": "2.0.0-beta.15",
+    "@docusaurus/utils-common": "2.0.0-beta.15",
+    "@docusaurus/utils-validation": "2.0.0-beta.15",
+    "cheerio": "^1.0.0-rc.10",
     "feed": "^4.2.2",
     "fs-extra": "^10.0.0",
-    "globby": "^11.0.2",
-    "js-yaml": "^4.0.0",
-    "loader-utils": "^2.0.0",
     "lodash": "^4.17.20",
     "reading-time": "^1.5.0",
     "remark-admonitions": "^1.2.1",
@@ -37,7 +35,8 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.14"
+    "@docusaurus/types": "2.0.0-beta.15",
+    "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
@@ -46,5 +45,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "c4824a8937d8f1aa0806667749cbc74058e2b294"
+  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
 }

package/src/authors.ts

@@ -5,92 +5,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import fs from 'fs-extra';
-import logger from '@docusaurus/logger';
-import path from 'path';
-import {Author, BlogContentPaths} from './types';
-import {findFolderContainingFile} from '@docusaurus/utils';
+import type {BlogContentPaths} from './types';
+import {getDataFileData} from '@docusaurus/utils';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
-import {
+import type {
+  Author,
   BlogPostFrontMatter,
   BlogPostFrontMatterAuthor,
   BlogPostFrontMatterAuthors,
-} from './blogFrontMatter';
-import {getContentPathList} from './blogUtils';
-import Yaml from 'js-yaml';
+} from '@docusaurus/plugin-content-blog';
 
 export type AuthorsMap = Record<string, Author>;
 
 const AuthorsMapSchema = Joi.object<AuthorsMap>().pattern(
   Joi.string(),
   Joi.object({
-    name: Joi.string().required(),
+    name: Joi.string(),
     url: URISchema,
     imageURL: URISchema,
     title: Joi.string(),
   })
     .rename('image_url', 'imageURL')
+    .or('name', 'imageURL')
     .unknown()
     .required(),
 );
 
-export function validateAuthorsMapFile(content: unknown): AuthorsMap {
+export function validateAuthorsMap(content: unknown): AuthorsMap {
   return Joi.attempt(content, AuthorsMapSchema);
 }
 
-export async function readAuthorsMapFile(
-  filePath: string,
-): Promise<AuthorsMap | undefined> {
-  if (await fs.pathExists(filePath)) {
-    const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
-    try {
-      const unsafeContent = Yaml.load(contentString);
-      return validateAuthorsMapFile(unsafeContent);
-    } catch (e) {
-      // TODO replace later by error cause: see https://v8.dev/features/error-cause
-      logger.error('The author list file looks invalid!');
-      throw e;
-    }
-  }
-  return undefined;
-}
-
-type AuthorsMapParams = {
+export async function getAuthorsMap(params: {
   authorsMapPath: string;
   contentPaths: BlogContentPaths;
-};
-
-export async function getAuthorsMapFilePath({
-  authorsMapPath,
-  contentPaths,
-}: AuthorsMapParams): Promise<string | undefined> {
-  // Useful to load an eventually localize authors map
-  const contentPath = await findFolderContainingFile(
-    getContentPathList(contentPaths),
-    authorsMapPath,
+}): Promise<AuthorsMap | undefined> {
+  return getDataFileData(
+    {
+      filePath: params.authorsMapPath,
+      contentPaths: params.contentPaths,
+      fileType: 'authors map',
+    },
+    validateAuthorsMap,
   );
-
-  if (contentPath) {
-    return path.join(contentPath, authorsMapPath);
-  }
-
-  return undefined;
-}
-
-export async function getAuthorsMap(
-  params: AuthorsMapParams,
-): Promise<AuthorsMap | undefined> {
-  const filePath = await getAuthorsMapFilePath(params);
-  if (!filePath) {
-    return undefined;
-  }
-  try {
-    return await readAuthorsMapFile(filePath);
-  } catch (e) {
-    // TODO replace later by error cause, see https://v8.dev/features/error-cause
-    logger.error`Couldn't read blog authors map at path=${filePath}`;
-    throw e;
-  }
 }
 
 type AuthorsParam = {
@@ -98,7 +54,7 @@ type AuthorsParam = {
   authorsMap: AuthorsMap | undefined;
 };
 
-// Legacy v1/early-v2 frontmatter fields
+// Legacy v1/early-v2 front matter fields
 // We may want to deprecate those in favor of using only frontMatter.authors
 function getFrontMatterAuthorLegacy(
   frontMatter: BlogPostFrontMatter,
@@ -108,7 +64,6 @@ function getFrontMatterAuthorLegacy(
   const url = frontMatter.author_url ?? frontMatter.authorURL;
   const imageURL = frontMatter.author_image_url ?? frontMatter.authorImageURL;
 
-  // Shouldn't we require at least an author name?
   if (name || title || url || imageURL) {
     return {
       name,
@@ -168,7 +123,7 @@ ${Object.keys(authorsMap)
 
   function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
     return {
-      // Author def from authorsMap can be locally overridden by frontmatter
+      // Author def from authorsMap can be locally overridden by front matter
       ...getAuthorsMapAuthor(frontMatterAuthor.key),
       ...frontMatterAuthor,
     };
@@ -182,11 +137,11 @@ export function getBlogPostAuthors(params: AuthorsParam): Author[] {
   const authors = getFrontMatterAuthors(params);
 
   if (authorLegacy) {
-    // Technically, we could allow mixing legacy/authors frontmatter, but do we really want to?
+    // Technically, we could allow mixing legacy/authors front matter, but do we really want to?
     if (authors.length > 0) {
       throw new Error(
-        `To declare blog post authors, use the 'authors' FrontMatter in priority.
-Don't mix 'authors' with other existing 'author_*' FrontMatter. Choose one or the other, not both at the same time.`,
+        `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.`,
       );
     }
     return [authorLegacy];

package/src/blogFrontMatter.ts

@@ -6,27 +6,13 @@
  */
 
 import {
-  JoiFrontMatter as Joi, // Custom instance for frontmatter
+  JoiFrontMatter as Joi, // Custom instance for front matter
   URISchema,
   validateFrontMatter,
   FrontMatterTagsSchema,
   FrontMatterTOCHeadingLevels,
 } from '@docusaurus/utils-validation';
-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)[];
+import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
 const BlogPostFrontMatterAuthorSchema = Joi.object({
   key: Joi.string(),
@@ -35,40 +21,9 @@ const BlogPostFrontMatterAuthorSchema = Joi.object({
   url: URISchema,
   imageURL: Joi.string(),
 })
-  .or('key', 'name')
+  .or('key', 'name', 'imageURL')
   .rename('image_url', 'imageURL', {alias: true});
 
-export type BlogPostFrontMatter = {
-  id?: string;
-  title?: string;
-  description?: string;
-  tags?: FrontMatterTag[];
-  slug?: string;
-  draft?: boolean;
-  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;
-
-  /** @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;
-};
-
 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).';
 
@@ -80,7 +35,7 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   draft: Joi.boolean(),
   date: Joi.date().raw(),
 
-  // New multi-authors frontmatter:
+  // New multi-authors front matter:
   authors: Joi.alternatives()
     .try(
       Joi.string(),
@@ -95,7 +50,7 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
     .messages({
       'alternatives.match': FrontMatterAuthorErrorMessage,
     }),
-  // Legacy author frontmatter
+  // Legacy author front matter
   author: Joi.string(),
   author_title: Joi.string(),
   author_url: URISchema,

package/src/blogUtils.ts

@@ -9,16 +9,14 @@ import fs from 'fs-extra';
 import path from 'path';
 import readingTime from 'reading-time';
 import {keyBy, mapValues} from 'lodash';
-import {
-  PluginOptions,
+import type {
   BlogPost,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   BlogTags,
-  ReadingTimeFunction,
 } from './types';
 import {
-  parseMarkdownFile,
+  parseMarkdownString,
   normalizeUrl,
   aliasedSitePath,
   getEditUrl,
@@ -28,11 +26,16 @@ import {
   Globby,
   normalizeFrontMatterTags,
   groupTaggedItems,
+  getContentPathList,
 } from '@docusaurus/utils';
-import {LoadContext} from '@docusaurus/types';
+import type {LoadContext} from '@docusaurus/types';
 import {validateBlogPostFrontMatter} from './blogFrontMatter';
-import {AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
 import logger from '@docusaurus/logger';
+import type {
+  PluginOptions,
+  ReadingTimeFunction,
+} from '@docusaurus/plugin-content-blog';
 
 export function truncate(fileString: string, truncateMarker: RegExp): string {
   return fileString.split(truncateMarker, 1).shift()!;
@@ -60,7 +63,7 @@ export function getBlogTags(blogPosts: BlogPost[]): BlogTags {
 }
 
 const DATE_FILENAME_REGEX =
-  /^(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
+  /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
 
 type ParsedBlogFileName = {
   date: Date | undefined;
@@ -73,12 +76,11 @@ export function parseBlogFileName(
 ): ParsedBlogFileName {
   const dateFilenameMatch = blogSourceRelative.match(DATE_FILENAME_REGEX);
   if (dateFilenameMatch) {
-    const dateString = dateFilenameMatch.groups!.date!;
-    const text = dateFilenameMatch.groups!.text!;
+    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}/${text}`;
+    const slug = `/${slugDate}/${folder}${text}`;
     return {date, text, slug};
   } else {
     const text = blogSourceRelative.replace(/(\/index)?\.mdx?$/, '');
@@ -101,13 +103,22 @@ function formatBlogPostDate(locale: string, date: Date): string {
 }
 
 async function parseBlogPostMarkdownFile(blogSourceAbsolute: string) {
-  const result = await parseMarkdownFile(blogSourceAbsolute, {
-    removeContentTitle: true,
-  });
-  return {
-    ...result,
-    frontMatter: validateBlogPostFrontMatter(result.frontMatter),
-  };
+  const markdownString = await fs.readFile(blogSourceAbsolute, 'utf-8');
+  try {
+    const result = parseMarkdownString(markdownString, {
+      removeContentTitle: true,
+    });
+    return {
+      ...result,
+      frontMatter: validateBlogPostFrontMatter(result.frontMatter),
+    };
+  } catch (e) {
+    throw new Error(
+      `Error while parsing blog post file ${blogSourceAbsolute}: "${
+        (e as Error).message
+      }".`,
+    );
+  }
 }
 
 const defaultReadingTime: ReadingTimeFunction = ({content, options}) =>
@@ -159,7 +170,12 @@ async function processBlogSourceFile(
   async function getDate(): Promise<Date> {
     // Prefer user-defined date.
     if (frontMatter.date) {
-      return new Date(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;
     }
@@ -234,6 +250,7 @@ async function processBlogSourceFile(
         : undefined,
       truncated: truncateMarker?.test(content) || false,
       authors,
+      frontMatter,
     },
     content,
   };
@@ -317,8 +334,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];
-}

package/src/feed.ts

@@ -5,34 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Feed, Author as FeedAuthor, Item as FeedItem} from 'feed';
-import {PluginOptions, Author, BlogPost, FeedType} from './types';
-import {normalizeUrl, mdxToHtml} from '@docusaurus/utils';
-import {DocusaurusConfig} from '@docusaurus/types';
+import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed';
+import type {BlogPost} from './types';
+import {
+  normalizeUrl,
+  posixPath,
+  mapAsyncSequential,
+  readOutputHTMLFile,
+} from '@docusaurus/utils';
+import cheerio from 'cheerio';
+import type {DocusaurusConfig} from '@docusaurus/types';
 import path from 'path';
 import fs from 'fs-extra';
-
-// TODO this is temporary until we handle mdxToHtml better
-// It's hard to convert reliably JSX/require calls  to an html feed content
-// See https://github.com/facebook/docusaurus/issues/5664
-function mdxToFeedContent(mdxContent: string): string | undefined {
-  try {
-    return mdxToHtml(mdxContent);
-  } catch (e) {
-    // TODO will we need a plugin option to configure how to handle such an error
-    // Swallow the error on purpose for now, until we understand better the problem space
-    return undefined;
-  }
-}
-
-export async function generateBlogFeed({
+import type {
+  FeedType,
+  PluginOptions,
+  Author,
+} from '@docusaurus/plugin-content-blog';
+import {blogPostContainerID} from '@docusaurus/utils-common';
+
+async function generateBlogFeed({
   blogPosts,
   options,
   siteConfig,
+  outDir,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
+  outDir: string;
 }): Promise<Feed | null> {
   if (!blogPosts.length) {
     return null;
@@ -42,9 +43,7 @@ export async function generateBlogFeed({
   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'); // weird legacy magic date
+  const updated = blogPosts[0] && blogPosts[0].metadata.date;
 
   const feed = new Feed({
     id: blogBaseUrl,
@@ -63,19 +62,35 @@ export async function generateBlogFeed({
     return {name: author.name, link: author.url};
   }
 
-  blogPosts.forEach((post) => {
+  await mapAsyncSequential(blogPosts, async (post) => {
     const {
       id,
-      metadata: {title: metadataTitle, permalink, date, description, authors},
+      metadata: {
+        title: metadataTitle,
+        permalink,
+        date,
+        description,
+        authors,
+        tags,
+      },
     } = post;
 
+    const content = await readOutputHTMLFile(
+      permalink.replace(siteConfig.baseUrl, ''),
+      outDir,
+      siteConfig.trailingSlash,
+    );
+    const $ = cheerio.load(content);
+
     const feedItem: FeedItem = {
       title: metadataTitle,
       id,
       link: normalizeUrl([siteUrl, permalink]),
       date,
       description,
-      content: mdxToFeedContent(post.content),
+      // Atom feed demands the "term", while other feeds use "name"
+      category: tags.map((tag) => ({name: tag.label, term: tag.label})),
+      content: $(`#${blogPostContainerID}`).html()!,
     };
 
     // json1() method takes the first item of authors array
@@ -113,7 +128,10 @@ async function createBlogFeedFile({
     }
   })();
   try {
-    await fs.outputFile(path.join(generatePath, feedPath), feedContent);
+    await fs.outputFile(
+      posixPath(path.join(generatePath, feedPath)),
+      feedContent,
+    );
   } catch (err) {
     throw new Error(`Generating ${feedType} feed failed: ${err}.`);
   }
@@ -130,7 +148,12 @@ export async function createBlogFeedFiles({
   siteConfig: DocusaurusConfig;
   outDir: string;
 }): Promise<void> {
-  const feed = await generateBlogFeed({blogPosts, options, siteConfig});
+  const feed = await generateBlogFeed({
+    blogPosts,
+    options,
+    siteConfig,
+    outDir,
+  });
 
   const feedTypes = options.feedOptions.type;
   if (!feed || !feedTypes) {