@docusaurus/plugin-content-blog 2.0.0-beta.16 → 2.0.0-beta.19

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

@@ -4,8 +4,7 @@
  * 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;
+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

@@ -14,8 +14,8 @@ function translateListPage(blogListPaginated, translations) {
             items,
             metadata: {
                 ...metadata,
-                blogTitle: translations.title.message,
-                blogDescription: translations.description.message,
+                blogTitle: translations.title?.message ?? page.metadata.blogTitle,
+                blogDescription: translations.description?.message ?? page.metadata.blogDescription,
             },
         };
     });
@@ -43,10 +43,10 @@ function getTranslationFiles(options) {
 }
 exports.getTranslationFiles = getTranslationFiles;
 function translateContent(content, translationFiles) {
-    const [{ content: optionsTranslations }] = translationFiles;
+    const { content: optionsTranslations } = translationFiles[0];
     return {
         ...content,
-        blogSidebarTitle: optionsTranslations['sidebar.title'].message,
+        blogSidebarTitle: optionsTranslations['sidebar.title']?.message ?? content.blogSidebarTitle,
         blogListPaginated: translateListPage(content.blogListPaginated, optionsTranslations),
     };
 }

package/lib/types.d.ts

@@ -4,84 +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 { Tag } from '@docusaurus/utils';
-import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
-import type { BlogPostFrontMatter, Author } from '@docusaurus/plugin-content-blog';
+import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils';
 export declare type BlogContentPaths = ContentPaths;
