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

package/lib/authors.js

@@ -52,9 +52,9 @@ function getFrontMatterAuthorLegacy(frontMatter) {
 function normalizeFrontMatterAuthors(frontMatterAuthors = []) {
     function normalizeAuthor(authorInput) {
         if (typeof authorInput === 'string') {
-            // Technically, we could allow users to provide an author's name here
-            // IMHO it's better to only support keys here
-            // Reason: a typo in a key would fallback to becoming a name and may end-up un-noticed
+            // 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;
@@ -97,7 +97,8 @@ function getBlogPostAuthors(params) {
     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?
+        // 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.`);

package/lib/blogUtils.d.ts

@@ -4,12 +4,24 @@
  * 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 } from './types';
+import type { BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions, BlogTags, BlogPaginated } from './types';
 import type { LoadContext } from '@docusaurus/types';
 import type { PluginOptions } from '@docusaurus/plugin-content-blog';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
 export declare function getSourceToPermalink(blogPosts: BlogPost[]): Record<string, string>;
-export declare function getBlogTags(blogPosts: BlogPost[]): BlogTags;
+export declare function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, }: {
+    blogPosts: BlogPost[];
+    basePageUrl: string;
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+}): BlogPaginated[];
+export declare function getBlogTags({ blogPosts, ...params }: {
+    blogPosts: BlogPost[];
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+}): BlogTags;
 declare type ParsedBlogFileName = {
     date: Date | undefined;
     text: string;

package/lib/blogUtils.js

@@ -6,12 +6,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.linkify = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.getSourceToPermalink = exports.truncate = void 0;
+exports.linkify = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.paginateBlogPosts = exports.getSourceToPermalink = exports.truncate = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const reading_time_1 = (0, tslib_1.__importDefault)(require("reading-time"));
-const lodash_1 = require("lodash");
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const blogFrontMatter_1 = require("./blogFrontMatter");
 const authors_1 = require("./authors");
@@ -21,19 +21,53 @@ function truncate(fileString, truncateMarker) {
 }
 exports.truncate = truncate;
 function getSourceToPermalink(blogPosts) {
-    return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(blogPosts, (item) => item.metadata.source), (v) => v.metadata.permalink);
+    return Object.fromEntries(blogPosts.map(({ metadata: { source, permalink } }) => [source, permalink]));
 }
 exports.getSourceToPermalink = getSourceToPermalink;
-function getBlogTags(blogPosts) {
+function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, }) {
+    const totalCount = blogPosts.length;
+    const postsPerPage = postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
+    const numberOfPages = Math.ceil(totalCount / postsPerPage);
+    const pages = [];
+    function permalink(page) {
+        return page > 0 ? `${basePageUrl}/page/${page + 1}` : basePageUrl;
+    }
+    for (let page = 0; page < numberOfPages; page += 1) {
+        pages.push({
+            items: blogPosts
+                .slice(page * postsPerPage, (page + 1) * postsPerPage)
+                .map((item) => item.id),
+            metadata: {
+                permalink: permalink(page),
+                page: page + 1,
+                postsPerPage,
+                totalPages: numberOfPages,
+                totalCount,
+                previousPage: page !== 0 ? permalink(page - 1) : null,
+                nextPage: page < numberOfPages - 1 ? permalink(page + 1) : null,
+                blogDescription,
+                blogTitle,
+            },
+        });
+    }
+    return pages;
+}
+exports.paginateBlogPosts = paginateBlogPosts;
+function getBlogTags({ blogPosts, ...params }) {
     const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
-    return (0, lodash_1.mapValues)(groups, (group) => ({
-        name: group.tag.label,
-        items: group.items.map((item) => item.id),
-        permalink: group.tag.permalink,
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagBlogPosts }) => ({
+        name: tag.label,
+        items: tagBlogPosts.map((item) => item.id),
+        permalink: tag.permalink,
+        pages: paginateBlogPosts({
+            blogPosts: tagBlogPosts,
+            basePageUrl: tag.permalink,
+            ...params,
+        }),
     }));
 }
 exports.getBlogTags = getBlogTags;
-const DATE_FILENAME_REGEX = /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
+const DATE_FILENAME_REGEX = /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(?:\/index)?.mdx?$/;
 function parseBlogFileName(blogSourceRelative) {
     const dateFilenameMatch = blogSourceRelative.match(DATE_FILENAME_REGEX);
     if (dateFilenameMatch) {
@@ -44,11 +78,9 @@ function parseBlogFileName(blogSourceRelative) {
         const slug = `/${slugDate}/${folder}${text}`;
         return { date, text, slug };
     }
-    else {
-        const text = blogSourceRelative.replace(/(\/index)?\.mdx?$/, '');
-        const slug = `/${text}`;
-        return { date: undefined, text, slug };
-    }
+    const text = blogSourceRelative.replace(/(?:\/index)?\.mdx?$/, '');
+    const slug = `/${text}`;
+    return { date: undefined, text, slug };
 }
 exports.parseBlogFileName = parseBlogFileName;
 function formatBlogPostDate(locale, date) {
@@ -60,8 +92,9 @@ function formatBlogPostDate(locale, date) {
             timeZone: 'UTC',
         }).format(date);
     }
-    catch (e) {
-        throw new Error(`Can't format blog post date "${date}"`);
+    catch (err) {
+        logger_1.default.error `Can't format blog post date "${String(date)}"`;
+        throw err;
     }
 }
 async function parseBlogPostMarkdownFile(blogSourceAbsolute) {
@@ -75,8 +108,9 @@ async function parseBlogPostMarkdownFile(blogSourceAbsolute) {
             frontMatter: (0, blogFrontMatter_1.validateBlogPostFrontMatter)(result.frontMatter),
         };
     }
-    catch (e) {
-        throw new Error(`Error while parsing blog post file ${blogSourceAbsolute}: "${e.message}".`);
+    catch (err) {
+        logger_1.default.error `Error while parsing blog post file path=${blogSourceAbsolute}.`;
+        throw err;
     }
 }
 const defaultReadingTime = ({ content, options }) => (0, reading_time_1.default)(content, options).minutes;
@@ -109,8 +143,17 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
         else if (parsedBlogFileName.date) {
             return parsedBlogFileName.date;
         }
-        // Fallback to file create time
-        return (await fs_extra_1.default.stat(blogSourceAbsolute)).birthtime;
+        try {
+            const result = (0, utils_1.getFileCommitDate)(blogSourceAbsolute, {
+                age: 'oldest',
+                includeAuthor: false,
+            });
+            return result.date;
+        }
+        catch (err) {
+            logger_1.default.error(err);
+            return (await fs_extra_1.default.stat(blogSourceAbsolute)).birthtime;
+        }
     }
     const date = await getDate();
     const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
