@docusaurus/plugin-content-blog 2.0.0-beta.12faed89d → 2.0.0-beta.13

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,12 +15,10 @@ import {
   reportMessage,
   posixPath,
   addTrailingPathSeparator,
-} from '@docusaurus/utils';
-import {
-  STATIC_DIR_NAME,
+  createAbsoluteFilePathMatcher,
   DEFAULT_PLUGIN_ID,
-} from '@docusaurus/core/lib/constants';
-import {flatten, take, kebabCase} from 'lodash';
+} from '@docusaurus/utils';
+import {translateContent, getTranslationFiles} from './translations';
 
 import {
   PluginOptions,
@@ -30,9 +27,10 @@ import {
   BlogItemsToMetadata,
   TagsModule,
   BlogPaginated,
-  BlogPost,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
+  MetaData,
+  Assets,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
 import {
@@ -46,11 +44,13 @@ import {
 } from '@docusaurus/types';
 import {Configuration} from 'webpack';
 import {
-  generateBlogFeed,
   generateBlogPosts,
   getContentPathList,
   getSourceToPermalink,
+  getBlogTags,
 } from './blogUtils';
+import {BlogPostFrontMatter} from './blogFrontMatter';
+import {createBlogFeedFiles} from './feed';
 
 export default function pluginContentBlog(
   context: LoadContext,
@@ -64,10 +64,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),
@@ -92,36 +93,42 @@ export default function pluginContentBlog(
     name: 'docusaurus-plugin-content-blog',
 
     getPathsToWatch() {
-      const {include = []} = options;
-      return flatten(
-        getContentPathList(contentPaths).map((contentPath) => {
-          return include.map((pattern) => `${contentPath}/${pattern}`);
-        }),
+      const {include, authorsMapPath} = options;
+      const contentMarkdownGlobs = getContentPathList(contentPaths).flatMap(
+        (contentPath) => include.map((pattern) => `${contentPath}/${pattern}`),
       );
-    },
 
-    getClientModules() {
-      const modules = [];
+      // TODO: we should read this path in plugin! but plugins do not support async init for now :'(
+      // const authorsMapFilePath = await getAuthorsMapFilePath({authorsMapPath,contentPaths,});
+      // simplified impl, better than nothing for now:
+      const authorsMapFilePath = path.join(
+        contentPaths.contentPath,
+        authorsMapPath,
+      );
 
-      if (options.admonitions) {
-        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
-      }
+      return [authorsMapFilePath, ...contentMarkdownGlobs];
+    },
 
-      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: {},
@@ -152,18 +159,17 @@ export default 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 {
-        siteConfig: {baseUrl = ''},
-      } = context;
-      const basePageUrl = normalizeUrl([baseUrl, routeBasePath]);
+      const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
 
       const blogListPaginated: BlogPaginated[] = [];
 
       function blogPaginationPermalink(page: number) {
         return page > 0
-          ? normalizeUrl([basePageUrl, `page/${page + 1}`])
-          : basePageUrl;
+          ? normalizeUrl([baseBlogUrl, `page/${page + 1}`])
+          : baseBlogUrl;
       }
 
       for (let page = 0; page < numberOfPages; page += 1) {
@@ -179,8 +185,8 @@ export default function pluginContentBlog(
               page < numberOfPages - 1
                 ? blogPaginationPermalink(page + 1)
                 : null,
-            blogDescription: options.blogDescription,
-            blogTitle: options.blogTitle,
+            blogDescription,
+            blogTitle,
           },
           items: blogPosts
             .slice(page * postsPerPage, (page + 1) * postsPerPage)
@@ -188,46 +194,15 @@ export default function pluginContentBlog(
         });
       }
 
-      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 blogTags: BlogTags = getBlogTags(blogPosts);
 
-        // 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 tagsPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
 
       const blogTagsListPath =
         Object.keys(blogTags).length > 0 ? tagsPath : null;
 
       return {
+        blogSidebarTitle,
         blogPosts,
         blogListPaginated,
         blogTags,
@@ -245,10 +220,13 @@ export default function pluginContentBlog(
         blogPostComponent,
         blogTagsListComponent,
         blogTagsPostsComponent,
+        routeBasePath,
+        archiveBasePath,
       } = options;
 
       const {addRoute, createData} = actions;
       const {
+        blogSidebarTitle,
         blogPosts,
         blogListPaginated,
         blogTags,
@@ -260,7 +238,27 @@ export default function pluginContentBlog(
       const sidebarBlogPosts =
         options.blogSidebarCount === 'ALL'
           ? blogPosts
-          : take(blogPosts, options.blogSidebarCount);
+          : blogPosts.slice(0, options.blogSidebarCount);
+
+      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: '@theme/BlogArchivePage',
+        exact: true,
+        modules: {
+          archive: aliasedSource(archiveProp),
+        },
+      });
 
       // This prop is useful to provide the blog list sidebar
       const sidebarProp = await createData(
@@ -269,7 +267,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 +319,9 @@ export default function pluginContentBlog(
             exact: true,
             modules: {
               sidebar: aliasedSource(sidebarProp),
-              items: items.map((postID) => {
+              items: items.map((postID) =>
                 // To tell routes.js this is an import and not a nested object to recurse.
-                return {
+                ({
                   content: {
                     __import: true,
                     path: blogItemsToMetadata[postID].source,
@@ -331,8 +329,8 @@ export default function pluginContentBlog(
                       truncated: true,
                     },
                   },
-                };
-              }),
+                }),
+              ),
               metadata: aliasedSource(pageMetadataPath),
             },
           });
@@ -350,6 +348,7 @@ export default function pluginContentBlog(
         Object.keys(blogTags).map(async (tag) => {
           const {name, items, permalink} = blogTags[tag];
 
+          // Refactor all this, see docs implementation
           tagsModule[tag] = {
             allTagsPath: blogTagsListPath,
             slug: tag,
@@ -406,6 +405,10 @@ export default function pluginContentBlog(
       }
     },
 
+    translateContent({content, translationFiles}) {
+      return translateContent(content, translationFiles);
+    },
+
     configureWebpack(
       _config: Configuration,
       isServer: boolean,
@@ -436,6 +439,7 @@ export default function pluginContentBlog(
         },
       };
 
+      const contentDirs = getContentPathList(contentPaths);
       return {
         resolve: {
           alias: {
@@ -446,7 +450,7 @@ export default function pluginContentBlog(
           rules: [
             {
               test: /(\.mdx?)$/,
-              include: getContentPathList(contentPaths)
+              include: contentDirs
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
               use: [
@@ -458,10 +462,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 +482,20 @@ 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,
+                      ),
+                    }),
                   },
                 },
                 {
@@ -485,33 +510,22 @@ export default function pluginContentBlog(
     },
 
     async postBuild({outDir}: Props) {
-      if (!options.feedOptions?.type) {
+      if (!options.feedOptions.type) {
         return;
       }
 
-      const feed = await generateBlogFeed(contentPaths, context, options);
-
-      if (!feed) {
+      // TODO: we shouldn't need to re-read the posts here!
+      // postBuild should receive loadedContent
+      const blogPosts = await generateBlogPosts(contentPaths, context, options);
+      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 +538,17 @@ 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`,
         },
       };
       const headTags: HtmlTags = [];

package/src/markdownLoader.ts

@@ -8,18 +8,16 @@
 import {truncate, linkify} from './blogUtils';
 import {parseQuery} from 'loader-utils';
 import {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({
@@ -38,6 +36,4 @@ const markdownLoader: Loader = function (source) {
   }
 
   return callback && callback(null, finalContent);
-};
-
-export default markdownLoader;
+}

package/{index.d.ts → src/plugin-content-blog.d.ts}

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable import/no-duplicates */
-/* eslint-disable camelcase */
+declare module '@docusaurus/plugin-content-blog' {
+  export type Options = Partial<import('./types').UserPluginOptions>;
+}
 
 declare module '@theme/BlogSidebar' {
   export type BlogSidebarItem = {title: string; permalink: string};
@@ -15,32 +16,20 @@ declare module '@theme/BlogSidebar' {
     items: BlogSidebarItem[];
   };
 
-  export type Props = {
+  export interface Props {
     readonly sidebar: BlogSidebar;
-  };
+  }
 
   const BlogSidebar: (props: Props) => JSX.Element;
   export default BlogSidebar;
 }
 
 declare module '@theme/BlogPostPage' {
-  import type {TOCItem} from '@docusaurus/types';
   import type {BlogSidebar} from '@theme/BlogSidebar';
+  import type {TOCItem} from '@docusaurus/types';
 
-  export type FrontMatter = {
-    readonly title: string;
-    readonly author?: string;
-    readonly image?: string;
-    readonly tags?: readonly string[];
-    readonly keywords?: readonly string[];
-    readonly author_url?: string;
-    readonly authorURL?: string;
-    readonly author_title?: string;
-    readonly authorTitle?: string;
-    readonly author_image_url?: string;
-    readonly authorImageURL?: string;
-    readonly hide_table_of_contents?: boolean;
-  };
+  export type FrontMatter = import('./blogFrontMatter').BlogPostFrontMatter;
+  export type Assets = import('./types').Assets;
 
   export type Metadata = {
     readonly title: string;
@@ -53,6 +42,7 @@ declare module '@theme/BlogPostPage' {
     readonly truncated?: string;
     readonly nextItem?: {readonly title: string; readonly permalink: string};
     readonly prevItem?: {readonly title: string; readonly permalink: string};
+    readonly authors: import('./types').Author[];
     readonly tags: readonly {
       readonly label: string;
       readonly permalink: string;
@@ -61,15 +51,16 @@ declare module '@theme/BlogPostPage' {
 
   export type Content = {
     readonly frontMatter: FrontMatter;
+    readonly assets: Assets;
     readonly metadata: Metadata;
     readonly toc: readonly TOCItem[];
     (): JSX.Element;
   };
 
-  export type Props = {
+  export interface Props {
     readonly sidebar: BlogSidebar;
     readonly content: Content;
-  };
+  }
 
   const BlogPostPage: (props: Props) => JSX.Element;
   export default BlogPostPage;
@@ -79,10 +70,6 @@ declare module '@theme/BlogListPage' {
   import type {Content} from '@theme/BlogPostPage';
   import type {BlogSidebar} from '@theme/BlogSidebar';
 
-  export type Item = {
-    readonly content: () => JSX.Element;
-  };
-
   export type Metadata = {
     readonly blogTitle: string;
     readonly blogDescription: string;
@@ -95,11 +82,11 @@ declare module '@theme/BlogListPage' {
     readonly totalPages: number;
   };
 
-  export type Props = {
+  export interface Props {
     readonly sidebar: BlogSidebar;
     readonly metadata: Metadata;
     readonly items: readonly {readonly content: Content}[];
-  };
+  }
 
   const BlogListPage: (props: Props) => JSX.Element;
   export default BlogListPage;
@@ -116,10 +103,10 @@ declare module '@theme/BlogTagsListPage' {
     slug: string;
   };
 
-  export type Props = {
+  export interface Props {
     readonly sidebar: BlogSidebar;
     readonly tags: Readonly<Record<string, Tag>>;
-  };
+  }
 
   const BlogTagsListPage: (props: Props) => JSX.Element;
   export default BlogTagsListPage;
@@ -130,9 +117,26 @@ declare module '@theme/BlogTagsPostsPage' {
   import type {Tag} from '@theme/BlogTagsListPage';
   import type {Content} from '@theme/BlogPostPage';
 
-  export type Props = {
+  export interface Props {
     readonly sidebar: BlogSidebar;
     readonly metadata: Tag;
     readonly items: readonly {readonly content: Content}[];
-  };
+  }
+
+  const BlogTagsPostsPage: (props: Props) => JSX.Element;
+  export default BlogTagsPostsPage;
+}
+
+declare module '@theme/BlogArchivePage' {
+  import type {Content} from '@theme/BlogPostPage';
+
+  export type ArchiveBlogPost = Content;
+
+  export interface Props {
+    readonly archive: {
+      readonly blogPosts: readonly ArchiveBlogPost[];
+    };
+  }
+
+  export default function BlogArchivePage(props: Props): JSX.Element;
 }

package/src/pluginOptionSchema.ts

@@ -12,9 +12,11 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import {PluginOptions} from './types';
 
-export const DEFAULT_OPTIONS = {
-  feedOptions: {type: ['rss', 'atom']},
+export const DEFAULT_OPTIONS: PluginOptions = {
+  feedOptions: {type: ['rss', 'atom'], copyright: ''},
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: {},
@@ -31,22 +33,30 @@ export const DEFAULT_OPTIONS = {
   blogSidebarCount: 5,
   blogSidebarTitle: 'Recent posts',
   postsPerPage: 10,
-  include: ['*.md', '*.mdx'],
+  include: ['**/*.{md,mdx}'],
+  exclude: GlobExcludeDefault,
   routeBasePath: 'blog',
+  tagsBasePath: 'tags',
+  archiveBasePath: 'archive',
   path: 'blog',
   editLocalizedFiles: false,
+  authorsMapPath: 'authors.yml',
+  readingTime: ({content, defaultReadingTime}) => defaultReadingTime({content}),
+  sortPosts: 'descending',
 };
 
-export const PluginOptionSchema = Joi.object({
+export const PluginOptionSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
+  archiveBasePath: Joi.string().default(DEFAULT_OPTIONS.archiveBasePath),
   routeBasePath: Joi.string()
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('')
     .default(DEFAULT_OPTIONS.routeBasePath),
+  tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
-  postsPerPage: Joi.number()
-    .integer()
-    .min(1)
+  exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
+  postsPerPage: Joi.alternatives()
+    .try(Joi.equal('ALL').required(), Joi.number().integer().min(1).required())
     .default(DEFAULT_OPTIONS.postsPerPage),
   blogListComponent: Joi.string().default(DEFAULT_OPTIONS.blogListComponent),
   blogPostComponent: Joi.string().default(DEFAULT_OPTIONS.blogPostComponent),
@@ -61,7 +71,7 @@ export const PluginOptionSchema = Joi.object({
     .allow('')
     .default(DEFAULT_OPTIONS.blogDescription),
   blogSidebarCount: Joi.alternatives()
-    .try(Joi.equal('ALL').required(), Joi.number().required())
+    .try(Joi.equal('ALL').required(), Joi.number().integer().min(0).required())
     .default(DEFAULT_OPTIONS.blogSidebarCount),
   blogSidebarTitle: Joi.string().default(DEFAULT_OPTIONS.blogSidebarTitle),
   showReadingTime: Joi.bool().default(DEFAULT_OPTIONS.showReadingTime),
@@ -94,7 +104,19 @@ export const PluginOptionSchema = Joi.object({
       .default(DEFAULT_OPTIONS.feedOptions.type),
     title: Joi.string().allow(''),
     description: Joi.string().allow(''),
-    copyright: Joi.string(),
+    // 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(),
+      otherwise: Joi.string()
+        .allow('')
+        .default(DEFAULT_OPTIONS.feedOptions.copyright),
+    }),
     language: Joi.string(),
   }).default(DEFAULT_OPTIONS.feedOptions),
+  authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
+  readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),
+  sortPosts: Joi.string()
+    .valid('descending', 'ascending')
+    .default(DEFAULT_OPTIONS.sortPosts),
 });