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

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

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+
+declare module '@docusaurus/plugin-content-blog' {
+  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;
+    email?: 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;
+    blogArchiveComponent: 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/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 = BlogPostFrontMatter;
+
+  export type Metadata = {
+    readonly title: string;
+    readonly date: string;
+    readonly formattedDate: string;
+    readonly permalink: string;
+    readonly description?: string;
+    readonly editUrl?: string;
+    readonly readingTime?: number;
+    readonly truncated?: string;
+    readonly nextItem?: {readonly title: string; readonly permalink: string};
+    readonly prevItem?: {readonly title: string; readonly permalink: string};
+    readonly authors: Author[];
+    readonly frontMatter: FrontMatter & Record<string, unknown>;
+    readonly tags: readonly {
+      readonly label: string;
+      readonly permalink: string;
+    }[];
+  };
+
+  export type Content = {
+    readonly frontMatter: FrontMatter;
+    readonly assets: Assets;
+    readonly metadata: Metadata;
+    readonly toc: readonly TOCItem[];
+    (): JSX.Element;
+  };
+
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+    readonly content: Content;
+  }
+
+  export default function BlogPostPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogListPage' {
+  import type {Content} from '@theme/BlogPostPage';
+  import type {BlogSidebar} from '@theme/BlogSidebar';
+
+  export type Metadata = {
+    readonly blogTitle: string;
+    readonly blogDescription: string;
+    readonly nextPage?: string;
+    readonly page: number;
+    readonly permalink: string;
+    readonly postsPerPage: number;
+    readonly previousPage?: string;
+    readonly totalCount: number;
+    readonly totalPages: number;
+  };
+
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+    readonly metadata: Metadata;
+    readonly items: readonly {readonly content: Content}[];
+  }
+
+  export default function BlogListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogTagsListPage' {
+  import type {BlogSidebar} from '@theme/BlogSidebar';
+
+  export type Tag = {
+    permalink: string;
+    name: string;
+    count: number;
+    allTagsPath: string;
+    slug: string;
+  };
+
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+    readonly tags: Readonly<Record<string, Tag>>;
+  }
+
+  export default function BlogTagsListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogTagsPostsPage' {
+  import type {BlogSidebar} from '@theme/BlogSidebar';
+  import type {Tag} from '@theme/BlogTagsListPage';
+  import type {Content} from '@theme/BlogPostPage';
+  import type {Metadata} from '@theme/BlogListPage';
+
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+    readonly metadata: Tag;
+    readonly listMetadata: Metadata;
+    readonly items: readonly {readonly content: Content}[];
+  }
+
+  export default function BlogTagsPostsPage(props: Props): JSX.Element;
+}
+
+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,13 +12,15 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import type {PluginOptions} from '@docusaurus/plugin-content-blog';
 
-export const DEFAULT_OPTIONS = {
-  feedOptions: {type: ['rss', 'atom']},
+export const DEFAULT_OPTIONS: PluginOptions = {
+  feedOptions: {type: ['rss', 'atom'], copyright: ''},
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: {},
-  truncateMarker: /<!--\s*(truncate)\s*-->/,
+  truncateMarker: /<!--\s*truncate\s*-->/,
   rehypePlugins: [],
   remarkPlugins: [],
   showReadingTime: true,
@@ -26,27 +28,38 @@ export const DEFAULT_OPTIONS = {
   blogTagsListComponent: '@theme/BlogTagsListPage',
   blogPostComponent: '@theme/BlogPostPage',
   blogListComponent: '@theme/BlogListPage',
+  blogArchiveComponent: '@theme/BlogArchivePage',
   blogDescription: 'Blog',
   blogTitle: 'Blog',
   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)
+    .allow(null),
   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),
@@ -56,12 +69,15 @@ export const PluginOptionSchema = Joi.object({
   blogTagsPostsComponent: Joi.string().default(
     DEFAULT_OPTIONS.blogTagsPostsComponent,
   ),
+  blogArchiveComponent: Joi.string().default(
+    DEFAULT_OPTIONS.blogArchiveComponent,
+  ),
   blogTitle: Joi.string().allow('').default(DEFAULT_OPTIONS.blogTitle),
   blogDescription: Joi.string()
     .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),
@@ -80,12 +96,12 @@ export const PluginOptionSchema = Joi.object({
   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],
             ),
           },
         ),