@@ -174,7 +217,7 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
 }
 async function generateBlogPosts(contentPaths, context, options) {
     const { include, exclude } = options;
-    if (!fs_extra_1.default.existsSync(contentPaths.contentPath)) {
+    if (!(await fs_extra_1.default.pathExists(contentPaths.contentPath))) {
         return [];
     }
     const blogSourceFiles = await (0, utils_1.Globby)(include, {
@@ -189,9 +232,9 @@ async function generateBlogPosts(contentPaths, context, options) {
         try {
             return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, authorsMap);
         }
-        catch (e) {
-            logger_1.default.error `Processing of blog source file failed for path path=${blogSourceFile}.`;
-            throw e;
+        catch (err) {
+            logger_1.default.error `Processing of blog source file path=${blogSourceFile} failed.`;
+            throw err;
         }
     }))).filter(Boolean);
     blogPosts.sort((a, b) => b.metadata.date.getTime() - a.metadata.date.getTime());

package/lib/index.js

@@ -62,6 +62,7 @@ async function pluginContentBlog(context, options) {
                     blogListPaginated: [],
                     blogTags: {},
                     blogTagsListPath: null,
+                    blogTagsPaginated: [],
                 };
             }
             // Colocate next and prev metadata.
@@ -81,39 +82,20 @@ async function pluginContentBlog(context, options) {
                     };
                 }
             });
-            // Blog pagination routes.
-            // Example: `/blog`, `/blog/page/1`, `/blog/page/2`
-            const totalCount = blogPosts.length;
-            const postsPerPage = postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
-            const numberOfPages = Math.ceil(totalCount / postsPerPage);
             const baseBlogUrl = (0, utils_1.normalizeUrl)([baseUrl, routeBasePath]);
