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

package/lib/pluginOptionSchema.js

@@ -8,8 +8,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginOptionSchema = exports.DEFAULT_OPTIONS = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const utils_1 = require("@docusaurus/utils");
 exports.DEFAULT_OPTIONS = {
-    feedOptions: { type: ['rss', 'atom'] },
+    feedOptions: { type: ['rss', 'atom'], copyright: '' },
     beforeDefaultRehypePlugins: [],
     beforeDefaultRemarkPlugins: [],
     admonitions: {},
@@ -26,21 +27,29 @@ exports.DEFAULT_OPTIONS = {
     blogSidebarCount: 5,
     blogSidebarTitle: 'Recent posts',
     postsPerPage: 10,
-    include: ['*.md', '*.mdx'],
+    include: ['**/*.{md,mdx}'],
+    exclude: utils_1.GlobExcludeDefault,
     routeBasePath: 'blog',
+    tagsBasePath: 'tags',
+    archiveBasePath: 'archive',
     path: 'blog',
     editLocalizedFiles: false,
+    authorsMapPath: 'authors.yml',
+    readingTime: ({ content, defaultReadingTime }) => defaultReadingTime({ content }),
+    sortPosts: 'descending',
 };
 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),
     routeBasePath: utils_validation_1.Joi.string()
         // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
         // .allow('')
         .default(exports.DEFAULT_OPTIONS.routeBasePath),
+    tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
     include: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.include),
-    postsPerPage: utils_validation_1.Joi.number()
-        .integer()
-        .min(1)
+    exclude: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.exclude),
+    postsPerPage: utils_validation_1.Joi.alternatives()
+        .try(utils_validation_1.Joi.equal('ALL').required(), utils_validation_1.Joi.number().integer().min(1).required())
         .default(exports.DEFAULT_OPTIONS.postsPerPage),
     blogListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogListComponent),
     blogPostComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogPostComponent),
@@ -51,7 +60,7 @@ exports.PluginOptionSchema = utils_validation_1.Joi.object({
         .allow('')
         .default(exports.DEFAULT_OPTIONS.blogDescription),
     blogSidebarCount: utils_validation_1.Joi.alternatives()
-        .try(utils_validation_1.Joi.equal('ALL').required(), utils_validation_1.Joi.number().required())
+        .try(utils_validation_1.Joi.equal('ALL').required(), utils_validation_1.Joi.number().integer().min(0).required())
         .default(exports.DEFAULT_OPTIONS.blogSidebarCount),
     blogSidebarTitle: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogSidebarTitle),
     showReadingTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showReadingTime),
@@ -65,14 +74,26 @@ 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),
         title: utils_validation_1.Joi.string().allow(''),
         description: utils_validation_1.Joi.string().allow(''),
-        copyright: utils_validation_1.Joi.string(),
+        // only add default value when user actually wants a feed (type is not null)
+        copyright: utils_validation_1.Joi.when('type', {
+            is: utils_validation_1.Joi.any().valid(null),
+            then: utils_validation_1.Joi.string().optional(),
+            otherwise: utils_validation_1.Joi.string()
+                .allow('')
+                .default(exports.DEFAULT_OPTIONS.feedOptions.copyright),
+        }),
         language: utils_validation_1.Joi.string(),
     }).default(exports.DEFAULT_OPTIONS.feedOptions),
+    authorsMapPath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.authorsMapPath),
+    readingTime: utils_validation_1.Joi.function().default(() => exports.DEFAULT_OPTIONS.readingTime),
+    sortPosts: utils_validation_1.Joi.string()
+        .valid('descending', 'ascending')
+        .default(exports.DEFAULT_OPTIONS.sortPosts),
 });

package/lib/translations.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 type { BlogContent, PluginOptions } from './types';
+import type { TranslationFiles } from '@docusaurus/types';
+export declare function getTranslationFiles(options: PluginOptions): TranslationFiles;
+export declare function translateContent(content: BlogContent, translationFiles: TranslationFiles): BlogContent;

