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

package/lib/pluginOptionSchema.js

@@ -8,12 +8,13 @@
 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: {},
-    truncateMarker: /<!--\s*(truncate)\s*-->/,
+    truncateMarker: /<!--\s*truncate\s*-->/,
     rehypePlugins: [],
     remarkPlugins: [],
     showReadingTime: true,
@@ -21,37 +22,49 @@ exports.DEFAULT_OPTIONS = {
     blogTagsListComponent: '@theme/BlogTagsListPage',
     blogPostComponent: '@theme/BlogPostPage',
     blogListComponent: '@theme/BlogListPage',
+    blogArchiveComponent: '@theme/BlogArchivePage',
     blogDescription: 'Blog',
     blogTitle: 'Blog',
     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)
+        .allow(null),
     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),
     blogTagsListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogTagsListComponent),
     blogTagsPostsComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogTagsPostsComponent),
+    blogArchiveComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.blogArchiveComponent),
     blogTitle: utils_validation_1.Joi.string().allow('').default(exports.DEFAULT_OPTIONS.blogTitle),
     blogDescription: utils_validation_1.Joi.string()
         .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 +78,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,11 @@
+/**
+ * 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 } 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

@@ -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: optionsTranslations }] = translationFiles;
+    return {
+        ...content,
+        blogSidebarTitle: optionsTranslations['sidebar.title'].message,
+        blogListPaginated: translateListPage(content.blogListPaginated, optionsTranslations),
+    };
+}
+exports.translateContent = translateContent;

package/lib/types.d.ts

@@ -4,64 +4,30 @@
  * 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 { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import type { Tag } from '@docusaurus/utils';
+import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import type { BlogPostFrontMatter, Author } from '@docusaurus/plugin-content-blog';
 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 EditUrlFunction = (editUrlParams: {
-    blogDirPath: string;
-    blogPath: string;
-    permalink: string;
-    locale: string;
-}) => string | undefined;
-export interface PluginOptions extends RemarkAndRehypePluginOptions {
-    id?: string;
-    path: string;
-    routeBasePath: string;
-    include: string[];
-    postsPerPage: number;
-    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>;
-}
 export interface BlogTags {
-    [key: string]: BlogTag;
+    [tagKey: string]: BlogTag;
 }
 export interface BlogTag {
     name: string;
     items: string[];
     permalink: string;
+    pages: BlogPaginated[];
 }
 export interface BlogPost {
     id: string;
     metadata: MetaData;
+    content: string;
 }
 export interface BlogPaginatedMetadata {
     permalink: string;
@@ -84,22 +50,20 @@ export interface MetaData {
     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[];
+    frontMatter: BlogPostFrontMatter & Record<string, unknown>;
 }
 export interface Paginator {
     title: string;
     permalink: string;
 }
-export interface Tag {
-    label: string;
-    permalink: string;
-}
 export interface BlogItemsToMetadata {
     [key: string]: MetaData;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.15a2b59f9",
+  "version": "2.0.0-beta.17",
   "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,32 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/mdx-loader": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/types": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/utils": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/utils-validation": "2.0.0-beta.15a2b59f9",
-    "chalk": "^4.1.1",
-    "escape-string-regexp": "^4.0.0",
+    "@docusaurus/core": "2.0.0-beta.17",
+    "@docusaurus/logger": "2.0.0-beta.17",
+    "@docusaurus/mdx-loader": "2.0.0-beta.17",
+    "@docusaurus/utils": "2.0.0-beta.17",
+    "@docusaurus/utils-common": "2.0.0-beta.17",
+    "@docusaurus/utils-validation": "2.0.0-beta.17",
+    "cheerio": "^1.0.0-rc.10",
     "feed": "^4.2.2",
-    "fs-extra": "^10.0.0",
-    "globby": "^11.0.2",
-    "loader-utils": "^2.0.0",
-    "lodash": "^4.17.20",
-    "reading-time": "^1.3.0",
+    "fs-extra": "^10.0.1",
+    "lodash": "^4.17.21",
+    "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.69.1"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "2.0.0-beta.17",
+    "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "34881586224092fb9b5b2f455a46e19b3eee7f08"
+  "gitHead": "0032c0b0480083227af2e1b4da2d3ee6ce992403"
 }

package/src/authors.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 {BlogContentPaths} from './types';
+import {getDataFileData} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import type {
+  Author,
+  BlogPostFrontMatter,
+  BlogPostFrontMatterAuthor,
+  BlogPostFrontMatterAuthors,
+} from '@docusaurus/plugin-content-blog';
+
+export type AuthorsMap = Record<string, Author>;
+
+const AuthorsMapSchema = Joi.object<AuthorsMap>().pattern(
+  Joi.string(),
+  Joi.object({
+    name: Joi.string(),
+    url: URISchema,
+    imageURL: URISchema,
+    title: Joi.string(),
+    email: Joi.string(),
+  })
+    .rename('image_url', 'imageURL')
+    .or('name', 'imageURL')
+    .unknown()
+    .required(),
+);
+
+export function validateAuthorsMap(content: unknown): AuthorsMap {
+  return Joi.attempt(content, AuthorsMapSchema);
+}
+
+export async function getAuthorsMap(params: {
+  authorsMapPath: string;
+  contentPaths: BlogContentPaths;
+}): Promise<AuthorsMap | undefined> {
+  return getDataFileData(
+    {
+      filePath: params.authorsMapPath,
+      contentPaths: params.contentPaths,
+      fileType: 'authors map',
+    },
+    validateAuthorsMap,
+  );
+}
+
+type AuthorsParam = {
+  frontMatter: BlogPostFrontMatter;
+  authorsMap: AuthorsMap | undefined;
+};
+
+// Legacy v1/early-v2 front matter 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;
+
+  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, but
+      // we only support keys, otherwise, a typo in a key would fallback to
+      // becoming a name and may end up unnoticed
+      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 front matter
+      ...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 front matter, but do we
+    // really want to?
+    if (authors.length > 0) {
+      throw new Error(
+        `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];
+  }
+
+  return authors;
+}

package/src/blogFrontMatter.ts

@@ -5,81 +5,74 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 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 {Tag} from './types';
-
-export type BlogPostFrontMatter = {
-  id?: string;
-  title?: string;
-  description?: string;
-  tags?: (string | Tag)[];
-  slug?: string;
-  draft?: boolean;
-  date?: Date;
-
-  author?: string;
-  author_title?: string;
-  author_url?: string;
-  author_image_url?: string;
+import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
-  image?: string;
-  keywords?: string[];
-  hide_table_of_contents?: boolean;
-
-  /** @deprecated */
-  authorTitle?: string;
-  authorURL?: string;
-  authorImageURL?: string;
-};
+const BlogPostFrontMatterAuthorSchema = Joi.object({
+  key: Joi.string(),
+  name: Joi.string(),
+  title: Joi.string(),
+  url: URISchema,
+  imageURL: Joi.string(),
+})
+  .or('key', 'name', 'imageURL')
+  .rename('image_url', 'imageURL', {alias: true});
 
-// 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 front matter:
+  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 front matter
   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>,