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

package/lib/pluginOptionSchema.js

@@ -40,7 +40,9 @@ exports.DEFAULT_OPTIONS = {
 };
 exports.PluginOptionSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
-    archiveBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.archiveBasePath),
+    archiveBasePath: utils_validation_1.Joi.string()
+        .default(exports.DEFAULT_OPTIONS.archiveBasePath)
+        .allow(null),
     routeBasePath: utils_validation_1.Joi.string()
         // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
         // .allow('')
@@ -74,8 +76,8 @@ exports.PluginOptionSchema = utils_validation_1.Joi.object({
     beforeDefaultRehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRehypePlugins),
     feedOptions: utils_validation_1.Joi.object({
         type: utils_validation_1.Joi.alternatives()
-            .try(utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()), utils_validation_1.Joi.alternatives().conditional(utils_validation_1.Joi.string().equal('all', 'rss', 'atom'), {
-            then: utils_validation_1.Joi.custom((val) => val === 'all' ? ['rss', 'atom'] : [val]),
+            .try(utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().equal('rss', 'atom', 'json')), utils_validation_1.Joi.alternatives().conditional(utils_validation_1.Joi.string().equal('all', 'rss', 'atom', 'json'), {
+            then: utils_validation_1.Joi.custom((val) => val === 'all' ? ['rss', 'atom', 'json'] : [val]),
         }))
             .allow(null)
             .default(exports.DEFAULT_OPTIONS.feedOptions.type),

package/lib/translations.d.ts

@@ -4,7 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { BlogContent, PluginOptions } from './types';
+import type { BlogContent } from './types';
 import type { TranslationFiles } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/plugin-content-blog';
 export declare function getTranslationFiles(options: PluginOptions): TranslationFiles;
 export declare function translateContent(content: BlogContent, translationFiles: TranslationFiles): BlogContent;

package/lib/translations.js

@@ -43,11 +43,11 @@ function getTranslationFiles(options) {
 }
 exports.getTranslationFiles = getTranslationFiles;
 function translateContent(content, translationFiles) {
-    const [{ content: optonsTranslations }] = translationFiles;
+    const [{ content: optionsTranslations }] = translationFiles;
     return {
         ...content,
-        blogSidebarTitle: optonsTranslations['sidebar.title'].message,
-        blogListPaginated: translateListPage(content.blogListPaginated, optonsTranslations),
+        blogSidebarTitle: optionsTranslations['sidebar.title'].message,
+        blogListPaginated: translateListPage(content.blogListPaginated, optionsTranslations),
     };
 }
 exports.translateContent = translateContent;

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';
-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.13",
+  "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.13",
-    "@docusaurus/mdx-loader": "2.0.0-beta.13",
-    "@docusaurus/utils": "2.0.0-beta.13",
-    "@docusaurus/utils-validation": "2.0.0-beta.13",
-    "chalk": "^4.1.2",
-    "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.13"
+    "@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": "b6ca12aedf10a10c2375f4f8b7e7380cfd7c7202"
+  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
 }

package/src/authors.ts

@@ -5,94 +5,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import fs from 'fs-extra';
-import chalk from 'chalk';
-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
-      console.error(chalk.red('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
-    console.error(
-      chalk.red(`Couldn't read blog authors map at path ${filePath}`),
-    );
-    throw e;
-  }
 }
 
 type AuthorsParam = {
@@ -100,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,
@@ -110,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,
@@ -170,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,
     };
@@ -184,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

@@ -6,20 +6,17 @@
  */
 
 import fs from 'fs-extra';
-import chalk from 'chalk';
 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,
@@ -29,10 +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}) =>
@@ -151,11 +162,7 @@ async function processBlogSourceFile(
   }
 
   if (frontMatter.id) {
-    console.warn(
-      chalk.yellow(
-        `"id" header option is deprecated in ${blogSourceRelative} file. Please use "slug" option instead.`,
-      ),
-    );
+    logger.warn`name=${'id'} header option is deprecated in path=${blogSourceRelative} file. Please use name=${'slug'} option instead.`;
   }
 
   const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
@@ -163,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;
     }
@@ -238,6 +250,7 @@ async function processBlogSourceFile(
         : undefined,
       truncated: truncateMarker?.test(content) || false,
       authors,
+      frontMatter,
     },
     content,
   };
@@ -276,11 +289,7 @@ export async function generateBlogPosts(
             authorsMap,
           );
         } catch (e) {
-          console.error(
-            chalk.red(
-              `Processing of blog source file failed for path "${blogSourceFile}"`,
-            ),
-          );
+          logger.error`Processing of blog source file failed for path path=${blogSourceFile}.`;
           throw e;
         }
       }),
@@ -325,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];
-}