-export interface BlogContent {
-    blogSidebarTitle: string;
-    blogPosts: BlogPost[];
-    blogListPaginated: BlogPaginated[];
-    blogTags: BlogTags;
-    blogTagsListPath: string | null;
-}
-export interface BlogTags {
-    [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;
-    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[];
-    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 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,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.16",
+  "version": "2.0.0-beta.19",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -18,24 +18,25 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.16",
-    "@docusaurus/logger": "2.0.0-beta.16",
-    "@docusaurus/mdx-loader": "2.0.0-beta.16",
-    "@docusaurus/utils": "2.0.0-beta.16",
-    "@docusaurus/utils-common": "2.0.0-beta.16",
-    "@docusaurus/utils-validation": "2.0.0-beta.16",
+    "@docusaurus/core": "2.0.0-beta.19",
+    "@docusaurus/logger": "2.0.0-beta.19",
+    "@docusaurus/mdx-loader": "2.0.0-beta.19",
+    "@docusaurus/utils": "2.0.0-beta.19",
+    "@docusaurus/utils-common": "2.0.0-beta.19",
+    "@docusaurus/utils-validation": "2.0.0-beta.19",
     "cheerio": "^1.0.0-rc.10",
     "feed": "^4.2.2",
-    "fs-extra": "^10.0.1",
+    "fs-extra": "^10.1.0",
     "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
     "remark-admonitions": "^1.2.1",
-    "tslib": "^2.3.1",
+    "tslib": "^2.4.0",
+    "unist-util-visit": "^2.0.3",
     "utility-types": "^3.10.0",
-    "webpack": "^5.69.1"
+    "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.16",
+    "@docusaurus/types": "2.0.0-beta.19",
     "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
@@ -45,5 +46,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
+  "gitHead": "a71e60a49cce93c1006ef10c41ac03187f057102"
 }

package/src/authors.ts

@@ -15,21 +15,33 @@ import type {
   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(),
-  })
-    .rename('image_url', 'imageURL')
-    .or('name', 'imageURL')
-    .unknown()
-    .required(),
-);
+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 {
   return Joi.attempt(content, AuthorsMapSchema);
@@ -58,7 +70,7 @@ type AuthorsParam = {
 // We may want to deprecate those in favor of using only frontMatter.authors
 function getFrontMatterAuthorLegacy(
   frontMatter: BlogPostFrontMatter,
-): BlogPostFrontMatterAuthor | undefined {
+): Author | undefined {
   const name = frontMatter.author;
   const title = frontMatter.author_title ?? frontMatter.authorTitle;
   const url = frontMatter.author_url ?? frontMatter.authorURL;
@@ -80,7 +92,7 @@ function normalizeFrontMatterAuthors(
   frontMatterAuthors: BlogPostFrontMatterAuthors = [],
 ): BlogPostFrontMatterAuthor[] {
   function normalizeAuthor(
-    authorInput: string | BlogPostFrontMatterAuthor,
+    authorInput: string | Author,
   ): BlogPostFrontMatterAuthor {
     if (typeof authorInput === 'string') {
       // Technically, we could allow users to provide an author's name here, but

package/src/blogUtils.ts

@@ -9,13 +9,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import readingTime from 'reading-time';
 import _ from 'lodash';
-import type {
-  BlogPost,
-  BlogContentPaths,
-  BlogMarkdownLoaderOptions,
-  BlogTags,
-  BlogPaginated,
-} from './types';
+import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 import {
   parseMarkdownString,
   normalizeUrl,
@@ -31,21 +25,24 @@ import {
   getContentPathList,
 } from '@docusaurus/utils';
 import type {LoadContext} from '@docusaurus/types';
-import {validateBlogPostFrontMatter} from './blogFrontMatter';
+import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
 import logger from '@docusaurus/logger';
 import type {
   PluginOptions,
   ReadingTimeFunction,
+  BlogPost,
+  BlogTags,
+  BlogPaginated,
 } from '@docusaurus/plugin-content-blog';
 
 export function truncate(fileString: string, truncateMarker: RegExp): string {
   return fileString.split(truncateMarker, 1).shift()!;
 }
 
-export function getSourceToPermalink(
-  blogPosts: BlogPost[],
-): Record<string, string> {
+export function getSourceToPermalink(blogPosts: BlogPost[]): {
+  [aliasedPath: string]: string;
+} {
   return Object.fromEntries(
     blogPosts.map(({metadata: {source, permalink}}) => [source, permalink]),
   );
@@ -72,7 +69,9 @@ export function paginateBlogPosts({
   const pages: BlogPaginated[] = [];
 
   function permalink(page: number) {
-    return page > 0 ? `${basePageUrl}/page/${page + 1}` : basePageUrl;
+    return page > 0
+      ? normalizeUrl([basePageUrl, `page/${page + 1}`])
+      : basePageUrl;
   }
 
   for (let page = 0; page < numberOfPages; page += 1) {
@@ -86,8 +85,8 @@ export function paginateBlogPosts({
         postsPerPage,
         totalPages: numberOfPages,
         totalCount,
-        previousPage: page !== 0 ? permalink(page - 1) : null,
-        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : null,
+        previousPage: page !== 0 ? permalink(page - 1) : undefined,
+        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : undefined,
         blogDescription,
         blogTitle,
       },
@@ -112,7 +111,7 @@ export function getBlogTags({
   );
 
   return _.mapValues(groups, ({tag, items: tagBlogPosts}) => ({
-    name: tag.label,
+    label: tag.label,
     items: tagBlogPosts.map((item) => item.id),
     permalink: tag.permalink,
     pages: paginateBlogPosts({
@@ -139,23 +138,28 @@ export function parseBlogFileName(
   if (dateFilenameMatch) {
     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}/${folder}${text}`;
-    return {date, text, slug};
+    const date = new Date(`${dateString!}Z`);
+    const slugDate = dateString!.replace(/-/g, '/');
+    const slug = `/${slugDate}/${folder!}${text!}`;
+    return {date, text: text!, slug};
   }
   const text = blogSourceRelative.replace(/(?:\/index)?\.mdx?$/, '');
   const slug = `/${text}`;
   return {date: undefined, text, slug};
 }
 
-function formatBlogPostDate(locale: string, date: Date): string {
+function formatBlogPostDate(
+  locale: string,
+  date: Date,
+  calendar: string,
+): string {
   try {
     return new Intl.DateTimeFormat(locale, {
       day: 'numeric',
       month: 'long',
       year: 'numeric',
       timeZone: 'UTC',
+      calendar,
     }).format(date);
   } catch (err) {
     logger.error`Can't format blog post date "${String(date)}"`;
@@ -245,13 +249,17 @@ async function processBlogSourceFile(
       });
       return result.date;
     } catch (err) {
-      logger.error(err);
+      logger.warn(err);
       return (await fs.stat(blogSourceAbsolute)).birthtime;
     }
   }
 
   const date = await getDate();
-  const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
+  const formattedDate = formatBlogPostDate(
+    i18n.currentLocale,
+    date,
+    i18n.localeConfigs[i18n.currentLocale]!.calendar,
+  );
 
   const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
   const description = frontMatter.description ?? excerpt ?? '';

package/src/deps.d.ts

@@ -6,7 +6,7 @@
  */
 
 declare module 'remark-admonitions' {
-  type Options = Record<string, unknown>;
+  type Options = {[key: string]: unknown};
 
   const plugin: (options?: Options) => void;
   export = plugin;

package/src/feed.ts

@@ -6,14 +6,8 @@
  */
 
 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 {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
+import {load as cheerioLoad} from 'cheerio';
 import type {DocusaurusConfig} from '@docusaurus/types';
 import path from 'path';
 import fs from 'fs-extra';
@@ -21,6 +15,7 @@ import type {
   FeedType,
   PluginOptions,
   Author,
+  BlogPost,
 } from '@docusaurus/plugin-content-blog';
 import {blogPostContainerID} from '@docusaurus/utils-common';
 
@@ -29,11 +24,13 @@ async function generateBlogFeed({
   options,
   siteConfig,
   outDir,
+  locale,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
   outDir: string;
+  locale: string;
 }): Promise<Feed | null> {
   if (!blogPosts.length) {
     return null;
@@ -43,65 +40,65 @@ async function generateBlogFeed({
   const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
   const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, routeBasePath]);
 
-  const updated = blogPosts[0] && blogPosts[0].metadata.date;
+  const updated = blogPosts[0]?.metadata.date;
 
   const feed = new Feed({
     id: blogBaseUrl,
-    title: feedOptions.title || `${title} Blog`,
+    title: feedOptions.title ?? `${title} Blog`,
     updated,
-    language: feedOptions.language,
+    language: feedOptions.language ?? locale,
     link: blogBaseUrl,
-    description: feedOptions.description || `${siteConfig.title} Blog`,
+    description: feedOptions.description ?? `${siteConfig.title} Blog`,
     favicon: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
     copyright: feedOptions.copyright,
   });
 
   function toFeedAuthor(author: Author): FeedAuthor {
-    // TODO ask author emails?
-    // RSS feed requires email to render authors
-    return {name: author.name, link: author.url};
+    return {name: author.name, link: author.url, email: author.email};
   }
 
-  await mapAsyncSequential(blogPosts, async (post) => {
-    const {
-      id,
-      metadata: {
+  await Promise.all(
+    blogPosts.map(async (post) => {
+      const {
+        id,
+        metadata: {
+          title: metadataTitle,
+          permalink,
+          date,
+          description,
+          authors,
+          tags,
+        },
+      } = post;
+
+      const content = await readOutputHTMLFile(
+        permalink.replace(siteConfig.baseUrl, ''),
+        outDir,
+        siteConfig.trailingSlash,
+      );
+      const $ = cheerioLoad(content);
+
+      const feedItem: FeedItem = {
         title: metadataTitle,
-        permalink,
+        id,
+        link: normalizeUrl([siteUrl, 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,
-      // 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
-    // it causes an error when authors array is empty
-    const feedItemAuthors = authors.map(toFeedAuthor);
-    if (feedItemAuthors.length > 0) {
-      feedItem.author = feedItemAuthors;
-    }
-
-    feed.addItem(feedItem);
-  });
+        // 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
+      // it causes an error when authors array is empty
+      const feedItemAuthors = authors.map(toFeedAuthor);
+      if (feedItemAuthors.length > 0) {
+        feedItem.author = feedItemAuthors;
+      }
+
+      return feedItem;
+    }),
+  ).then((items) => items.forEach(feed.addItem));
 
   return feed;
 }
@@ -128,10 +125,7 @@ async function createBlogFeedFile({
     }
   })();
   try {
-    await fs.outputFile(
-      posixPath(path.join(generatePath, feedPath)),
-      feedContent,
-    );
+    await fs.outputFile(path.join(generatePath, feedPath), feedContent);
   } catch (err) {
     throw new Error(`Generating ${feedType} feed failed: ${err}.`);
   }
@@ -142,17 +136,20 @@ export async function createBlogFeedFiles({
   options,
   siteConfig,
   outDir,
+  locale,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
   outDir: string;
+  locale: string;
 }): Promise<void> {
   const feed = await generateBlogFeed({
     blogPosts,
     options,
     siteConfig,
     outDir,
+    locale,
   });
 
   const feedTypes = options.feedOptions.type;

package/src/{blogFrontMatter.ts → frontMatter.ts}

@@ -74,8 +74,8 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
     '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
 });
 
-export function validateBlogPostFrontMatter(
-  frontMatter: Record<string, unknown>,
-): BlogPostFrontMatter {
+export function validateBlogPostFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): BlogPostFrontMatter {
   return validateFrontMatter(frontMatter, BlogFrontMatterSchema);
 }