@docusaurus/plugin-content-blog 0.0.0-4543 → 0.0.0-4548

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,7 +6,7 @@
  * 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"));
@@ -24,13 +24,50 @@ function getSourceToPermalink(blogPosts) {
     return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(blogPosts, (item) => item.metadata.source), (v) => v.metadata.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 (0, lodash_1.mapValues)(groups, (group) => {
+        const { tag, items: tagBlogPosts } = group;
+        return {
+            name: tag.label,
+            items: tagBlogPosts.map((item) => item.id),
+            permalink: tag.permalink,
+            pages: paginateBlogPosts({
+                blogPosts: tagBlogPosts,
+                basePageUrl: group.tag.permalink,
+                ...params,
+            }),
+        };
+    });
 }
 exports.getBlogTags = getBlogTags;
 const DATE_FILENAME_REGEX = /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(?:\/index)?.mdx?$/;

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 {
@@ -212,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));

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": "0.0.0-4543",
+  "version": "0.0.0-4548",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -18,12 +18,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4543",
-    "@docusaurus/logger": "0.0.0-4543",
-    "@docusaurus/mdx-loader": "0.0.0-4543",
-    "@docusaurus/utils": "0.0.0-4543",
-    "@docusaurus/utils-common": "0.0.0-4543",
-    "@docusaurus/utils-validation": "0.0.0-4543",
+    "@docusaurus/core": "0.0.0-4548",
+    "@docusaurus/logger": "0.0.0-4548",
+    "@docusaurus/mdx-loader": "0.0.0-4548",
+    "@docusaurus/utils": "0.0.0-4548",
+    "@docusaurus/utils-common": "0.0.0-4548",
+    "@docusaurus/utils-validation": "0.0.0-4548",
     "cheerio": "^1.0.0-rc.10",
     "feed": "^4.2.2",
     "fs-extra": "^10.0.0",
@@ -35,7 +35,7 @@
     "webpack": "^5.68.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "0.0.0-4543",
+    "@docusaurus/types": "0.0.0-4548",
     "escape-string-regexp": "^4.0.0"
   },
   "peerDependencies": {
@@ -46,5 +46,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "b7bf9036b8c17fd2b4c4f4fc00480e293d851b85"
+  "gitHead": "ded4ed41aad85b798c178034ae43f028162ef747"
 }

package/src/blogUtils.ts

@@ -14,6 +14,7 @@ import type {
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   BlogTags,
+  BlogPaginated,
 } from './types';
 import {
   parseMarkdownString,
@@ -50,16 +51,79 @@ export function getSourceToPermalink(
   );
 }
 
-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, (group) => {
+    const {tag, items: tagBlogPosts} = group;
+    return {
+      name: tag.label,
+      items: tagBlogPosts.map((item) => item.id),
+      permalink: tag.permalink,
+      pages: paginateBlogPosts({
+        blogPosts: tagBlogPosts,
+        basePageUrl: group.tag.permalink,
+        ...params,
+      }),
+    };
+  });
 }
 
 const DATE_FILENAME_REGEX =

package/src/index.ts

@@ -23,6 +23,7 @@ import {
 import {translateContent, getTranslationFiles} from './translations';
 
 import type {
+  BlogTag,
   BlogTags,
   BlogContent,
   BlogItemsToMetadata,
@@ -31,6 +32,7 @@ import type {
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   MetaData,
+  TagModule,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
 import type {
@@ -46,6 +48,7 @@ import {
   generateBlogPosts,
   getSourceToPermalink,
   getBlogTags,
+  paginateBlogPosts,
 } from './blogUtils';
 import {createBlogFeedFiles} from './feed';
 import type {
@@ -134,6 +137,7 @@ export default async function pluginContentBlog(
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath: null,
+          blogTagsPaginated: [],
         };
       }
 
@@ -157,45 +161,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]);
 
@@ -345,50 +326,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(

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

@@ -259,10 +259,12 @@ 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}[];
   }
 

package/src/types.ts

@@ -26,13 +26,17 @@ 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 +59,7 @@ export interface BlogPaginatedMetadata {
 
 export interface BlogPaginated {
   metadata: BlogPaginatedMetadata;
-  items: string[];
+  items: string[]; // blog post permalinks
 }
 
 export interface MetaData {