@docusaurus/plugin-content-blog 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/lib/{pluginOptionSchema.js → options.js}

@@ -6,14 +6,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PluginOptionSchema = exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = 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*-->/,
+    admonitions: true,
+    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({
+const 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,31 @@ 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),
+}).default(exports.DEFAULT_OPTIONS);
+function validateOptions({ validate, options, }) {
+    const validatedOptions = validate(PluginOptionSchema, options);
+    return validatedOptions;
+}
+exports.validateOptions = validateOptions;

package/lib/remark/footnoteIDFixer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { Transformer } from 'unified';
+/**
+ * In the blog list view, each post will be compiled separately. However, they
+ * may use the same footnote IDs. This leads to duplicated DOM IDs and inability
+ * to navigate to footnote references. This plugin fixes it by appending a
+ * unique hash to each reference/definition.
+ */
+export default function plugin(): Transformer;

package/lib/remark/footnoteIDFixer.js

@@ -0,0 +1,29 @@
+"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 });
+const tslib_1 = require("tslib");
+const unist_util_visit_1 = tslib_1.__importDefault(require("unist-util-visit"));
+const utils_1 = require("@docusaurus/utils");
+/**
+ * In the blog list view, each post will be compiled separately. However, they
+ * may use the same footnote IDs. This leads to duplicated DOM IDs and inability
+ * to navigate to footnote references. This plugin fixes it by appending a
+ * unique hash to each reference/definition.
+ */
+function plugin() {
+    return (root, vfile) => {
+        const suffix = `-${(0, utils_1.simpleHash)(vfile.path, 6)}`;
+        (0, unist_util_visit_1.default)(root, 'footnoteReference', (node) => {
+            node.identifier += suffix;
+        });
+        (0, unist_util_visit_1.default)(root, 'footnoteDefinition', (node) => {
+            node.identifier += suffix;
+        });
+    };
+}
+exports.default = plugin;

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 { TranslationFile } from '@docusaurus/types';
+import type { PluginOptions, BlogContent } from '@docusaurus/plugin-content-blog';
+export declare function getTranslationFiles(options: PluginOptions): TranslationFile[];
+export declare function translateContent(content: BlogContent, translationFiles: TranslationFile[]): 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 ?? page.metadata.blogTitle,
+                blogDescription: translations.description?.message ?? page.metadata.blogDescription,
+            },
+        };
+    });
+}
+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[0];
+    return {
+        ...content,
+        blogSidebarTitle: optionsTranslations['sidebar.title']?.message ?? content.blogSidebarTitle,
+        blogListPaginated: translateListPage(content.blogListPaginated, optionsTranslations),
+    };
+}
+exports.translateContent = translateContent;

package/lib/types.d.ts

@@ -4,120 +4,15 @@
  * 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 { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils';
 export declare type BlogContentPaths = ContentPaths;
-export interface BlogContent {
-    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;
-}
-export interface BlogTag {
-    name: string;
-    items: string[];
-    permalink: string;
-}
-export interface BlogPost {
-    id: string;
-    metadata: MetaData;
-}
-export interface BlogPaginatedMetadata {
-    permalink: string;
-    page: number;
-    postsPerPage: number;
-    totalPages: number;
-    totalCount: number;
-    previousPage: string | null;
-    nextPage: string | null;
-    blogTitle: string;
-    blogDescription: string;
-}
-export interface BlogPaginated {
-    metadata: BlogPaginatedMetadata;
-    items: string[];
-}
-export interface MetaData {
-    permalink: string;
-    source: string;
-    description: string;
-    date: Date;
-    formattedDate: string;
-    tags: (Tag | string)[];
-    title: string;
-    readingTime?: number;
-    prevItem?: Paginator;
-    nextItem?: Paginator;
-    truncated: boolean;
-    editUrl?: string;
-}
-export interface Paginator {
-    title: string;
-    permalink: string;
-}
-export interface Tag {
-    label: string;
-    permalink: string;
-}
-export interface BlogItemsToMetadata {
-    [key: string]: MetaData;
-}
-export interface TagsModule {
-    [key: string]: TagModule;
-}
-export interface TagModule {
-    allTagsPath: string;
-    slug: string;
-    name: string;
-    count: number;
-    permalink: string;
-}
 export declare type BlogBrokenMarkdownLink = BrokenMarkdownLink<BlogContentPaths>;
 export declare type BlogMarkdownLoaderOptions = {
     siteDir: string;
     contentPaths: BlogContentPaths;
     truncateMarker: RegExp;
-    sourceToPermalink: Record<string, string>;
+    sourceToPermalink: {
+        [aliasedPath: string]: string;
+    };
     onBrokenMarkdownLink: (brokenMarkdownLink: BlogBrokenMarkdownLink) => void;
 };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.fbdeefcac",
+  "version": "2.0.0-rc.1",
   "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.fbdeefcac",
-    "@docusaurus/mdx-loader": "2.0.0-beta.fbdeefcac",
-    "@docusaurus/types": "2.0.0-beta.fbdeefcac",
-    "@docusaurus/utils": "2.0.0-beta.fbdeefcac",
-    "@docusaurus/utils-validation": "2.0.0-beta.fbdeefcac",
-    "chalk": "^4.1.1",
-    "escape-string-regexp": "^4.0.0",
+    "@docusaurus/core": "2.0.0-rc.1",
+    "@docusaurus/logger": "2.0.0-rc.1",
+    "@docusaurus/mdx-loader": "2.0.0-rc.1",
+    "@docusaurus/types": "2.0.0-rc.1",
+    "@docusaurus/utils": "2.0.0-rc.1",
+    "@docusaurus/utils-common": "2.0.0-rc.1",
+    "@docusaurus/utils-validation": "2.0.0-rc.1",
+    "cheerio": "^1.0.0-rc.12",
     "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",
-    "remark-admonitions": "^1.2.1",
-    "tslib": "^2.2.0",
-    "webpack": "^5.40.0"
+    "fs-extra": "^10.1.0",
+    "lodash": "^4.17.21",
+    "reading-time": "^1.5.0",
+    "tslib": "^2.4.0",
+    "unist-util-visit": "^2.0.3",
+    "utility-types": "^3.10.0",
+    "webpack": "^5.73.0"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "2.0.0-beta.21",
+    "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": ">=16.14"
   },
-  "gitHead": "636c490f68d16a7452499ab722deb5ed51ef49fc"
+  "gitHead": "c8ddd02a8e68dfaf515c20465a049a83153bd205"
 }

package/src/authors.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 {getDataFileData} from '@docusaurus/utils';
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import type {BlogContentPaths} from './types';
+import type {
+  Author,
+  BlogPostFrontMatter,
+  BlogPostFrontMatterAuthor,
+  BlogPostFrontMatterAuthors,
+} from '@docusaurus/plugin-content-blog';
+
+export type AuthorsMap = {[authorKey: 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()
+      .messages({
+        'object.base':
+          '{#label} should be an author object containing properties like name, title, and imageURL.',
+        'any.required':
+          '{#label} cannot be undefined. It should be an author object containing properties like name, title, and imageURL.',
+      }),
+  )
+  .messages({
+    'object.base':
+      "The authors map file should contain an object where each entry contains an author key and the corresponding author's data.",
+  });
+
+export function validateAuthorsMap(content: unknown): AuthorsMap {
+  const {error, value} = AuthorsMapSchema.validate(content);
+  if (error) {
+    throw error;
+  }
+  return value;
+}
+
+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,
+): Author | 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 | Author,
+  ): 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;
+}