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

package/lib/blogUtils.d.ts

@@ -4,9 +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 { BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions, BlogTags, BlogPaginated } from './types';
+import type { BlogContentPaths, BlogMarkdownLoaderOptions } from './types';
 import type { LoadContext } from '@docusaurus/types';
-import type { PluginOptions } from '@docusaurus/plugin-content-blog';
+import type { PluginOptions, BlogPost, BlogTags, BlogPaginated } from '@docusaurus/plugin-content-blog';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
 export declare function getSourceToPermalink(blogPosts: BlogPost[]): {
     [aliasedPath: string]: string;

package/lib/blogUtils.js

@@ -58,7 +58,7 @@ exports.paginateBlogPosts = paginateBlogPosts;
 function getBlogTags({ blogPosts, ...params }) {
     const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
     return lodash_1.default.mapValues(groups, ({ tag, items: tagBlogPosts }) => ({
-        name: tag.label,
+        label: tag.label,
         items: tagBlogPosts.map((item) => item.id),
         permalink: tag.permalink,
         pages: paginateBlogPosts({
@@ -85,13 +85,14 @@ function parseBlogFileName(blogSourceRelative) {
     return { date: undefined, text, slug };
 }
 exports.parseBlogFileName = parseBlogFileName;
-function formatBlogPostDate(locale, date) {
+function formatBlogPostDate(locale, date, calendar) {
     try {
         return new Intl.DateTimeFormat(locale, {
             day: 'numeric',
             month: 'long',
             year: 'numeric',
             timeZone: 'UTC',
+            calendar,
         }).format(date);
     }
     catch (err) {
@@ -157,7 +158,7 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
         }
     }
     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 ?? '';
     const slug = frontMatter.slug || parsedBlogFileName.slug;

package/lib/feed.d.ts

@@ -4,9 +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 { BlogPost } from './types';
 import type { DocusaurusConfig } from '@docusaurus/types';
-import type { PluginOptions } from '@docusaurus/plugin-content-blog';
+import type { PluginOptions, BlogPost } from '@docusaurus/plugin-content-blog';
 export declare function createBlogFeedFiles({ blogPosts, options, siteConfig, outDir, locale, }: {
     blogPosts: BlogPost[];
     options: PluginOptions;

package/lib/feed.js

@@ -35,7 +35,7 @@ async function generateBlogFeed({ blogPosts, options, siteConfig, outDir, locale
     function toFeedAuthor(author) {
         return { name: author.name, link: author.url, email: author.email };
     }
-    await (0, utils_1.mapAsyncSequential)(blogPosts, async (post) => {
+    await Promise.all(blogPosts.map(async (post) => {
         const { id, metadata: { title: metadataTitle, permalink, date, description, authors, tags, }, } = post;
         const content = await (0, utils_1.readOutputHTMLFile)(permalink.replace(siteConfig.baseUrl, ''), outDir, siteConfig.trailingSlash);
         const $ = (0, cheerio_1.load)(content);
@@ -55,8 +55,8 @@ async function generateBlogFeed({ blogPosts, options, siteConfig, outDir, locale
         if (feedItemAuthors.length > 0) {
             feedItem.author = feedItemAuthors;
         }
-        feed.addItem(feedItem);
-    });
+        return feedItem;
+    })).then((items) => items.forEach(feed.addItem));
     return feed;
 }
 async function createBlogFeedFile({ feed, feedType, generatePath, }) {
@@ -73,7 +73,7 @@ async function createBlogFeedFile({ feed, feedType, generatePath, }) {
         }
     })();
     try {
-        await fs_extra_1.default.outputFile((0, utils_1.posixPath)(path_1.default.join(generatePath, feedPath)), feedContent);
+        await fs_extra_1.default.outputFile(path_1.default.join(generatePath, feedPath), feedContent);
     }
     catch (err) {
         throw new Error(`Generating ${feedType} feed failed: ${err}.`);

package/lib/index.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 { LoadContext, Plugin } from '@docusaurus/types';
-import type { PluginOptions } from '@docusaurus/plugin-content-blog';
+import type { PluginOptions, BlogContent } from '@docusaurus/plugin-content-blog';
 export default function pluginContentBlog(context: LoadContext, options: PluginOptions): Promise<Plugin<BlogContent>>;
 export { validateOptions } from './options';

package/lib/index.js

@@ -10,6 +10,7 @@ exports.validateOptions = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const remark_admonitions_1 = tslib_1.__importDefault(require("remark-admonitions"));
+const footnoteIDFixer_1 = tslib_1.__importDefault(require("./remark/footnoteIDFixer"));
 const utils_1 = require("@docusaurus/utils");
 const translations_1 = require("./translations");
 const blogUtils_1 = require("./blogUtils");
@@ -46,12 +47,14 @@ async function pluginContentBlog(context, options) {
             const contentMarkdownGlobs = (0, utils_1.getContentPathList)(contentPaths).flatMap((contentPath) => include.map((pattern) => `${contentPath}/${pattern}`));
             return [authorsMapFilePath, ...contentMarkdownGlobs].filter(Boolean);
         },
-        async getTranslationFiles() {
+        getTranslationFiles() {
             return (0, translations_1.getTranslationFiles)(options);
         },
         // Fetches blog contents and returns metadata for the necessary routes.
         async loadContent() {
             const { postsPerPage: postsPerPageOption, routeBasePath, tagsBasePath, blogDescription, blogTitle, blogSidebarTitle, } = options;
+            const baseBlogUrl = (0, utils_1.normalizeUrl)([baseUrl, routeBasePath]);
+            const blogTagsListPath = (0, utils_1.normalizeUrl)([baseBlogUrl, tagsBasePath]);
             const blogPosts = await (0, blogUtils_1.generateBlogPosts)(contentPaths, context, options);
             if (!blogPosts.length) {
                 return {
@@ -59,7 +62,7 @@ async function pluginContentBlog(context, options) {
                     blogPosts: [],
                     blogListPaginated: [],
                     blogTags: {},
-                    blogTagsListPath: null,
+                    blogTagsListPath,
                     blogTagsPaginated: [],
                 };
             }
@@ -80,7 +83,6 @@ async function pluginContentBlog(context, options) {
                     };
                 }
             });
-            const baseBlogUrl = (0, utils_1.normalizeUrl)([baseUrl, routeBasePath]);
             const blogListPaginated = (0, blogUtils_1.paginateBlogPosts)({
                 blogPosts,
                 blogTitle,
@@ -94,8 +96,6 @@ async function pluginContentBlog(context, options) {
                 blogDescription,
                 blogTitle,
             });
-            const tagsPath = (0, utils_1.normalizeUrl)([baseBlogUrl, tagsBasePath]);
-            const blogTagsListPath = Object.keys(blogTags).length > 0 ? tagsPath : null;
             return {
                 blogSidebarTitle,
                 blogPosts,
@@ -121,7 +121,7 @@ async function pluginContentBlog(context, options) {
                     routeBasePath,
                     archiveBasePath,
                 ]);
-                // creates a blog archive route
+                // Create a blog archive route
                 const archiveProp = await createData(`${(0, utils_1.docuHash)(archiveUrl)}.json`, JSON.stringify({ blogPosts }, null, 2));
                 addRoute({
                     path: archiveUrl,
@@ -172,10 +172,7 @@ async function pluginContentBlog(context, options) {
                     exact: true,
                     modules: {
                         sidebar: aliasedSource(sidebarProp),
-                        items: items.map((postID) => 
-                        // To tell routes.js this is an import and not a nested object
-                        // to recurse.
-                        ({
+                        items: items.map((postID) => ({
                             content: {
                                 __import: true,
                                 path: blogItemsToMetadata[postID].source,
@@ -188,23 +185,37 @@ async function pluginContentBlog(context, options) {
                     },
                 });
             }));
-            // Tags.
-            if (blogTagsListPath === null) {
+            // Tags. This is the last part so we early-return if there are no tags.
+            if (Object.keys(blogTags).length === 0) {
                 return;
             }
-            const tagsModule = Object.fromEntries(Object.entries(blogTags).map(([, tag]) => {
-                const tagModule = {
-                    allTagsPath: blogTagsListPath,
-                    name: tag.name,
-                    count: tag.items.length,
+            async function createTagsListPage() {
+                const tagsProp = Object.values(blogTags).map((tag) => ({
+                    label: tag.label,
                     permalink: tag.permalink,
-                };
-                return [tag.name, tagModule];
-            }));
-            async function createTagRoutes(tag) {
+                    count: tag.items.length,
+                }));
+                const tagsPropPath = await createData(`${(0, utils_1.docuHash)(`${blogTagsListPath}-tags`)}.json`, JSON.stringify(tagsProp, null, 2));
+                addRoute({
+                    path: blogTagsListPath,
+                    component: blogTagsListComponent,
+                    exact: true,
+                    modules: {
+                        sidebar: aliasedSource(sidebarProp),
+                        tags: aliasedSource(tagsPropPath),
+                    },
+                });
+            }
+            async function createTagPostsListPage(tag) {
                 await Promise.all(tag.pages.map(async (blogPaginated) => {
                     const { metadata, items } = blogPaginated;
-                    const tagsMetadataPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}.json`, JSON.stringify(tagsModule[tag.name], null, 2));
+                    const tagProp = {
+                        label: tag.label,
+                        permalink: tag.permalink,
+                        allTagsPath: blogTagsListPath,
+                        count: tag.items.length,
+                    };
+                    const tagPropPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}.json`, JSON.stringify(tagProp, null, 2));
                     const listMetadataPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}-list.json`, JSON.stringify(metadata, null, 2));
                     addRoute({
                         path: metadata.permalink,
@@ -224,26 +235,14 @@ async function pluginContentBlog(context, options) {
                                     },
                                 };
                             }),
-                            metadata: aliasedSource(tagsMetadataPath),
+                            tag: aliasedSource(tagPropPath),
                             listMetadata: aliasedSource(listMetadataPath),
                         },
                     });
                 }));
             }
-            await Promise.all(Object.values(blogTags).map(createTagRoutes));
-            // Only create /tags page if there are tags.
-            if (Object.keys(blogTags).length > 0) {
-                const tagsListPath = await createData(`${(0, utils_1.docuHash)(`${blogTagsListPath}-tags`)}.json`, JSON.stringify(tagsModule, null, 2));
-                addRoute({
-                    path: blogTagsListPath,
-                    component: blogTagsListComponent,
-                    exact: true,
-                    modules: {
-                        sidebar: aliasedSource(sidebarProp),
-                        tags: aliasedSource(tagsListPath),
-                    },
-                });
-            }
+            await createTagsListPage();
+            await Promise.all(Object.values(blogTags).map(createTagPostsListPage));
         },
         translateContent({ content, translationFiles }) {
             return (0, translations_1.translateContent)(content, translationFiles);
@@ -283,7 +282,10 @@ async function pluginContentBlog(context, options) {
                                     options: {
                                         remarkPlugins,
                                         rehypePlugins,
-                                        beforeDefaultRemarkPlugins,
+                                        beforeDefaultRemarkPlugins: [
+                                            footnoteIDFixer_1.default,
+                                            ...beforeDefaultRemarkPlugins,
+                                        ],
                                         beforeDefaultRehypePlugins,
                                         staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
                                         siteDir,

package/lib/options.js

@@ -85,7 +85,7 @@ const PluginOptionSchema = utils_validation_1.Joi.object({
             .default(exports.DEFAULT_OPTIONS.feedOptions.type),
         title: utils_validation_1.Joi.string().allow(''),
         description: utils_validation_1.Joi.string().allow(''),
-        // only add default value when user actually wants a feed (type is not null)
+        // 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(),

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

@@ -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/types.d.ts

@@ -5,34 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils';
-import type { BlogPostMetadata } from '@docusaurus/plugin-content-blog';
-import type { Metadata as BlogPaginatedMetadata } from '@theme/BlogListPage';
 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: BlogPostMetadata;
-    content: string;
-}
-export interface BlogPaginated {
-    metadata: BlogPaginatedMetadata;
-    items: string[];
-}
 export declare type BlogBrokenMarkdownLink = BrokenMarkdownLink<BlogContentPaths>;
 export declare type BlogMarkdownLoaderOptions = {
     siteDir: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.18",
+  "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.18",
-    "@docusaurus/logger": "2.0.0-beta.18",
-    "@docusaurus/mdx-loader": "2.0.0-beta.18",
-    "@docusaurus/utils": "2.0.0-beta.18",
-    "@docusaurus/utils-common": "2.0.0-beta.18",
-    "@docusaurus/utils-validation": "2.0.0-beta.18",
+    "@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.70.0"
+    "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.18",
+    "@docusaurus/types": "2.0.0-beta.19",
     "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
@@ -45,5 +46,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "1a945d06993d53376e61bed2c942799fe07dc336"
+  "gitHead": "a71e60a49cce93c1006ef10c41ac03187f057102"
 }

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,
@@ -37,6 +31,9 @@ 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 {
@@ -114,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({
@@ -151,13 +148,18 @@ export function parseBlogFileName(
   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)}"`;
@@ -253,7 +255,11 @@ async function processBlogSourceFile(
   }
 
   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/feed.ts

@@ -6,13 +6,7 @@
  */
 
 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 {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
 import {load as cheerioLoad} from 'cheerio';
 import type {DocusaurusConfig} from '@docusaurus/types';
 import path from 'path';
@@ -21,6 +15,7 @@ import type {
   FeedType,
   PluginOptions,
   Author,
+  BlogPost,
 } from '@docusaurus/plugin-content-blog';
 import {blogPostContainerID} from '@docusaurus/utils-common';
 
@@ -62,46 +57,48 @@ async function generateBlogFeed({
     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 $ = cheerioLoad(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}.`);
   }

package/src/index.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import admonitions from 'remark-admonitions';
+import footnoteIDFixer from './remark/footnoteIDFixer';
 import {
   normalizeUrl,
   docuHash,
@@ -19,17 +20,12 @@ import {
   getContentPathList,
   getDataFilePath,
   DEFAULT_PLUGIN_ID,
+  type TagsListItem,
+  type TagModule,
 } from '@docusaurus/utils';
 import {translateContent, getTranslationFiles} from './translations';
 
-import type {
-  BlogTag,
-  BlogTags,
-  BlogContent,
-  BlogPaginated,
-  BlogContentPaths,
-  BlogMarkdownLoaderOptions,
-} from './types';
+import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
 import {
   generateBlogPosts,
@@ -43,7 +39,10 @@ import type {
   BlogPostFrontMatter,
   BlogPostMetadata,
   Assets,
-  TagModule,
+  BlogTag,
+  BlogTags,
+  BlogContent,
+  BlogPaginated,
 } from '@docusaurus/plugin-content-blog';
 
 export default async function pluginContentBlog(
@@ -102,7 +101,7 @@ export default async function pluginContentBlog(
       ) as string[];
     },
 
-    async getTranslationFiles() {
+    getTranslationFiles() {
       return getTranslationFiles(options);
     },
 
@@ -117,6 +116,8 @@ export default async function pluginContentBlog(
         blogSidebarTitle,
       } = options;
 
+      const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
+      const blogTagsListPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
       const blogPosts = await generateBlogPosts(contentPaths, context, options);
 
       if (!blogPosts.length) {
@@ -125,7 +126,7 @@ export default async function pluginContentBlog(
           blogPosts: [],
           blogListPaginated: [],
           blogTags: {},
-          blogTagsListPath: null,
+          blogTagsListPath,
           blogTagsPaginated: [],
         };
       }
@@ -150,8 +151,6 @@ export default async function pluginContentBlog(
         }
       });
 
-      const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
-
       const blogListPaginated: BlogPaginated[] = paginateBlogPosts({
         blogPosts,
         blogTitle,
@@ -167,11 +166,6 @@ export default async function pluginContentBlog(
         blogTitle,
       });
 
-      const tagsPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
-
-      const blogTagsListPath =
-        Object.keys(blogTags).length > 0 ? tagsPath : null;
-
       return {
         blogSidebarTitle,
         blogPosts,
@@ -218,7 +212,7 @@ export default async function pluginContentBlog(
           routeBasePath,
           archiveBasePath,
         ]);
-        // creates a blog archive route
+        // Create a blog archive route
         const archiveProp = await createData(
           `${docuHash(archiveUrl)}.json`,
           JSON.stringify({blogPosts}, null, 2),
@@ -292,49 +286,62 @@ export default async function pluginContentBlog(
             exact: true,
             modules: {
               sidebar: aliasedSource(sidebarProp),
-              items: items.map((postID) =>
-                // To tell routes.js this is an import and not a nested object
-                // to recurse.
-                ({
-                  content: {
-                    __import: true,
-                    path: blogItemsToMetadata[postID]!.source,
-                    query: {
-                      truncated: true,
-                    },
+              items: items.map((postID) => ({
+                content: {
+                  __import: true,
+                  path: blogItemsToMetadata[postID]!.source,
+                  query: {
+                    truncated: true,
                   },
-                }),
-              ),
+                },
+              })),
               metadata: aliasedSource(pageMetadataPath),
             },
           });
         }),
       );
 
-      // Tags.
-      if (blogTagsListPath === null) {
+      // Tags. This is the last part so we early-return if there are no tags.
+      if (Object.keys(blogTags).length === 0) {
         return;
       }
 
-      const tagsModule: {[tagName: string]: TagModule} = Object.fromEntries(
-        Object.entries(blogTags).map(([, tag]) => {
-          const tagModule: TagModule = {
-            allTagsPath: blogTagsListPath,
-            name: tag.name,
-            count: tag.items.length,
-            permalink: tag.permalink,
-          };
-          return [tag.name, tagModule];
-        }),
-      );
+      async function createTagsListPage() {
+        const tagsProp: TagsListItem[] = Object.values(blogTags).map((tag) => ({
+          label: tag.label,
+          permalink: tag.permalink,
+          count: tag.items.length,
+        }));
+
+        const tagsPropPath = await createData(
+          `${docuHash(`${blogTagsListPath}-tags`)}.json`,
+          JSON.stringify(tagsProp, null, 2),
+        );
 
-      async function createTagRoutes(tag: BlogTag): Promise<void> {
+        addRoute({
+          path: blogTagsListPath,
+          component: blogTagsListComponent,
+          exact: true,
+          modules: {
+            sidebar: aliasedSource(sidebarProp),
+            tags: aliasedSource(tagsPropPath),
+          },
+        });
+      }
+
+      async function createTagPostsListPage(tag: BlogTag): Promise<void> {
         await Promise.all(
           tag.pages.map(async (blogPaginated) => {
             const {metadata, items} = blogPaginated;
-            const tagsMetadataPath = await createData(
+            const tagProp: TagModule = {
+              label: tag.label,
+              permalink: tag.permalink,
+              allTagsPath: blogTagsListPath,
+              count: tag.items.length,
+            };
+            const tagPropPath = await createData(
               `${docuHash(metadata.permalink)}.json`,
-              JSON.stringify(tagsModule[tag.name], null, 2),
+              JSON.stringify(tagProp, null, 2),
             );
 
             const listMetadataPath = await createData(
@@ -360,7 +367,7 @@ export default async function pluginContentBlog(
                     },
                   };
                 }),
-                metadata: aliasedSource(tagsMetadataPath),
+                tag: aliasedSource(tagPropPath),
                 listMetadata: aliasedSource(listMetadataPath),
               },
             });
@@ -368,25 +375,8 @@ export default async function pluginContentBlog(
         );
       }
 
-      await Promise.all(Object.values(blogTags).map(createTagRoutes));
-
-      // Only create /tags page if there are tags.
-      if (Object.keys(blogTags).length > 0) {
-        const tagsListPath = await createData(
-          `${docuHash(`${blogTagsListPath}-tags`)}.json`,
-          JSON.stringify(tagsModule, null, 2),
-        );
-
-        addRoute({
-          path: blogTagsListPath,
-          component: blogTagsListComponent,
-          exact: true,
-          modules: {
-            sidebar: aliasedSource(sidebarProp),
-            tags: aliasedSource(tagsListPath),
-          },
-        });
-      }
+      await createTagsListPage();
+      await Promise.all(Object.values(blogTags).map(createTagPostsListPage));
     },
 
     translateContent({content, translationFiles}) {
@@ -439,7 +429,10 @@ export default async function pluginContentBlog(
                   options: {
                     remarkPlugins,
                     rehypePlugins,
-                    beforeDefaultRemarkPlugins,
+                    beforeDefaultRemarkPlugins: [
+                      footnoteIDFixer,
+                      ...beforeDefaultRemarkPlugins,
+                    ],
                     beforeDefaultRehypePlugins,
                     staticDirs: siteConfig.staticDirectories.map((dir) =>
                       path.resolve(siteDir, dir),

package/src/options.ts

@@ -111,7 +111,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
       .default(DEFAULT_OPTIONS.feedOptions.type),
     title: Joi.string().allow(''),
     description: Joi.string().allow(''),
-    // only add default value when user actually wants a feed (type is not null)
+    // Only add default value when user actually wants a feed (type is not null)
     copyright: Joi.when('type', {
       is: Joi.any().valid(null),
       then: Joi.string().optional(),

package/src/plugin-content-blog.d.ts

@@ -6,11 +6,12 @@
  */
 
 declare module '@docusaurus/plugin-content-blog' {
-  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-  import type {FrontMatterTag} from '@docusaurus/utils';
+  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {FrontMatterTag, Tag} from '@docusaurus/utils';
+  import type {Plugin, LoadContext} from '@docusaurus/types';
   import type {Overwrite} from 'utility-types';
 
-  export interface Assets {
+  export type Assets = {
     /**
      * If `metadata.image` is a collocated image path, this entry will be the
      * bundler-generated image path. Otherwise, it's empty, and the image URL
@@ -25,13 +26,9 @@ declare module '@docusaurus/plugin-content-blog' {
      * should be accessed through `authors.imageURL`.
      */
     authorsImageUrls: (string | undefined)[];
-  }
+  };
 
-  /**
-   * Unknown keys are allowed, so that we can pass custom fields to authors,
-   * e.g., `twitter`.
-   */
-  export interface Author extends Record<string, unknown> {
+  export type Author = {
     /**
      * If `name` doesn't exist, an `imageURL` is expected.
      */
@@ -55,7 +52,12 @@ declare module '@docusaurus/plugin-content-blog' {
      * to generate a fallback `mailto:` URL.
      */
     email?: string;
-  }
+    /**
+     * Unknown keys are allowed, so that we can pass custom fields to authors,
+     * e.g., `twitter`.
+     */
+    [key: string]: unknown;
+  };
 
   /**
    * Everything is partial/unnormalized, because front matter is always
@@ -81,10 +83,7 @@ declare module '@docusaurus/plugin-content-blog' {
      * @see {@link BlogPostMetadata.tags}
      */
     tags?: FrontMatterTag[];
-    /**
-     * Custom slug appended after /<baseUrl>/<routeBasePath>/
-     * @see {@link BlogPostMetadata.slug}
-     */
+    /** Custom slug appended after `/<baseUrl>/<routeBasePath>/` */
     slug?: string;
     /**
      * Marks the post as draft and excludes it from the production build.
@@ -130,25 +129,18 @@ declare module '@docusaurus/plugin-content-blog' {
     /** @deprecated v1 legacy */
     authorImageURL?: string;
 
-    /**
-     * @see {@link BlogPostMetadata.image}
-     */
+    /** Used in the head meta. Should use `assets.image` in priority. */
     image?: string;
-    /**
-     * Used in the head meta
-     */
+    /** Used in the head meta. */
     keywords?: string[];
-    /**
-     * Hide the right TOC
-     */
+    /** Hide the right TOC. */
     hide_table_of_contents?: boolean;
     /**
-     * Minimum TOC heading level
+     * Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
+     * the max value.
      */
     toc_min_heading_level?: number;
-    /**
-     * Maximum TOC heading level
-     */
+    /** Maximum TOC heading level. Must be between 2 and 6. */
     toc_max_heading_level?: number;
   };
 
@@ -175,9 +167,7 @@ declare module '@docusaurus/plugin-content-blog' {
     | (string | BlogPostFrontMatterAuthor)[];
 
   export type BlogPostMetadata = {
-    /**
-     * Path to the Markdown source, with `@site` alias.
-     */
+    /** Path to the Markdown source, with `@site` alias. */
     readonly source: string;
     /**
      * Used to generate the page h1 heading, tab title, and pagination title.
@@ -193,9 +183,7 @@ declare module '@docusaurus/plugin-content-blog' {
      * render the date regardless of the existence of `Intl.DateTimeFormat`.
      */
     readonly formattedDate: string;
-    /**
-     * Full link including base URL.
-     */
+    /** Full link including base URL. */
     readonly permalink: string;
     /**
      * Description used in the meta. Could be an empty string (empty content)
@@ -229,17 +217,10 @@ declare module '@docusaurus/plugin-content-blog' {
      * `assets.authorsImageUrls` on client side.
      */
     readonly authors: Author[];
-    /**
-     * Front matter, as-is.
-     */
+    /** Front matter, as-is. */
     readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
-    /**
-     * Tags, normalized.
-     */
-    readonly tags: readonly {
-      readonly label: string;
-      readonly permalink: string;
-    }[];
+    /** Tags, normalized. */
+    readonly tags: Tag[];
   };
   /**
    * @returns The edit URL that's directly plugged into metadata.
@@ -250,17 +231,11 @@ declare module '@docusaurus/plugin-content-blog' {
      * site path. Usually the same as `options.path` but can be localized
      */
     blogDirPath: string;
-    /**
-     * Path to this post file, relative to `blogDirPath`
-     */
+    /** Path to this post file, relative to `blogDirPath`. */
     blogPath: string;
-    /**
-     * @see {@link BlogPostMetadata.permalink}
-     */
+    /** @see {@link BlogPostMetadata.permalink} */
     permalink: string;
-    /**
-     * Locale name.
-     */
+    /** Locale name. */
     locale: string;
   }) => string | undefined;
 
@@ -325,7 +300,7 @@ declare module '@docusaurus/plugin-content-blog' {
   /**
    * Plugin options after normalization.
    */
-  export type PluginOptions = RemarkAndRehypePluginOptions & {
+  export type PluginOptions = MDXOptions & {
     /** Plugin ID. */
     id?: string;
     /**
@@ -432,25 +407,70 @@ declare module '@docusaurus/plugin-content-blog' {
     }
   >;
 
-  export type TagModule = {
-    /** Permalink of the tag's own page. */
-    permalink: string;
-    /** Name of the tag. */
-    name: string;
-    /** Number of posts with this tag. */
-    count: number;
-    /** The tags list page. */
-    allTagsPath: string;
-  };
-
   export type BlogSidebar = {
     title: string;
     items: {title: string; permalink: string}[];
   };
+
+  export type BlogContent = {
+    blogSidebarTitle: string;
+    blogPosts: BlogPost[];
+    blogListPaginated: BlogPaginated[];
+    blogTags: BlogTags;
+    blogTagsListPath: string;
+  };
+
+  export type BlogTags = {
+    [permalink: string]: BlogTag;
+  };
+
+  export type BlogTag = Tag & {
+    /** Blog post permalinks. */
+    items: string[];
+    pages: BlogPaginated[];
+  };
+
+  export type BlogPost = {
+    id: string;
+    metadata: BlogPostMetadata;
+    content: string;
+  };
+
+  export type BlogPaginatedMetadata = {
+    /** Title of the entire blog. */
+    readonly blogTitle: string;
+    /** Blog description. */
+    readonly blogDescription: string;
+    /** Permalink to the next list page. */
+    readonly nextPage?: string;
+    /** Permalink of the current page. */
+    readonly permalink: string;
+    /** Permalink to the previous list page. */
+    readonly previousPage?: string;
+    /** Index of the current page, 1-based. */
+    readonly page: number;
+    /** Posts displayed on each list page. */
+    readonly postsPerPage: number;
+    /** Total number of posts in the entire blog. */
+    readonly totalCount: number;
+    /** Total number of list pages. */
+    readonly totalPages: number;
+  };
+
+  export type BlogPaginated = {
+    metadata: BlogPaginatedMetadata;
+    /** Blog post permalinks. */
+    items: string[];
+  };
+
+  export default function pluginContentBlog(
+    context: LoadContext,
+    options: PluginOptions,
+  ): Promise<Plugin<BlogContent>>;
 }
 
 declare module '@theme/BlogPostPage' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {
     BlogPostFrontMatter,
     BlogPostMetadata,
@@ -469,24 +489,7 @@ declare module '@theme/BlogPostPage' {
     }
   >;
 
-  export type Content = {
-    // TODO remove this. `metadata.frontMatter` is preferred because it can be
-    // accessed in enhanced plugins
-    /** Same as `metadata.frontMatter` */
-    readonly frontMatter: FrontMatter;
-    /**
-     * Usually image assets that may be collocated like `./img/thumbnail.png`.
-     * The loader would also bundle these assets and the client should use these
-     * in priority.
-     */
-    readonly assets: Assets;
-    /** Metadata of the post. */
-    readonly metadata: Metadata;
-    /** A list of TOC items (headings). */
-    readonly toc: readonly TOCItem[];
-    /** Renders the actual MDX content. */
-    (): JSX.Element;
-  };
+  export type Content = LoadedMDXContent<FrontMatter, Metadata, Assets>;
 
   export interface Props {
     /** Blog sidebar. */
@@ -500,34 +503,16 @@ declare module '@theme/BlogPostPage' {
 
 declare module '@theme/BlogListPage' {
   import type {Content} from '@theme/BlogPostPage';
-  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
-
-  export type Metadata = {
-    /** Title of the entire blog. */
-    readonly blogTitle: string;
-    /** Blog description. */
-    readonly blogDescription: string;
-    /** Permalink to the next list page. */
-    readonly nextPage?: string;
-    /** Permalink of the current page. */
-    readonly permalink: string;
-    /** Permalink to the previous list page. */
-    readonly previousPage?: string;
-    /** Index of the current page, 1-based. */
-    readonly page: number;
-    /** Posts displayed on each list page. */
-    readonly postsPerPage: number;
-    /** Total number of posts in the entire blog. */
-    readonly totalCount: number;
-    /** Total number of list pages. */
-    readonly totalPages: number;
-  };
+  import type {
+    BlogSidebar,
+    BlogPaginatedMetadata,
+  } from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     /** Blog sidebar. */
     readonly sidebar: BlogSidebar;
     /** Metadata of the current listing page. */
-    readonly metadata: Metadata;
+    readonly metadata: BlogPaginatedMetadata;
     /**
      * Array of blog posts included on this page. Every post's metadata is also
      * available.
@@ -539,30 +524,34 @@ declare module '@theme/BlogListPage' {
 }
 
 declare module '@theme/BlogTagsListPage' {
-  import type {BlogSidebar, TagModule} from '@docusaurus/plugin-content-blog';
+  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
+  import type {TagsListItem} from '@docusaurus/utils';
 
   export interface Props {
     /** Blog sidebar. */
     readonly sidebar: BlogSidebar;
-    /** A map from tag names to the full tag module. */
-    readonly tags: Readonly<{[tagName: string]: TagModule}>;
+    /** All tags declared in this blog. */
+    readonly tags: TagsListItem[];
   }
 
   export default function BlogTagsListPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogTagsPostsPage' {
-  import type {BlogSidebar, TagModule} from '@docusaurus/plugin-content-blog';
+  import type {
+    BlogSidebar,
+    BlogPaginatedMetadata,
+  } from '@docusaurus/plugin-content-blog';
   import type {Content} from '@theme/BlogPostPage';
-  import type {Metadata} from '@theme/BlogListPage';
+  import type {TagModule} from '@docusaurus/utils';
 
   export interface Props {
     /** Blog sidebar. */
     readonly sidebar: BlogSidebar;
     /** Metadata of this tag. */
-    readonly metadata: TagModule;
+    readonly tag: TagModule;
     /** Looks exactly the same as the posts list page */
-    readonly listMetadata: Metadata;
+    readonly listMetadata: BlogPaginatedMetadata;
     /**
      * Array of blog posts included on this page. Every post's metadata is also
      * available.

package/src/remark/footnoteIDFixer.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 visit from 'unist-util-visit';
+import {simpleHash} from '@docusaurus/utils';
+import type {Transformer} from 'unified';
+import type {FootnoteReference, FootnoteDefinition} from 'mdast';
+
+/**
+ * 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 {
+  return (root, vfile) => {
+    const suffix = `-${simpleHash(vfile.path!, 6)}`;
+    visit(root, 'footnoteReference', (node: FootnoteReference) => {
+      node.identifier += suffix;
+    });
+    visit(root, 'footnoteDefinition', (node: FootnoteDefinition) => {
+      node.identifier += suffix;
+    });
+  };
+}

package/src/translations.ts

@@ -5,9 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {BlogContent, BlogPaginated} from './types';
-import type {TranslationFileContent, TranslationFiles} from '@docusaurus/types';
-import type {PluginOptions} from '@docusaurus/plugin-content-blog';
+import type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  BlogContent,
+  BlogPaginated,
+} from '@docusaurus/plugin-content-blog';
 
 function translateListPage(
   blogListPaginated: BlogPaginated[],
@@ -27,7 +30,7 @@ function translateListPage(
   });
 }
 
-export function getTranslationFiles(options: PluginOptions): TranslationFiles {
+export function getTranslationFiles(options: PluginOptions): TranslationFile[] {
   return [
     {
       path: 'options',
@@ -51,7 +54,7 @@ export function getTranslationFiles(options: PluginOptions): TranslationFiles {
 
 export function translateContent(
   content: BlogContent,
-  translationFiles: TranslationFiles,
+  translationFiles: TranslationFile[],
 ): BlogContent {
   const {content: optionsTranslations} = translationFiles[0]!;
   return {

package/src/types.ts

@@ -6,45 +6,9 @@
  */
 
 import type {BrokenMarkdownLink, ContentPaths} from '@docusaurus/utils';
-import type {BlogPostMetadata} from '@docusaurus/plugin-content-blog';
-import type {Metadata as BlogPaginatedMetadata} from '@theme/BlogListPage';
 
 export type BlogContentPaths = ContentPaths;
 
-export interface BlogContent {
-  blogSidebarTitle: string;
-  blogPosts: BlogPost[];
-  blogListPaginated: BlogPaginated[];
-  blogTags: BlogTags;
-  blogTagsListPath: string | null;
-}
-
-export interface BlogTags {
-  // TODO, the key is the tag slug/permalink
-  // This is due to legacy frontmatter: tags:
-  // [{label: "xyz", permalink: "/1"}, {label: "xyz", permalink: "/2"}]
-  // Soon we should forbid declaring permalink through frontmatter
-  [tagKey: string]: BlogTag;
-}
-
-export interface BlogTag {
-  name: string;
-  items: string[]; // blog post permalinks
-  permalink: string;
-  pages: BlogPaginated[];
-}
-
-export interface BlogPost {
-  id: string;
-  metadata: BlogPostMetadata;
-  content: string;
-}
-
-export interface BlogPaginated {
-  metadata: BlogPaginatedMetadata;
-  items: string[]; // blog post permalinks
-}
-
 export type BlogBrokenMarkdownLink = BrokenMarkdownLink<BlogContentPaths>;
 export type BlogMarkdownLoaderOptions = {
   siteDir: string;