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

package/src/feed.ts

@@ -5,34 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Feed, Author as FeedAuthor} from 'feed';
-import {PluginOptions, Author, BlogPost, FeedType} from './types';
-import {normalizeUrl, mdxToHtml} from '@docusaurus/utils';
-import {DocusaurusConfig} from '@docusaurus/types';
+import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed';
+import type {BlogPost} from './types';
+import {
+  normalizeUrl,
+  posixPath,
+  mapAsyncSequential,
+  readOutputHTMLFile,
+} from '@docusaurus/utils';
+import cheerio from 'cheerio';
+import type {DocusaurusConfig} from '@docusaurus/types';
 import path from 'path';
 import fs from 'fs-extra';
+import type {
+  FeedType,
+  PluginOptions,
+  Author,
+} from '@docusaurus/plugin-content-blog';
+import {blogPostContainerID} from '@docusaurus/utils-common';
 
-// 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({
+async function generateBlogFeed({
   blogPosts,
   options,
   siteConfig,
+  outDir,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
+  outDir: string;
 }): Promise<Feed | null> {
   if (!blogPosts.length) {
     return null;
@@ -42,9 +43,7 @@ export async function generateBlogFeed({
   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 updated = blogPosts[0] && blogPosts[0].metadata.date;
 
   const feed = new Feed({
     id: blogBaseUrl,
@@ -63,20 +62,45 @@ export async function generateBlogFeed({
     return {name: author.name, link: author.url};
   }
 
-  blogPosts.forEach((post) => {
+  await mapAsyncSequential(blogPosts, async (post) => {
     const {
       id,
-      metadata: {title: metadataTitle, permalink, date, description, authors},
+      metadata: {
+        title: metadataTitle,
+        permalink,
+        date,
+        description,
+        authors,
+        tags,
+      },
     } = post;
-    feed.addItem({
+
+    const content = await readOutputHTMLFile(
+      permalink.replace(siteConfig.baseUrl, ''),
+      outDir,
+      siteConfig.trailingSlash,
+    );
+    const $ = cheerio.load(content);
+
+    const feedItem: FeedItem = {
       title: metadataTitle,
       id,
       link: normalizeUrl([siteUrl, permalink]),
       date,
       description,
-      content: mdxToFeedContent(post.content),
-      author: authors.map(toFeedAuthor),
-    });
+      // Atom feed demands the "term", while other feeds use "name"
+      category: tags.map((tag) => ({name: tag.label, term: tag.label})),
+      content: $(`#${blogPostContainerID}`).html()!,
+    };
+
+    // 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;
@@ -85,15 +109,29 @@ export async function generateBlogFeed({
 async function createBlogFeedFile({
   feed,
   feedType,
-  filePath,
+  generatePath,
 }: {
   feed: Feed;
   feedType: FeedType;
-  filePath: string;
+  generatePath: string;
 }) {
-  const feedContent = feedType === 'rss' ? feed.rss2() : feed.atom1();
+  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(filePath, feedContent);
+    await fs.outputFile(
+      posixPath(path.join(generatePath, feedPath)),
+      feedContent,
+    );
   } catch (err) {
     throw new Error(`Generating ${feedType} feed failed: ${err}.`);
   }
@@ -110,7 +148,12 @@ export async function createBlogFeedFiles({
   siteConfig: DocusaurusConfig;
   outDir: string;
 }): Promise<void> {
-  const feed = await generateBlogFeed({blogPosts, options, siteConfig});
+  const feed = await generateBlogFeed({
+    blogPosts,
+    options,
+    siteConfig,
+    outDir,
+  });
 
   const feedTypes = options.feedOptions.type;
   if (!feed || !feedTypes) {
@@ -118,12 +161,12 @@ export async function createBlogFeedFiles({
   }
 
   await Promise.all(
-    feedTypes.map(async (feedType) => {
-      await createBlogFeedFile({
+    feedTypes.map((feedType) =>
+      createBlogFeedFile({
         feed,
         feedType,
-        filePath: path.join(outDir, options.routeBasePath, `${feedType}.xml`),
-      });
-    }),
+        generatePath: path.join(outDir, options.routeBasePath),
+      }),
+    ),
   );
 }

package/src/index.ts

@@ -16,12 +16,13 @@ import {
   posixPath,
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
+  getContentPathList,
+  getDataFilePath,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import {translateContent, getTranslationFiles} from './translations';
 
-import {
-  PluginOptions,
+import type {
   BlogTags,
   BlogContent,
   BlogItemsToMetadata,
@@ -30,32 +31,33 @@ import {
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
   MetaData,
-  Assets,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
-import {
+import type {
   LoadContext,
   ConfigureWebpackUtils,
-  Props,
   Plugin,
   HtmlTags,
   OptionValidationContext,
   ValidationResult,
 } from '@docusaurus/types';
-import {Configuration} from 'webpack';
+import type {Configuration} from 'webpack';
 import {
   generateBlogPosts,
-  getContentPathList,
   getSourceToPermalink,
   getBlogTags,
 } from './blogUtils';
-import {BlogPostFrontMatter} from './blogFrontMatter';
 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],
@@ -89,24 +91,23 @@ 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, authorsMapPath} = options;
+      const {include} = options;
       const contentMarkdownGlobs = getContentPathList(contentPaths).flatMap(
         (contentPath) => include.map((pattern) => `${contentPath}/${pattern}`),
       );
 
-      // 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,
-      );
-
-      return [authorsMapFilePath, ...contentMarkdownGlobs];
+      return [authorsMapFilePath, ...contentMarkdownGlobs].filter(
+        Boolean,
+      ) as string[];
     },
 
     async getTranslationFiles() {
@@ -240,25 +241,26 @@ export default function pluginContentBlog(
           ? blogPosts
           : 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),
-        },
-      });
+      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: '@theme/BlogArchivePage',
+          exact: true,
+          modules: {
+            archive: aliasedSource(archiveProp),
+          },
+        });
+      }
 
       // This prop is useful to provide the blog list sidebar
       const sidebarProp = await createData(
@@ -509,14 +511,11 @@ export default function pluginContentBlog(
       };
     },
 
-    async postBuild({outDir}: Props) {
+    async postBuild({outDir, content}) {
       if (!options.feedOptions.type) {
         return;
       }
-
-      // TODO: we shouldn't need to re-read the posts here!
-      // postBuild should receive loadedContent
-      const blogPosts = await generateBlogPosts(contentPaths, context, options);
+      const {blogPosts} = content;
       if (!blogPosts.length) {
         return;
       }
@@ -550,6 +549,11 @@ export default function pluginContentBlog(
           path: 'atom.xml',
           title: `${feedTitle} Atom Feed`,
         },
+        json: {
+          type: 'application/json',
+          path: 'feed.json',
+          title: `${feedTitle} JSON Feed`,
+        },
       };
       const headTags: HtmlTags = [];
 

package/src/markdownLoader.ts

@@ -6,8 +6,7 @@
  */
 
 import {truncate, linkify} from './blogUtils';
-import {parseQuery} from 'loader-utils';
-import {BlogMarkdownLoaderOptions} from './types';
+import type {BlogMarkdownLoaderOptions} from './types';
 import type {LoaderContext} from 'webpack';
 
 export default function markdownLoader(
@@ -28,7 +27,7 @@ export default function markdownLoader(
 
   // 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) {

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

@@ -6,7 +6,145 @@
  */
 
 declare module '@docusaurus/plugin-content-blog' {
-  export type Options = Partial<import('./types').UserPluginOptions>;
+  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
+  import type {FrontMatterTag} from '@docusaurus/utils';
+  import type {Overwrite} from 'utility-types';
+
+  export interface Assets {
+    image?: string;
+    authorsImageUrls: (string | undefined)[]; // Array of same size as the original MetaData.authors array
+  }
+
+  // We allow passing custom fields to authors, e.g., twitter
+  export interface Author extends Record<string, unknown> {
+    name?: string;
+    imageURL?: string;
+    url?: string;
+    title?: string;
+  }
+
+  export type BlogPostFrontMatter = {
+    id?: string;
+    title?: string;
+    description?: string;
+    tags?: FrontMatterTag[];
+    slug?: string;
+    draft?: boolean;
+    date?: Date | string; // Yaml automatically convert some string patterns as Date, but not all
+
+    authors?: BlogPostFrontMatterAuthors;
+
+    // We may want to deprecate those older author front matter fields later:
+    author?: string;
+    author_title?: string;
+    author_url?: string;
+    author_image_url?: string;
+
+    /** @deprecated */
+    authorTitle?: string;
+    /** @deprecated */
+    authorURL?: string;
+    /** @deprecated */
+    authorImageURL?: string;
+
+    image?: string;
+    keywords?: string[];
+    hide_table_of_contents?: boolean;
+    toc_min_heading_level?: number;
+    toc_max_heading_level?: number;
+  };
+
+  export type BlogPostFrontMatterAuthor = Record<string, unknown> & {
+    key?: string;
+    name?: string;
+    imageURL?: string;
+    url?: string;
+    title?: string;
+  };
+
+  // All the possible variants that the user can use for convenience
+  export type BlogPostFrontMatterAuthors =
+    | string
+    | BlogPostFrontMatterAuthor
+    | (string | BlogPostFrontMatterAuthor)[];
+
+  export type EditUrlFunction = (editUrlParams: {
+    blogDirPath: string;
+    blogPath: string;
+    permalink: string;
+    locale: string;
+  }) => string | undefined;
+
+  export type FeedType = 'rss' | 'atom' | 'json';
+  export type FeedOptions = {
+    type?: FeedType[] | null;
+    title?: string;
+    description?: string;
+    copyright: string;
+    language?: string;
+  };
+  // Feed options, as provided by user config
+  export type UserFeedOptions = Overwrite<
+    Partial<FeedOptions>,
+    {type?: FeedOptions['type'] | 'all'} // Handle the type: "all" shortcut
+  >;
+
+  // Duplicate from ngryman/reading-time to keep stability of API
+  type ReadingTimeOptions = {
+    wordsPerMinute?: number;
+    wordBound?: (char: string) => boolean;
+  };
+
+  export type ReadingTimeFunction = (params: {
+    content: string;
+    frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
+    options?: ReadingTimeOptions;
+  }) => number;
+
+  export type ReadingTimeFunctionOption = (
+    params: Required<Omit<Parameters<ReadingTimeFunction>[0], 'options'>> & {
+      defaultReadingTime: ReadingTimeFunction;
+    },
+  ) => number | undefined;
+
+  export type PluginOptions = RemarkAndRehypePluginOptions & {
+    id?: string;
+    path: string;
+    routeBasePath: string;
+    tagsBasePath: string;
+    archiveBasePath: string | null;
+    include: string[];
+    exclude: string[];
+    postsPerPage: number | 'ALL';
+    blogListComponent: string;
+    blogPostComponent: string;
+    blogTagsListComponent: string;
+    blogTagsPostsComponent: string;
+    blogTitle: string;
+    blogDescription: string;
+    blogSidebarCount: number | 'ALL';
+    blogSidebarTitle: string;
+    truncateMarker: RegExp;
+    showReadingTime: boolean;
+    feedOptions: {
+      type?: FeedType[] | null;
+      title?: string;
+      description?: string;
+      copyright: string;
+      language?: string;
+    };
+    editUrl?: string | EditUrlFunction;
+    editLocalizedFiles?: boolean;
+    admonitions: Record<string, unknown>;
+    authorsMapPath: string;
+    readingTime: ReadingTimeFunctionOption;
+    sortPosts: 'ascending' | 'descending';
+  };
+  // Options, as provided in the user config (before normalization)
+  export type Options = Overwrite<
+    Partial<PluginOptions>,
+    {feedOptions?: UserFeedOptions}
+  >;
 }
 
 declare module '@theme/BlogSidebar' {
@@ -27,9 +165,13 @@ declare module '@theme/BlogSidebar' {
 declare module '@theme/BlogPostPage' {
   import type {BlogSidebar} from '@theme/BlogSidebar';
   import type {TOCItem} from '@docusaurus/types';
+  import type {
+    BlogPostFrontMatter,
+    Author,
+    Assets,
+  } from '@docusaurus/plugin-content-blog';
 
-  export type FrontMatter = import('./blogFrontMatter').BlogPostFrontMatter;
-  export type Assets = import('./types').Assets;
+  export type FrontMatter = BlogPostFrontMatter;
 
   export type Metadata = {
     readonly title: string;
@@ -42,7 +184,8 @@ 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 authors: Author[];
+    readonly frontMatter: FrontMatter & Record<string, unknown>;
     readonly tags: readonly {
       readonly label: string;
       readonly permalink: string;

package/src/pluginOptionSchema.ts

@@ -13,7 +13,7 @@ import {
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
-import {PluginOptions} from './types';
+import type {PluginOptions} from '@docusaurus/plugin-content-blog';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
   feedOptions: {type: ['rss', 'atom'], copyright: ''},
@@ -47,7 +47,9 @@ export const DEFAULT_OPTIONS: PluginOptions = {
 
 export const PluginOptionSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
-  archiveBasePath: Joi.string().default(DEFAULT_OPTIONS.archiveBasePath),
+  archiveBasePath: Joi.string()
+    .default(DEFAULT_OPTIONS.archiveBasePath)
+    .allow(null),
   routeBasePath: Joi.string()
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('')
@@ -90,12 +92,12 @@ export const PluginOptionSchema = Joi.object<PluginOptions>({
   feedOptions: Joi.object({
     type: Joi.alternatives()
       .try(
-        Joi.array().items(Joi.string()),
+        Joi.array().items(Joi.string().equal('rss', 'atom', 'json')),
         Joi.alternatives().conditional(
-          Joi.string().equal('all', 'rss', 'atom'),
+          Joi.string().equal('all', 'rss', 'atom', 'json'),
           {
             then: Joi.custom((val) =>
-              val === 'all' ? ['rss', 'atom'] : [val],
+              val === 'all' ? ['rss', 'atom', 'json'] : [val],
             ),
           },
         ),

package/src/translations.ts

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {BlogContent, PluginOptions, BlogPaginated} from './types';
+import type {BlogContent, BlogPaginated} from './types';
 import type {TranslationFileContent, TranslationFiles} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-content-blog';
 
 function translateListPage(
   blogListPaginated: BlogPaginated[],
@@ -51,13 +52,13 @@ export function translateContent(
   content: BlogContent,
   translationFiles: TranslationFiles,
 ): BlogContent {
-  const [{content: optonsTranslations}] = translationFiles;
+  const [{content: optionsTranslations}] = translationFiles;
   return {
     ...content,
-    blogSidebarTitle: optonsTranslations['sidebar.title'].message,
+    blogSidebarTitle: optionsTranslations['sidebar.title'].message,
     blogListPaginated: translateListPage(
       content.blogListPaginated,
-      optonsTranslations,
+      optionsTranslations,
     ),
   };
 }