package/lib/translations.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateContent = exports.getTranslationFiles = void 0;
+function translateListPage(blogListPaginated, translations) {
+    return blogListPaginated.map((page) => {
+        const { items, metadata } = page;
+        return {
+            items,
+            metadata: {
+                ...metadata,
+                blogTitle: translations.title.message,
+                blogDescription: translations.description.message,
+            },
+        };
+    });
+}
+function getTranslationFiles(options) {
+    return [
+        {
+            path: 'options',
+            content: {
+                title: {
+                    message: options.blogTitle,
+                    description: 'The title for the blog used in SEO',
+                },
+                description: {
+                    message: options.blogDescription,
+                    description: 'The description for the blog used in SEO',
+                },
+                'sidebar.title': {
+                    message: options.blogSidebarTitle,
+                    description: 'The label for the left sidebar',
+                },
+            },
+        },
+    ];
+}
+exports.getTranslationFiles = getTranslationFiles;
+function translateContent(content, translationFiles) {
+    const [{ content: optonsTranslations }] = translationFiles;
+    return {
+        ...content,
+        blogSidebarTitle: optonsTranslations['sidebar.title'].message,
+        blogListPaginated: translateListPage(content.blogListPaginated, optonsTranslations),
+    };
+}
+exports.translateContent = translateContent;

package/lib/types.d.ts

