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

package/src/index.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import fs from 'fs-extra';
 import path from 'path';
 import admonitions from 'remark-admonitions';
 import {
@@ -16,46 +15,50 @@ import {
   reportMessage,
   posixPath,
   addTrailingPathSeparator,
-} from '@docusaurus/utils';
-import {
-  STATIC_DIR_NAME,
+  createAbsoluteFilePathMatcher,
+  getContentPathList,
+  getDataFilePath,
   DEFAULT_PLUGIN_ID,
-} from '@docusaurus/core/lib/constants';
-import {flatten, take, kebabCase} from 'lodash';
+} from '@docusaurus/utils';
+import {translateContent, getTranslationFiles} from './translations';
 
-import {
-  PluginOptions,
+import type {
+  BlogTag,
   BlogTags,
   BlogContent,
   BlogItemsToMetadata,
   TagsModule,
   BlogPaginated,
-  BlogPost,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
+  MetaData,
+  TagModule,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
-import {
+import type {
   LoadContext,
-  ConfigureWebpackUtils,
-  Props,
   Plugin,
   HtmlTags,
   OptionValidationContext,
   ValidationResult,
 } from '@docusaurus/types';
-import {Configuration} from 'webpack';
 import {
-  generateBlogFeed,
   generateBlogPosts,
-  getContentPathList,
   getSourceToPermalink,
+  getBlogTags,
+  paginateBlogPosts,
 } from './blogUtils';
+import {createBlogFeedFiles} from './feed';
+import type {
+  PluginOptions,
+  BlogPostFrontMatter,
+  Assets,
+} from '@docusaurus/plugin-content-blog';
 
-export default function pluginContentBlog(
+export default async function pluginContentBlog(
   context: LoadContext,
   options: PluginOptions,
-): Plugin<BlogContent> {
+): Promise<Plugin<BlogContent>> {
   if (options.admonitions) {
     options.remarkPlugins = options.remarkPlugins.concat([
       [admonitions, options.admonitions],
@@ -64,10 +67,11 @@ export default function pluginContentBlog(
 
   const {
     siteDir,
-    siteConfig: {onBrokenMarkdownLinks},
+    siteConfig,
     generatedFilesDir,
     i18n: {currentLocale},
   } = context;
+  const {onBrokenMarkdownLinks, baseUrl} = siteConfig;
 
   const contentPaths: BlogContentPaths = {
     contentPath: path.resolve(siteDir, options.path),
@@ -88,44 +92,50 @@ export default function pluginContentBlog(
   const aliasedSource = (source: string) =>
     `~blog/${posixPath(path.relative(pluginDataDirRoot, source))}`;
 
+  const authorsMapFilePath = await getDataFilePath({
+    filePath: options.authorsMapPath,
+    contentPaths,
+  });
+
   return {
     name: 'docusaurus-plugin-content-blog',
 
     getPathsToWatch() {
-      const {include = []} = options;
-      return flatten(
-        getContentPathList(contentPaths).map((contentPath) => {
-          return include.map((pattern) => `${contentPath}/${pattern}`);
-        }),
+      const {include} = options;
+      const contentMarkdownGlobs = getContentPathList(contentPaths).flatMap(
+        (contentPath) => include.map((pattern) => `${contentPath}/${pattern}`),
       );
-    },
-
-    getClientModules() {
-      const modules = [];
 
-      if (options.admonitions) {
-        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
-      }
+      return [authorsMapFilePath, ...contentMarkdownGlobs].filter(
+        Boolean,
+      ) as string[];
+    },
 
-      return modules;
+    async getTranslationFiles() {
+      return getTranslationFiles(options);
     },
 
     // Fetches blog contents and returns metadata for the necessary routes.
     async loadContent() {
-      const {postsPerPage, routeBasePath} = options;
+      const {
+        postsPerPage: postsPerPageOption,
+        routeBasePath,
+        tagsBasePath,
+        blogDescription,
+        blogTitle,
+        blogSidebarTitle,
+      } = options;
 
-      const blogPosts: BlogPost[] = await generateBlogPosts(
-        contentPaths,
-        context,
-        options,
-      );
+      const blogPosts = await generateBlogPosts(contentPaths, context, options);
 
       if (!blogPosts.length) {
         return {
+          blogSidebarTitle,
           blogPosts: [],
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath: null,
+          blogTagsPaginated: [],
         };
       }
 
@@ -149,85 +159,30 @@ export default function pluginContentBlog(
         }
       });
 
-      // Blog pagination routes.
-      // Example: `/blog`, `/blog/page/1`, `/blog/page/2`
-      const totalCount = blogPosts.length;
-      const numberOfPages = Math.ceil(totalCount / postsPerPage);
-      const {
-        siteConfig: {baseUrl = ''},
-      } = context;
-      const basePageUrl = normalizeUrl([baseUrl, routeBasePath]);
-
-      const blogListPaginated: BlogPaginated[] = [];
+      const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
 
-      function blogPaginationPermalink(page: number) {
-        return page > 0
-          ? normalizeUrl([basePageUrl, `page/${page + 1}`])
-          : basePageUrl;
-      }
-
-      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: options.blogDescription,
-            blogTitle: options.blogTitle,
-          },
-          items: blogPosts
-            .slice(page * postsPerPage, (page + 1) * postsPerPage)
-            .map((item) => item.id),
-        });
-      }
-
-      const blogTags: BlogTags = {};
-      const tagsPath = normalizeUrl([basePageUrl, 'tags']);
-      blogPosts.forEach((blogPost) => {
-        const {tags} = blogPost.metadata;
-        if (!tags || tags.length === 0) {
-          // TODO: Extract tags out into a separate plugin.
-          // eslint-disable-next-line no-param-reassign
-          blogPost.metadata.tags = [];
-          return;
-        }
+      const blogListPaginated: BlogPaginated[] = paginateBlogPosts({
+        blogPosts,
+        blogTitle,
+        blogDescription,
+        postsPerPageOption,
+        basePageUrl: baseBlogUrl,
+      });
 
-        // eslint-disable-next-line no-param-reassign
-        blogPost.metadata.tags = tags.map((tag) => {
-          if (typeof tag === 'string') {
-            const normalizedTag = kebabCase(tag);
-            const permalink = normalizeUrl([tagsPath, normalizedTag]);
-            if (!blogTags[normalizedTag]) {
-              blogTags[normalizedTag] = {
-                // Will only use the name of the first occurrence of the tag.
-                name: tag.toLowerCase(),
-                items: [],
-                permalink,
-              };
-            }
-
-            blogTags[normalizedTag].items.push(blogPost.id);
-
-            return {
-              label: tag,
-              permalink,
-            };
-          }
-          return tag;
-        });
+      const blogTags: BlogTags = getBlogTags({
+        blogPosts,
+        postsPerPageOption,
+        blogDescription,
+        blogTitle,
       });
 
+      const tagsPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
+
       const blogTagsListPath =
         Object.keys(blogTags).length > 0 ? tagsPath : null;
 
       return {
+        blogSidebarTitle,
         blogPosts,
         blogListPaginated,
         blogTags,
@@ -245,10 +200,14 @@ export default function pluginContentBlog(
         blogPostComponent,
         blogTagsListComponent,
         blogTagsPostsComponent,
+        blogArchiveComponent,
+        routeBasePath,
+        archiveBasePath,
       } = options;
 
       const {addRoute, createData} = actions;
       const {
+        blogSidebarTitle,
         blogPosts,
         blogListPaginated,
         blogTags,
@@ -260,7 +219,28 @@ export default function pluginContentBlog(
       const sidebarBlogPosts =
         options.blogSidebarCount === 'ALL'
           ? blogPosts
-          : take(blogPosts, options.blogSidebarCount);
+          : blogPosts.slice(0, options.blogSidebarCount);
+
+      if (archiveBasePath) {
+        const archiveUrl = normalizeUrl([
+          baseUrl,
+          routeBasePath,
+          archiveBasePath,
+        ]);
+        // creates a blog archive route
+        const archiveProp = await createData(
+          `${docuHash(archiveUrl)}.json`,
+          JSON.stringify({blogPosts}, null, 2),
+        );
+        addRoute({
+          path: archiveUrl,
+          component: blogArchiveComponent,
+          exact: true,
+          modules: {
+            archive: aliasedSource(archiveProp),
+          },
+        });
+      }
 
       // This prop is useful to provide the blog list sidebar
       const sidebarProp = await createData(
@@ -269,7 +249,7 @@ export default function pluginContentBlog(
         `blog-post-list-prop-${pluginId}.json`,
         JSON.stringify(
           {
-            title: options.blogSidebarTitle,
+            title: blogSidebarTitle,
             items: sidebarBlogPosts.map((blogPost) => ({
               title: blogPost.metadata.title,
               permalink: blogPost.metadata.permalink,
@@ -321,9 +301,10 @@ export default 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.
-                return {
+              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,
@@ -331,8 +312,8 @@ export default function pluginContentBlog(
                       truncated: true,
                     },
                   },
-                };
-              }),
+                }),
+              ),
               metadata: aliasedSource(pageMetadataPath),
             },
           });
@@ -344,49 +325,61 @@ export default function pluginContentBlog(
         return;
       }
 
-      const tagsModule: TagsModule = {};
-
-      await Promise.all(
-        Object.keys(blogTags).map(async (tag) => {
-          const {name, items, permalink} = blogTags[tag];
-
-          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(
@@ -406,12 +399,11 @@ export default function pluginContentBlog(
       }
     },
 
-    configureWebpack(
-      _config: Configuration,
-      isServer: boolean,
-      {getJSLoader}: ConfigureWebpackUtils,
-      content,
-    ) {
+    translateContent({content, translationFiles}) {
+      return translateContent(content, translationFiles);
+    },
+
+    configureWebpack(_config, isServer, {getJSLoader}, content) {
       const {
         rehypePlugins,
         remarkPlugins,
@@ -436,6 +428,7 @@ export default function pluginContentBlog(
         },
       };
 
+      const contentDirs = getContentPathList(contentPaths);
       return {
         resolve: {
           alias: {
@@ -445,8 +438,8 @@ export default function pluginContentBlog(
         module: {
           rules: [
             {
-              test: /(\.mdx?)$/,
-              include: getContentPathList(contentPaths)
+              test: /\.mdx?$/i,
+              include: contentDirs
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
               use: [
@@ -458,10 +451,17 @@ export default function pluginContentBlog(
                     rehypePlugins,
                     beforeDefaultRemarkPlugins,
                     beforeDefaultRehypePlugins,
-                    staticDir: path.join(siteDir, STATIC_DIR_NAME),
-                    // Note that metadataPath must be the same/in-sync as
-                    // the path from createData for each MDX.
+                    staticDirs: siteConfig.staticDirectories.map((dir) =>
+                      path.resolve(siteDir, dir),
+                    ),
+                    siteDir,
+                    isMDXPartial: createAbsoluteFilePathMatcher(
+                      options.exclude,
+                      contentDirs,
+                    ),
                     metadataPath: (mdxPath: string) => {
+                      // Note that metadataPath must be the same/in-sync as
+                      // the path from createData for each MDX.
                       const aliasedPath = aliasedSitePath(mdxPath, siteDir);
                       return path.join(
                         dataDir,
@@ -471,6 +471,21 @@ export default function pluginContentBlog(
                     // 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
+                    createAssets: ({
+                      frontMatter,
+                      metadata,
+                    }: {
+                      frontMatter: BlogPostFrontMatter;
+                      metadata: MetaData;
+                    }): Assets => ({
+                      image: frontMatter.image,
+                      authorsImageUrls: metadata.authors.map(
+                        (author) => author.imageURL,
+                      ),
+                    }),
                   },
                 },
                 {
@@ -484,34 +499,20 @@ export default function pluginContentBlog(
       };
     },
 
-    async postBuild({outDir}: Props) {
-      if (!options.feedOptions?.type) {
+    async postBuild({outDir, content}) {
+      if (!options.feedOptions.type) {
         return;
       }
-
-      const feed = await generateBlogFeed(contentPaths, context, options);
-
-      if (!feed) {
+      const {blogPosts} = content;
+      if (!blogPosts.length) {
         return;
       }
-
-      const feedTypes = options.feedOptions.type;
-
-      await Promise.all(
-        feedTypes.map(async (feedType) => {
-          const feedPath = path.join(
-            outDir,
-            options.routeBasePath,
-            `${feedType}.xml`,
-          );
-          const feedContent = feedType === 'rss' ? feed.rss2() : feed.atom1();
-          try {
-            await fs.outputFile(feedPath, feedContent);
-          } catch (err) {
-            throw new Error(`Generating ${feedType} feed failed: ${err}.`);
-          }
-        }),
-      );
+      await createBlogFeedFiles({
+        blogPosts,
+        options,
+        outDir,
+        siteConfig,
+      });
     },
 
     injectHtmlTags({content}) {
@@ -524,20 +525,22 @@ export default function pluginContentBlog(
       }
 
       const feedTypes = options.feedOptions.type;
-      const {
-        siteConfig: {title},
-        baseUrl,
-      } = context;
+      const feedTitle = options.feedOptions.title ?? context.siteConfig.title;
       const feedsConfig = {
         rss: {
           type: 'application/rss+xml',
           path: 'rss.xml',
-          title: `${title} Blog RSS Feed`,
+          title: `${feedTitle} RSS Feed`,
         },
         atom: {
           type: 'application/atom+xml',
           path: 'atom.xml',
-          title: `${title} Blog Atom Feed`,
+          title: `${feedTitle} Atom Feed`,
+        },
+        json: {
+          type: 'application/json',
+          path: 'feed.json',
+          title: `${feedTitle} JSON Feed`,
         },
       };
       const headTags: HtmlTags = [];

package/src/markdownLoader.ts

@@ -6,20 +6,17 @@
  */
 
 import {truncate, linkify} from './blogUtils';
-import {parseQuery} from 'loader-utils';
-import {BlogMarkdownLoaderOptions} from './types';
+import type {BlogMarkdownLoaderOptions} from './types';
+import type {LoaderContext} from 'webpack';
 
-// TODO temporary until Webpack5 export this type
-// see https://github.com/webpack/webpack/issues/11630
-interface Loader extends Function {
-  (this: any, source: string): string | Buffer | void | undefined;
-}
-
-const markdownLoader: Loader = function (source) {
+export default function markdownLoader(
+  this: LoaderContext<BlogMarkdownLoaderOptions>,
+  source: string,
+): void {
   const filePath = this.resourcePath;
-  const fileString = source as string;
+  const fileString = source;
   const callback = this.async();
-  const markdownLoaderOptions = this.getOptions() as BlogMarkdownLoaderOptions;
+  const markdownLoaderOptions = this.getOptions();
 
   // Linkify blog posts
   let finalContent = linkify({
@@ -30,7 +27,7 @@ const markdownLoader: Loader = function (source) {
 
   // Truncate content if requested (e.g: file.md?truncated=true).
   const truncated: boolean | undefined = this.resourceQuery
-    ? !!parseQuery(this.resourceQuery).truncated
+    ? !!new URLSearchParams(this.resourceQuery.slice(1)).get('truncated')
     : undefined;
 
   if (truncated) {
@@ -38,6 +35,4 @@ const markdownLoader: Loader = function (source) {
   }
 
   return callback && callback(null, finalContent);
-};
-
-export default markdownLoader;
+}