-            const blogListPaginated = [];
-            function blogPaginationPermalink(page) {
-                return page > 0
-                    ? (0, utils_1.normalizeUrl)([baseBlogUrl, `page/${page + 1}`])
-                    : baseBlogUrl;
-            }
-            for (let page = 0; page < numberOfPages; page += 1) {
-                blogListPaginated.push({
-                    metadata: {
-                        permalink: blogPaginationPermalink(page),
-                        page: page + 1,
-                        postsPerPage,
-                        totalPages: numberOfPages,
-                        totalCount,
-                        previousPage: page !== 0 ? blogPaginationPermalink(page - 1) : null,
-                        nextPage: page < numberOfPages - 1
-                            ? blogPaginationPermalink(page + 1)
-                            : null,
-                        blogDescription,
-                        blogTitle,
-                    },
-                    items: blogPosts
-                        .slice(page * postsPerPage, (page + 1) * postsPerPage)
-                        .map((item) => item.id),
-                });
-            }
-            const blogTags = (0, blogUtils_1.getBlogTags)(blogPosts);
+            const blogListPaginated = (0, blogUtils_1.paginateBlogPosts)({
+                blogPosts,
+                blogTitle,
+                blogDescription,
+                postsPerPageOption,
+                basePageUrl: baseBlogUrl,
+            });
+            const blogTags = (0, blogUtils_1.getBlogTags)({
+                blogPosts,
+                postsPerPageOption,
+                blogDescription,
+                blogTitle,
+            });
             const tagsPath = (0, utils_1.normalizeUrl)([baseBlogUrl, tagsBasePath]);
             const blogTagsListPath = Object.keys(blogTags).length > 0 ? tagsPath : null;
             return {
@@ -128,7 +110,7 @@ async function pluginContentBlog(context, options) {
             if (!blogContents) {
                 return;
             }
-            const { blogListComponent, blogPostComponent, blogTagsListComponent, blogTagsPostsComponent, routeBasePath, archiveBasePath, } = options;
+            const { blogListComponent, blogPostComponent, blogTagsListComponent, blogTagsPostsComponent, blogArchiveComponent, routeBasePath, archiveBasePath, } = options;
             const { addRoute, createData } = actions;
             const { blogSidebarTitle, blogPosts, blogListPaginated, blogTags, blogTagsListPath, } = blogContents;
             const blogItemsToMetadata = {};
@@ -145,7 +127,7 @@ async function pluginContentBlog(context, options) {
                 const archiveProp = await createData(`${(0, utils_1.docuHash)(archiveUrl)}.json`, JSON.stringify({ blogPosts }, null, 2));
                 addRoute({
                     path: archiveUrl,
-                    component: '@theme/BlogArchivePage',
+                    component: blogArchiveComponent,
                     exact: true,
                     modules: {
                         archive: aliasedSource(archiveProp),
@@ -193,7 +175,8 @@ async function pluginContentBlog(context, options) {
                     modules: {
                         sidebar: aliasedSource(sidebarProp),
                         items: items.map((postID) => 
-                        // To tell routes.js this is an import and not a nested object to recurse.
+                        // To tell routes.js this is an import and not a nested object
+                        // to recurse.
                         ({
                             content: {
                                 __import: true,
@@ -211,40 +194,46 @@ async function pluginContentBlog(context, options) {
             if (blogTagsListPath === null) {
                 return;
             }
-            const tagsModule = {};
-            await Promise.all(Object.keys(blogTags).map(async (tag) => {
-                const { name, items, permalink } = blogTags[tag];
-                // Refactor all this, see docs implementation
-                tagsModule[tag] = {
+            const tagsModule = Object.fromEntries(Object.entries(blogTags).map(([tagKey, tag]) => {
+                const tagModule = {
                     allTagsPath: blogTagsListPath,
-                    slug: tag,
-                    name,
-                    count: items.length,
-                    permalink,
+                    slug: tagKey,
+                    name: tag.name,
+                    count: tag.items.length,
+                    permalink: tag.permalink,
                 };
-                const tagsMetadataPath = await createData(`${(0, utils_1.docuHash)(permalink)}.json`, JSON.stringify(tagsModule[tag], null, 2));
-                addRoute({
-                    path: permalink,
-                    component: blogTagsPostsComponent,
-                    exact: true,
-                    modules: {
-                        sidebar: aliasedSource(sidebarProp),
-                        items: items.map((postID) => {
-                            const metadata = blogItemsToMetadata[postID];
-                            return {
-                                content: {
-                                    __import: true,
-                                    path: metadata.source,
-                                    query: {
-                                        truncated: true,
-                                    },
-                                },
-                            };
-                        }),
-                        metadata: aliasedSource(tagsMetadataPath),
-                    },
-                });
+                return [tag.name, tagModule];
             }));
+            async function createTagRoutes(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 listMetadataPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}-list.json`, JSON.stringify(metadata, null, 2));
+                    addRoute({
+                        path: metadata.permalink,
+                        component: blogTagsPostsComponent,
+                        exact: true,
+                        modules: {
+                            sidebar: aliasedSource(sidebarProp),
+                            items: items.map((postID) => {
+                                const blogPostMetadata = blogItemsToMetadata[postID];
+                                return {
+                                    content: {
+                                        __import: true,
+                                        path: blogPostMetadata.source,
+                                        query: {
+                                            truncated: true,
+                                        },
+                                    },
+                                };
+                            }),
+                            metadata: aliasedSource(tagsMetadataPath),
+                            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));
@@ -286,7 +275,7 @@ async function pluginContentBlog(context, options) {
                 module: {
                     rules: [
                         {
-                            test: /(\.mdx?)$/,
+                            test: /\.mdx?$/i,
                             include: contentDirs
                                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                                 .map(utils_1.addTrailingPathSeparator),
@@ -311,7 +300,8 @@ async function pluginContentBlog(context, options) {
                                         // For blog posts a title in markdown is always removed
                                         // Blog posts title are rendered separately
                                         removeContentTitle: true,
-                                        // Assets allow to convert some relative images paths to require() calls
+                                        // Assets allow to convert some relative images paths to
+                                        // require() calls
                                         createAssets: ({ frontMatter, metadata, }) => ({
                                             image: frontMatter.image,
                                             authorsImageUrls: metadata.authors.map((author) => author.imageURL),

package/lib/pluginOptionSchema.js

@@ -14,7 +14,7 @@ exports.DEFAULT_OPTIONS = {
     beforeDefaultRehypePlugins: [],
     beforeDefaultRemarkPlugins: [],
     admonitions: {},
-    truncateMarker: /<!--\s*(truncate)\s*-->/,
+    truncateMarker: /<!--\s*truncate\s*-->/,
     rehypePlugins: [],
     remarkPlugins: [],
     showReadingTime: true,
@@ -22,6 +22,7 @@ exports.DEFAULT_OPTIONS = {
     blogTagsListComponent: '@theme/BlogTagsListPage',
     blogPostComponent: '@theme/BlogPostPage',
     blogListComponent: '@theme/BlogListPage',
+    blogArchiveComponent: '@theme/BlogArchivePage',
     blogDescription: 'Blog',
     blogTitle: 'Blog',
     blogSidebarCount: 5,
@@ -57,6 +58,7 @@ exports.PluginOptionSchema = utils_validation_1.Joi.object({
     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('')

package/lib/types.d.ts

@@ -16,12 +16,13 @@ export interface BlogContent {
     blogTagsListPath: string | null;
 }
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.16",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -18,24 +18,24 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15",
-    "@docusaurus/logger": "2.0.0-beta.15",
-    "@docusaurus/mdx-loader": "2.0.0-beta.15",
-    "@docusaurus/utils": "2.0.0-beta.15",
-    "@docusaurus/utils-common": "2.0.0-beta.15",
-    "@docusaurus/utils-validation": "2.0.0-beta.15",
+    "@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",
     "cheerio": "^1.0.0-rc.10",
     "feed": "^4.2.2",
-    "fs-extra": "^10.0.0",
-    "lodash": "^4.17.20",
+    "fs-extra": "^10.0.1",
+    "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
     "remark-admonitions": "^1.2.1",
     "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.61.0"
+    "webpack": "^5.69.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.15",
+    "@docusaurus/types": "2.0.0-beta.16",
     "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
@@ -45,5 +45,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/authors.ts

@@ -83,9 +83,9 @@ function normalizeFrontMatterAuthors(
     authorInput: string | BlogPostFrontMatterAuthor,
   ): BlogPostFrontMatterAuthor {
     if (typeof authorInput === 'string') {
-      // Technically, we could allow users to provide an author's name here
-      // IMHO it's better to only support keys here
-      // Reason: a typo in a key would fallback to becoming a name and may end-up un-noticed
+      // 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;
@@ -137,7 +137,8 @@ export function getBlogPostAuthors(params: AuthorsParam): Author[] {
   const authors = getFrontMatterAuthors(params);
 
   if (authorLegacy) {
-    // Technically, we could allow mixing legacy/authors front matter, but do we really want to?
+    // 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.

package/src/blogUtils.ts

@@ -8,12 +8,13 @@
 import fs from 'fs-extra';
 import path from 'path';
 import readingTime from 'reading-time';
-import {keyBy, mapValues} from 'lodash';
+import _ from 'lodash';
 import type {
   BlogPost,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   BlogTags,
+  BlogPaginated,
 } from './types';
 import {
   parseMarkdownString,
@@ -26,6 +27,7 @@ import {
   Globby,
   normalizeFrontMatterTags,
   groupTaggedItems,
+  getFileCommitDate,
   getContentPathList,
 } from '@docusaurus/utils';
 import type {LoadContext} from '@docusaurus/types';
@@ -44,26 +46,85 @@ export function truncate(fileString: string, truncateMarker: RegExp): string {
 export function getSourceToPermalink(
   blogPosts: BlogPost[],
 ): Record<string, string> {
-  return mapValues(
-    keyBy(blogPosts, (item) => item.metadata.source),
-    (v) => v.metadata.permalink,
+  return Object.fromEntries(
+    blogPosts.map(({metadata: {source, permalink}}) => [source, permalink]),
   );
 }
 
-export function getBlogTags(blogPosts: BlogPost[]): BlogTags {
+export function paginateBlogPosts({
+  blogPosts,
+  basePageUrl,
+  blogTitle,
+  blogDescription,
+  postsPerPageOption,
+}: {
+  blogPosts: BlogPost[];
+  basePageUrl: string;
+  blogTitle: string;
+  blogDescription: string;
+  postsPerPageOption: number | 'ALL';
+}): BlogPaginated[] {
+  const totalCount = blogPosts.length;
+  const postsPerPage =
+    postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
+  const numberOfPages = Math.ceil(totalCount / postsPerPage);
+
+  const pages: BlogPaginated[] = [];
+
+  function permalink(page: number) {
+    return page > 0 ? `${basePageUrl}/page/${page + 1}` : basePageUrl;
+  }
+
+  for (let page = 0; page < numberOfPages; page += 1) {
+    pages.push({
+      items: blogPosts
+        .slice(page * postsPerPage, (page + 1) * postsPerPage)
+        .map((item) => item.id),
+      metadata: {
+        permalink: permalink(page),
+        page: page + 1,
+        postsPerPage,
+        totalPages: numberOfPages,
+        totalCount,
+        previousPage: page !== 0 ? permalink(page - 1) : null,
+        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : null,
+        blogDescription,
+        blogTitle,
+      },
+    });
+  }
+
+  return pages;
+}
+
+export function getBlogTags({
+  blogPosts,
+  ...params
+}: {
+  blogPosts: BlogPost[];
+  blogTitle: string;
+  blogDescription: string;
+  postsPerPageOption: number | 'ALL';
+}): BlogTags {
   const groups = groupTaggedItems(
     blogPosts,
     (blogPost) => blogPost.metadata.tags,
   );
-  return mapValues(groups, (group) => ({
-    name: group.tag.label,
-    items: group.items.map((item) => item.id),
-    permalink: group.tag.permalink,
+
+  return _.mapValues(groups, ({tag, items: tagBlogPosts}) => ({
+    name: tag.label,
+    items: tagBlogPosts.map((item) => item.id),
+    permalink: tag.permalink,
+    pages: paginateBlogPosts({
+      blogPosts: tagBlogPosts,
+      basePageUrl: tag.permalink,
+      ...params,
+    }),
   }));
 }
 
 const DATE_FILENAME_REGEX =
-  /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
+  /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(?:\/index)?.mdx?$/;
 
 type ParsedBlogFileName = {
   date: Date | undefined;
@@ -82,11 +143,10 @@ export function parseBlogFileName(
     const slugDate = dateString.replace(/-/g, '/');
     const slug = `/${slugDate}/${folder}${text}`;
     return {date, text, slug};
-  } else {
-    const text = blogSourceRelative.replace(/(\/index)?\.mdx?$/, '');
-    const slug = `/${text}`;
-    return {date: undefined, text, slug};
   }
+  const text = blogSourceRelative.replace(/(?:\/index)?\.mdx?$/, '');
+  const slug = `/${text}`;
+  return {date: undefined, text, slug};
 }
 
 function formatBlogPostDate(locale: string, date: Date): string {
@@ -97,8 +157,9 @@ function formatBlogPostDate(locale: string, date: Date): string {
       year: 'numeric',
       timeZone: 'UTC',
     }).format(date);
-  } catch (e) {
-    throw new Error(`Can't format blog post date "${date}"`);
+  } catch (err) {
+    logger.error`Can't format blog post date "${String(date)}"`;
+    throw err;
   }
 }
 
@@ -112,12 +173,9 @@ async function parseBlogPostMarkdownFile(blogSourceAbsolute: string) {
       ...result,
       frontMatter: validateBlogPostFrontMatter(result.frontMatter),
     };
-  } catch (e) {
-    throw new Error(
-      `Error while parsing blog post file ${blogSourceAbsolute}: "${
-        (e as Error).message
-      }".`,
-    );
+  } catch (err) {
+    logger.error`Error while parsing blog post file path=${blogSourceAbsolute}.`;
+    throw err;
   }
 }
 
@@ -179,8 +237,17 @@ async function processBlogSourceFile(
     } else if (parsedBlogFileName.date) {
       return parsedBlogFileName.date;
     }
-    // Fallback to file create time
-    return (await fs.stat(blogSourceAbsolute)).birthtime;
+
+    try {
+      const result = getFileCommitDate(blogSourceAbsolute, {
+        age: 'oldest',
+        includeAuthor: false,
+      });
+      return result.date;
+    } catch (err) {
+      logger.error(err);
+      return (await fs.stat(blogSourceAbsolute)).birthtime;
+    }
   }
 
   const date = await getDate();
@@ -263,7 +330,7 @@ export async function generateBlogPosts(
 ): Promise<BlogPost[]> {
   const {include, exclude} = options;
 
-  if (!fs.existsSync(contentPaths.contentPath)) {
+  if (!(await fs.pathExists(contentPaths.contentPath))) {
     return [];
   }
 
@@ -288,9 +355,9 @@ export async function generateBlogPosts(
             options,
             authorsMap,
           );
-        } catch (e) {
-          logger.error`Processing of blog source file failed for path path=${blogSourceFile}.`;
-          throw e;
+        } catch (err) {
+          logger.error`Processing of blog source file path=${blogSourceFile} failed.`;
+          throw err;
         }
       }),
     )

package/src/index.ts

@@ -23,6 +23,7 @@ import {
 import {translateContent, getTranslationFiles} from './translations';
 
 import type {
+  BlogTag,
   BlogTags,
   BlogContent,
   BlogItemsToMetadata,
@@ -31,21 +32,21 @@ import type {
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   MetaData,
+  TagModule,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
 import type {
   LoadContext,
-  ConfigureWebpackUtils,
   Plugin,
   HtmlTags,
   OptionValidationContext,
   ValidationResult,
 } from '@docusaurus/types';
-import type {Configuration} from 'webpack';
 import {
   generateBlogPosts,
   getSourceToPermalink,
   getBlogTags,
+  paginateBlogPosts,
 } from './blogUtils';
 import {createBlogFeedFiles} from './feed';
 import type {
@@ -134,6 +135,7 @@ export default async function pluginContentBlog(
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath: null,
+          blogTagsPaginated: [],
         };
       }
 
@@ -157,45 +159,22 @@ export default async function pluginContentBlog(
         }
       });
 
-      // Blog pagination routes.
-      // Example: `/blog`, `/blog/page/1`, `/blog/page/2`
-      const totalCount = blogPosts.length;
-      const postsPerPage =
-        postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
-      const numberOfPages = Math.ceil(totalCount / postsPerPage);
       const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
 
-      const blogListPaginated: BlogPaginated[] = [];
-
-      function blogPaginationPermalink(page: number) {
-        return page > 0
-          ? normalizeUrl([baseBlogUrl, `page/${page + 1}`])
-          : baseBlogUrl;
-      }
-
-      for (let page = 0; page < numberOfPages; page += 1) {
-        blogListPaginated.push({
-          metadata: {
-            permalink: blogPaginationPermalink(page),
-            page: page + 1,
-            postsPerPage,
-            totalPages: numberOfPages,
-            totalCount,
-            previousPage: page !== 0 ? blogPaginationPermalink(page - 1) : null,
-            nextPage:
-              page < numberOfPages - 1
-                ? blogPaginationPermalink(page + 1)
-                : null,
-            blogDescription,
-            blogTitle,
-          },
-          items: blogPosts
-            .slice(page * postsPerPage, (page + 1) * postsPerPage)
-            .map((item) => item.id),
-        });
-      }
+      const blogListPaginated: BlogPaginated[] = paginateBlogPosts({
+        blogPosts,
+        blogTitle,
+        blogDescription,
+        postsPerPageOption,
+        basePageUrl: baseBlogUrl,
+      });
 
-      const blogTags: BlogTags = getBlogTags(blogPosts);
+      const blogTags: BlogTags = getBlogTags({
+        blogPosts,
+        postsPerPageOption,
+        blogDescription,
+        blogTitle,
+      });
 
       const tagsPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
 
@@ -221,6 +200,7 @@ export default async function pluginContentBlog(
         blogPostComponent,
         blogTagsListComponent,
         blogTagsPostsComponent,
+        blogArchiveComponent,
         routeBasePath,
         archiveBasePath,
       } = options;
@@ -254,7 +234,7 @@ export default async function pluginContentBlog(
         );
         addRoute({
           path: archiveUrl,
-          component: '@theme/BlogArchivePage',
+          component: blogArchiveComponent,
           exact: true,
           modules: {
             archive: aliasedSource(archiveProp),
@@ -322,7 +302,8 @@ export default async function pluginContentBlog(
             modules: {
               sidebar: aliasedSource(sidebarProp),
               items: items.map((postID) =>
-                // To tell routes.js this is an import and not a nested object to recurse.
+                // To tell routes.js this is an import and not a nested object
+                // to recurse.
                 ({
                   content: {
                     __import: true,
@@ -344,50 +325,61 @@ export default async function pluginContentBlog(
         return;
       }
 
-      const tagsModule: TagsModule = {};
-
-      await Promise.all(
-        Object.keys(blogTags).map(async (tag) => {
-          const {name, items, permalink} = blogTags[tag];
-
-          // Refactor all this, see docs implementation
-          tagsModule[tag] = {
+      const tagsModule: TagsModule = Object.fromEntries(
+        Object.entries(blogTags).map(([tagKey, tag]) => {
+          const tagModule: TagModule = {
             allTagsPath: blogTagsListPath,
-            slug: tag,
-            name,
-            count: items.length,
-            permalink,
+            slug: tagKey,
+            name: tag.name,
+            count: tag.items.length,
+            permalink: tag.permalink,
           };
-
-          const tagsMetadataPath = await createData(
-            `${docuHash(permalink)}.json`,
-            JSON.stringify(tagsModule[tag], null, 2),
-          );
-
-          addRoute({
-            path: permalink,
-            component: blogTagsPostsComponent,
-            exact: true,
-            modules: {
-              sidebar: aliasedSource(sidebarProp),
-              items: items.map((postID) => {
-                const metadata = blogItemsToMetadata[postID];
-                return {
-                  content: {
-                    __import: true,
-                    path: metadata.source,
-                    query: {
-                      truncated: true,
-                    },
-                  },
-                };
-              }),
-              metadata: aliasedSource(tagsMetadataPath),
-            },
-          });
+          return [tag.name, tagModule];
         }),
       );
 
+      async function createTagRoutes(tag: BlogTag): Promise<void> {
+        await Promise.all(
+          tag.pages.map(async (blogPaginated) => {
+            const {metadata, items} = blogPaginated;
+            const tagsMetadataPath = await createData(
+              `${docuHash(metadata.permalink)}.json`,
+              JSON.stringify(tagsModule[tag.name], null, 2),
+            );
+
+            const listMetadataPath = await createData(
+              `${docuHash(metadata.permalink)}-list.json`,
+              JSON.stringify(metadata, null, 2),
+            );
+
+            addRoute({
+              path: metadata.permalink,
+              component: blogTagsPostsComponent,
+              exact: true,
+              modules: {
+                sidebar: aliasedSource(sidebarProp),
+                items: items.map((postID) => {
+                  const blogPostMetadata = blogItemsToMetadata[postID];
+                  return {
+                    content: {
+                      __import: true,
+                      path: blogPostMetadata.source,
+                      query: {
+                        truncated: true,
+                      },
+                    },
+                  };
+                }),
+                metadata: aliasedSource(tagsMetadataPath),
+                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(
@@ -411,12 +403,7 @@ export default async function pluginContentBlog(
       return translateContent(content, translationFiles);
     },
 
-    configureWebpack(
-      _config: Configuration,
-      isServer: boolean,
-      {getJSLoader}: ConfigureWebpackUtils,
-      content,
-    ) {
+    configureWebpack(_config, isServer, {getJSLoader}, content) {
       const {
         rehypePlugins,
         remarkPlugins,
@@ -451,7 +438,7 @@ export default async function pluginContentBlog(
         module: {
           rules: [
             {
-              test: /(\.mdx?)$/,
+              test: /\.mdx?$/i,
               include: contentDirs
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
@@ -485,7 +472,8 @@ export default async function pluginContentBlog(
                     // Blog posts title are rendered separately
                     removeContentTitle: true,
 
-                    // Assets allow to convert some relative images paths to require() calls
+                    // Assets allow to convert some relative images paths to
+                    // require() calls
                     createAssets: ({
                       frontMatter,
                       metadata,

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

@@ -120,6 +120,7 @@ declare module '@docusaurus/plugin-content-blog' {
     blogPostComponent: string;
     blogTagsListComponent: string;
     blogTagsPostsComponent: string;
+    blogArchiveComponent: string;
     blogTitle: string;
     blogDescription: string;
     blogSidebarCount: number | 'ALL';
@@ -147,21 +148,6 @@ declare module '@docusaurus/plugin-content-blog' {
   >;
 }
 
-declare module '@theme/BlogSidebar' {
-  export type BlogSidebarItem = {title: string; permalink: string};
-  export type BlogSidebar = {
-    title: string;
-    items: BlogSidebarItem[];
-  };
-
-  export interface Props {
-    readonly sidebar: BlogSidebar;
-  }
-
-  const BlogSidebar: (props: Props) => JSX.Element;
-  export default BlogSidebar;
-}
-
 declare module '@theme/BlogPostPage' {
   import type {BlogSidebar} from '@theme/BlogSidebar';
   import type {TOCItem} from '@docusaurus/types';
@@ -205,8 +191,7 @@ declare module '@theme/BlogPostPage' {
     readonly content: Content;
   }
 
-  const BlogPostPage: (props: Props) => JSX.Element;
-  export default BlogPostPage;
+  export default function BlogPostPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogListPage' {
@@ -231,8 +216,7 @@ declare module '@theme/BlogListPage' {
     readonly items: readonly {readonly content: Content}[];
   }
 
-  const BlogListPage: (props: Props) => JSX.Element;
-  export default BlogListPage;
+  export default function BlogListPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogTagsListPage' {
@@ -251,23 +235,23 @@ declare module '@theme/BlogTagsListPage' {
     readonly tags: Readonly<Record<string, Tag>>;
   }
 
-  const BlogTagsListPage: (props: Props) => JSX.Element;
-  export default BlogTagsListPage;
+  export default function BlogTagsListPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogTagsPostsPage' {
   import type {BlogSidebar} from '@theme/BlogSidebar';
   import type {Tag} from '@theme/BlogTagsListPage';
   import type {Content} from '@theme/BlogPostPage';
+  import type {Metadata} from '@theme/BlogListPage';
 
   export interface Props {
     readonly sidebar: BlogSidebar;
     readonly metadata: Tag;
+    readonly listMetadata: Metadata;
     readonly items: readonly {readonly content: Content}[];
   }
 
-  const BlogTagsPostsPage: (props: Props) => JSX.Element;
-  export default BlogTagsPostsPage;
+  export default function BlogTagsPostsPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogArchivePage' {

package/src/pluginOptionSchema.ts

@@ -20,7 +20,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: {},
-  truncateMarker: /<!--\s*(truncate)\s*-->/,
+  truncateMarker: /<!--\s*truncate\s*-->/,
   rehypePlugins: [],
   remarkPlugins: [],
   showReadingTime: true,
@@ -28,6 +28,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   blogTagsListComponent: '@theme/BlogTagsListPage',
   blogPostComponent: '@theme/BlogPostPage',
   blogListComponent: '@theme/BlogListPage',
+  blogArchiveComponent: '@theme/BlogArchivePage',
   blogDescription: 'Blog',
   blogTitle: 'Blog',
   blogSidebarCount: 5,
@@ -68,6 +69,9 @@ export const PluginOptionSchema = Joi.object<PluginOptions>({
   blogTagsPostsComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogTagsPostsComponent,
   ),
+  blogArchiveComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogArchiveComponent,
+  ),
   blogTitle: Joi.string().allow('').default(DEFAULT_OPTIONS.blogTitle),
   blogDescription: Joi.string()
     .allow('')

package/src/types.ts

@@ -26,13 +26,18 @@ export interface BlogContent {
 }
 
 export interface BlogTags {
-  [key: string]: BlogTag;
+  // 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[];
+  items: string[]; // blog post permalinks
   permalink: string;
+  pages: BlogPaginated[];
 }
 
 export interface BlogPost {
@@ -55,7 +60,7 @@ export interface BlogPaginatedMetadata {
 
 export interface BlogPaginated {
   metadata: BlogPaginatedMetadata;
-  items: string[];
+  items: string[]; // blog post permalinks
 }
 
 export interface MetaData {