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

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

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('')

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,
     ),
   };
 }

package/src/types.ts

@@ -5,14 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
 import type {Tag} from '@docusaurus/utils';
 import type {
   BrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
-import {Overwrite} from 'utility-types';
-import {BlogPostFrontMatter} from './blogFrontMatter';
+import type {
+  BlogPostFrontMatter,
+  Author,
+} from '@docusaurus/plugin-content-blog';
 
 export type BlogContentPaths = ContentPaths;
 
@@ -24,87 +25,6 @@ export interface BlogContent {
   blogTagsListPath: string | null;
 }
 
-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
->;
-
-export type EditUrlFunction = (editUrlParams: {
-  blogDirPath: string;
-  blogPath: string;
-  permalink: string;
-  locale: string;
-}) => string | undefined;
-
-// 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;
-  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 UserPluginOptions = Overwrite<
-  Partial<PluginOptions>,
-  {feedOptions?: UserFeedOptions}
->;
-
 export interface BlogTags {
   [key: string]: BlogTag;
 }
@@ -138,14 +58,6 @@ export interface BlogPaginated {
   items: string[];
 }
 
-// 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 interface MetaData {
   permalink: string;
   source: string;
@@ -160,11 +72,7 @@ export interface MetaData {
   truncated: boolean;
   editUrl?: string;
   authors: Author[];
-}
-
-export interface Assets {
-  image?: string;
-  authorsImageUrls: (string | undefined)[]; // Array of same size as the original MetaData.authors array
+  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
 }
 
 export interface Paginator {