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

package/src/feed.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {Feed, Author as FeedAuthor, Item as FeedItem} from 'feed';
+import {PluginOptions, Author, BlogPost, FeedType} from './types';
+import {normalizeUrl, mdxToHtml} from '@docusaurus/utils';
+import {DocusaurusConfig} from '@docusaurus/types';
+import path from 'path';
+import fs from 'fs-extra';
+
+// TODO this is temporary until we handle mdxToHtml better
+// It's hard to convert reliably JSX/require calls  to an html feed content
+// See https://github.com/facebook/docusaurus/issues/5664
+function mdxToFeedContent(mdxContent: string): string | undefined {
+  try {
+    return mdxToHtml(mdxContent);
+  } catch (e) {
+    // TODO will we need a plugin option to configure how to handle such an error
+    // Swallow the error on purpose for now, until we understand better the problem space
+    return undefined;
+  }
+}
+
+export async function generateBlogFeed({
+  blogPosts,
+  options,
+  siteConfig,
+}: {
+  blogPosts: BlogPost[];
+  options: PluginOptions;
+  siteConfig: DocusaurusConfig;
+}): Promise<Feed | null> {
+  if (!blogPosts.length) {
+    return null;
+  }
+
+  const {feedOptions, routeBasePath} = options;
+  const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
+  const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, routeBasePath]);
+
+  const updated =
+    (blogPosts[0] && blogPosts[0].metadata.date) ||
+    new Date('2015-10-25T16:29:00.000-07:00'); // weird legacy magic date
+
+  const feed = new Feed({
+    id: blogBaseUrl,
+    title: feedOptions.title || `${title} Blog`,
+    updated,
+    language: feedOptions.language,
+    link: blogBaseUrl,
+    description: feedOptions.description || `${siteConfig.title} Blog`,
+    favicon: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
+    copyright: feedOptions.copyright,
+  });
+
+  function toFeedAuthor(author: Author): FeedAuthor {
+    // TODO ask author emails?
+    // RSS feed requires email to render authors
+    return {name: author.name, link: author.url};
+  }
+
+  blogPosts.forEach((post) => {
+    const {
+      id,
+      metadata: {title: metadataTitle, permalink, date, description, authors},
+    } = post;
+
+    const feedItem: FeedItem = {
+      title: metadataTitle,
+      id,
+      link: normalizeUrl([siteUrl, permalink]),
+      date,
+      description,
+      content: mdxToFeedContent(post.content),
+    };
+
+    // json1() method takes the first item of authors array
+    // it causes an error when authors array is empty
+    const feedItemAuthors = authors.map(toFeedAuthor);
+    if (feedItemAuthors.length > 0) {
+      feedItem.author = feedItemAuthors;
+    }
+
+    feed.addItem(feedItem);
+  });
+
+  return feed;
+}
+
+async function createBlogFeedFile({
+  feed,
+  feedType,
+  generatePath,
+}: {
+  feed: Feed;
+  feedType: FeedType;
+  generatePath: string;
+}) {
+  const [feedContent, feedPath] = (() => {
+    switch (feedType) {
+      case 'rss':
+        return [feed.rss2(), 'rss.xml'];
+      case 'json':
+        return [feed.json1(), 'feed.json'];
+      case 'atom':
+        return [feed.atom1(), 'atom.xml'];
+      default:
+        throw new Error(`Feed type ${feedType} not supported.`);
+    }
+  })();
+  try {
+    await fs.outputFile(path.join(generatePath, feedPath), feedContent);
+  } catch (err) {
+    throw new Error(`Generating ${feedType} feed failed: ${err}.`);
+  }
+}
+
+export async function createBlogFeedFiles({
+  blogPosts,
+  options,
+  siteConfig,
+  outDir,
+}: {
+  blogPosts: BlogPost[];
+  options: PluginOptions;
+  siteConfig: DocusaurusConfig;
+  outDir: string;
+}): Promise<void> {
+  const feed = await generateBlogFeed({blogPosts, options, siteConfig});
+
+  const feedTypes = options.feedOptions.type;
+  if (!feed || !feedTypes) {
+    return;
+  }
+
+  await Promise.all(
+    feedTypes.map((feedType) =>
+      createBlogFeedFile({
+        feed,
+        feedType,
+        generatePath: path.join(outDir, options.routeBasePath),
+      }),
+    ),
+  );
+}

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,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

@@ -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;
+}