@@ -94,7 +110,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),
 });

package/src/translations.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 type {BlogContent, BlogPaginated} from './types';
+import type {TranslationFileContent, TranslationFiles} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-content-blog';
+
+function translateListPage(
+  blogListPaginated: BlogPaginated[],
+  translations: TranslationFileContent,
+) {
+  return blogListPaginated.map((page) => {
+    const {items, metadata} = page;
+    return {
+      items,
+      metadata: {
+        ...metadata,
+        blogTitle: translations.title.message,
+        blogDescription: translations.description.message,
+      },
+    };
+  });
+}
+
+export function getTranslationFiles(options: PluginOptions): TranslationFiles {
+  return [
+    {
+      path: 'options',
+      content: {
+        title: {
+          message: options.blogTitle,
+          description: 'The title for the blog used in SEO',
+        },
+        description: {
+          message: options.blogDescription,
+          description: 'The description for the blog used in SEO',
+        },
+        'sidebar.title': {
+          message: options.blogSidebarTitle,
+          description: 'The label for the left sidebar',
+        },
+      },
+    },
+  ];
+}
+
+export function translateContent(
+  content: BlogContent,
+  translationFiles: TranslationFiles,
+): BlogContent {
+  const [{content: optionsTranslations}] = translationFiles;
+  return {
+    ...content,
+    blogSidebarTitle: optionsTranslations['sidebar.title'].message,
+    blogListPaginated: translateListPage(
+      content.blogListPaginated,
+      optionsTranslations,
+    ),
+  };
+}

package/src/types.ts

@@ -5,76 +5,45 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import {
+import type {Tag} from '@docusaurus/utils';
+import type {
   BrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
+import type {
+  BlogPostFrontMatter,
+  Author,
+} from '@docusaurus/plugin-content-blog';
 
 export type BlogContentPaths = ContentPaths;
 
 export interface BlogContent {
+  blogSidebarTitle: string;
   blogPosts: BlogPost[];
   blogListPaginated: BlogPaginated[];
   blogTags: BlogTags;
   blogTagsListPath: string | null;
 }
 
-export interface DateLink {
-  date: Date;
-  link: string;
-}
-
-export type FeedType = 'rss' | 'atom';
-
-export type EditUrlFunction = (editUrlParams: {
-  blogDirPath: string;
-  blogPath: string;
-  permalink: string;
-  locale: string;
-}) => string | undefined;
-
-export interface PluginOptions extends RemarkAndRehypePluginOptions {
-  id?: string;
-  path: string;
-  routeBasePath: string;
-  include: string[];
-  postsPerPage: number;
-  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>;
-}
-
 export interface BlogTags {
-  [key: string]: BlogTag;
+  // TODO, the key is the tag slug/permalink
+  // This is due to legacy frontmatter: tags:
+  // [{label: "xyz", permalink: "/1"}, {label: "xyz", permalink: "/2"}]
+  // Soon we should forbid declaring permalink through frontmatter
+  [tagKey: string]: BlogTag;
 }
 
 export interface BlogTag {
   name: string;
-  items: string[];
+  items: string[]; // blog post permalinks
   permalink: string;
+  pages: BlogPaginated[];
 }
 
 export interface BlogPost {
   id: string;
   metadata: MetaData;
+  content: string;
 }
 
 export interface BlogPaginatedMetadata {
@@ -91,7 +60,7 @@ export interface BlogPaginatedMetadata {
 
 export interface BlogPaginated {
   metadata: BlogPaginatedMetadata;
-  items: string[];
+  items: string[]; // blog post permalinks
 }
 
 export interface MetaData {
@@ -100,13 +69,15 @@ export interface MetaData {
   description: string;
   date: Date;
   formattedDate: string;
-  tags: (Tag | string)[];
+  tags: Tag[];
   title: string;
   readingTime?: number;
   prevItem?: Paginator;
   nextItem?: Paginator;
   truncated: boolean;
   editUrl?: string;
+  authors: Author[];
+  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
 }
 
 export interface Paginator {
@@ -114,11 +85,6 @@ export interface Paginator {
   permalink: string;
 }
 
-export interface Tag {
-  label: string;
-  permalink: string;
-}
-
 export interface BlogItemsToMetadata {
   [key: string]: MetaData;
 }