@@ -5,31 +5,56 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { RemarkAndRehypePluginOptions } from '@docusaurus/mdx-loader';
-import { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import type { Tag } from '@docusaurus/utils';
+import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import { Overwrite } from 'utility-types';
+import { BlogPostFrontMatter } from './blogFrontMatter';
 export declare type BlogContentPaths = ContentPaths;
 export interface BlogContent {
+    blogSidebarTitle: string;
     blogPosts: BlogPost[];
     blogListPaginated: BlogPaginated[];
     blogTags: BlogTags;
     blogTagsListPath: string | null;
 }
-export interface DateLink {
-    date: Date;
-    link: string;
-}
-export declare type FeedType = 'rss' | 'atom';
+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;
-export interface PluginOptions extends RemarkAndRehypePluginOptions {
+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[];
-    postsPerPage: number;
+    exclude: string[];
+    postsPerPage: number | 'ALL';
     blogListComponent: string;
     blogPostComponent: string;
     blogTagsListComponent: string;
@@ -41,7 +66,7 @@ export interface PluginOptions extends RemarkAndRehypePluginOptions {
     truncateMarker: RegExp;
     showReadingTime: boolean;
     feedOptions: {
-        type?: [FeedType] | null;
+        type?: FeedType[] | null;
         title?: string;
         description?: string;
         copyright: string;
@@ -50,7 +75,13 @@ export interface PluginOptions extends RemarkAndRehypePluginOptions {
     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;
 }
@@ -62,6 +93,7 @@ export interface BlogTag {
 export interface BlogPost {
     id: string;
     metadata: MetaData;
+    content: string;
 }
 export interface BlogPaginatedMetadata {
     permalink: string;
@@ -78,28 +110,35 @@ 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;
     description: string;
     date: Date;
     formattedDate: string;
-    tags: (Tag | string)[];
+    tags: Tag[];
     title: string;
     readingTime?: number;
     prevItem?: Paginator;
     nextItem?: Paginator;
     truncated: boolean;
     editUrl?: string;
+    authors: Author[];
+}
+export interface Assets {
+    image?: string;
+    authorsImageUrls: (string | undefined)[];
 }
 export interface Paginator {
     title: string;
     permalink: string;
 }
-export interface Tag {
-    label: string;
-    permalink: string;
-}
 export interface BlogItemsToMetadata {
     [key: string]: MetaData;
 }
@@ -121,3 +160,4 @@ export declare type BlogMarkdownLoaderOptions = {
     sourceToPermalink: Record<string, string>;
     onBrokenMarkdownLink: (brokenMarkdownLink: BlogBrokenMarkdownLink) => void;
 };
+export {};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.138b4c997",
+  "version": "2.0.0-beta.14",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
-  "types": "index.d.ts",
+  "types": "src/plugin-content-blog.d.ts",
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch"
@@ -18,29 +18,33 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.138b4c997",
-    "@docusaurus/mdx-loader": "2.0.0-beta.138b4c997",
-    "@docusaurus/types": "2.0.0-beta.138b4c997",
-    "@docusaurus/utils": "2.0.0-beta.138b4c997",
-    "@docusaurus/utils-validation": "2.0.0-beta.138b4c997",
-    "chalk": "^4.1.1",
+    "@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",
     "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.3.0",
+    "reading-time": "^1.5.0",
     "remark-admonitions": "^1.2.1",
-    "tslib": "^2.2.0",
-    "webpack": "^5.40.0"
+    "tslib": "^2.3.1",
+    "utility-types": "^3.10.0",
+    "webpack": "^5.61.0"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "2.0.0-beta.14"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "8cc620648710971acc459aabd2c6f505ef757701"
+  "gitHead": "c4824a8937d8f1aa0806667749cbc74058e2b294"
 }

package/src/authors.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 fs from 'fs-extra';
+import logger from '@docusaurus/logger';
+import path from 'path';
+import {Author, BlogContentPaths} from './types';
+import {findFolderContainingFile} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import {
+  BlogPostFrontMatter,
+  BlogPostFrontMatterAuthor,
+  BlogPostFrontMatterAuthors,
+} from './blogFrontMatter';
+import {getContentPathList} from './blogUtils';
+import Yaml from 'js-yaml';
+
+export type AuthorsMap = Record<string, Author>;
+
+const AuthorsMapSchema = Joi.object<AuthorsMap>().pattern(
+  Joi.string(),
+  Joi.object({
+    name: Joi.string().required(),
+    url: URISchema,
+    imageURL: URISchema,
+    title: Joi.string(),
+  })
+    .rename('image_url', 'imageURL')
+    .unknown()
+    .required(),
+);
+
+export function validateAuthorsMapFile(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 = {
+  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,
+  );
+
+  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 = {
+  frontMatter: BlogPostFrontMatter;
+  authorsMap: AuthorsMap | undefined;
+};
+
+// Legacy v1/early-v2 frontmatter fields
+// We may want to deprecate those in favor of using only frontMatter.authors
+function getFrontMatterAuthorLegacy(
+  frontMatter: BlogPostFrontMatter,
+): BlogPostFrontMatterAuthor | undefined {
+  const name = frontMatter.author;
+  const title = frontMatter.author_title ?? frontMatter.authorTitle;
+  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,
+      title,
+      url,
+      imageURL,
+    };
+  }
+
+  return undefined;
+}
+
+function normalizeFrontMatterAuthors(
+  frontMatterAuthors: BlogPostFrontMatterAuthors = [],
+): BlogPostFrontMatterAuthor[] {
+  function normalizeAuthor(
+    authorInput: string | BlogPostFrontMatterAuthor,
+  ): BlogPostFrontMatterAuthor {
+    if (typeof authorInput === 'string') {
+      // Technically, we could allow users to provide an author's name here
+      // IMHO it's better to only support keys here
+      // Reason: a typo in a key would fallback to becoming a name and may end-up un-noticed
+      return {key: authorInput};
+    }
+    return authorInput;
+  }
+
+  return Array.isArray(frontMatterAuthors)
+    ? frontMatterAuthors.map(normalizeAuthor)
+    : [normalizeAuthor(frontMatterAuthors)];
+}
+
+function getFrontMatterAuthors(params: AuthorsParam): Author[] {
+  const {authorsMap} = params;
+  const frontMatterAuthors = normalizeFrontMatterAuthors(
+    params.frontMatter.authors,
+  );
+
+  function getAuthorsMapAuthor(key: string | undefined): Author | undefined {
+    if (key) {
+      if (!authorsMap || Object.keys(authorsMap).length === 0) {
+        throw new Error(`Can't reference blog post authors by a key (such as '${key}') because no authors map file could be loaded.
+Please double-check your blog plugin config (in particular 'authorsMapPath'), ensure the file exists at the configured path, is not empty, and is valid!`);
+      }
+      const author = authorsMap[key];
+      if (!author) {
+        throw Error(`Blog author with key "${key}" not found in the authors map file.
+Valid author keys are:
+${Object.keys(authorsMap)
+  .map((validKey) => `- ${validKey}`)
+  .join('\n')}`);
+      }
+      return author;
+    }
+    return undefined;
+  }
+
+  function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
+    return {
+      // Author def from authorsMap can be locally overridden by frontmatter
+      ...getAuthorsMapAuthor(frontMatterAuthor.key),
+      ...frontMatterAuthor,
+    };
+  }
+
+  return frontMatterAuthors.map(toAuthor);
+}
+
+export function getBlogPostAuthors(params: AuthorsParam): Author[] {
+  const authorLegacy = getFrontMatterAuthorLegacy(params.frontMatter);
+  const authors = getFrontMatterAuthors(params);
+
+  if (authorLegacy) {
+    // Technically, we could allow mixing legacy/authors frontmatter, 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.`,
+      );
+    }
+    return [authorLegacy];
+  }
+
+  return authors;
+}