@docusaurus/plugin-content-blog 2.0.0-beta.1 → 2.0.0-beta.10

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

package/src/translations.ts

@@ -0,0 +1,63 @@
+/**
+ * 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, PluginOptions, BlogPaginated} from './types';
+import type {TranslationFileContent, TranslationFiles} from '@docusaurus/types';
+
+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: optonsTranslations}] = translationFiles;
+  return {
+    ...content,
+    blogSidebarTitle: optonsTranslations['sidebar.title'].message,
+    blogListPaginated: translateListPage(
+      content.blogListPaginated,
+      optonsTranslations,
+    ),
+  };
+}

package/src/types.ts

@@ -6,27 +6,40 @@
  */
 
 import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import {
+import type {Tag} from '@docusaurus/utils';
+import type {
   BrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
+import {Overwrite} from 'utility-types';
+import {BlogPostFrontMatter} from './blogFrontMatter';
 
 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 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;
@@ -34,12 +47,33 @@ export type EditUrlFunction = (editUrlParams: {
   locale: string;
 }) => string | undefined;
 
-export interface PluginOptions extends RemarkAndRehypePluginOptions {
+// 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[];
-  postsPerPage: number;
+  exclude: string[];
+  postsPerPage: number | 'ALL';
   blogListComponent: string;
   blogPostComponent: string;
   blogTagsListComponent: string;
@@ -51,7 +85,7 @@ export interface PluginOptions extends RemarkAndRehypePluginOptions {
   truncateMarker: RegExp;
   showReadingTime: boolean;
   feedOptions: {
-    type?: [FeedType] | null;
+    type?: FeedType[] | null;
     title?: string;
     description?: string;
     copyright: string;
@@ -60,7 +94,16 @@ export interface PluginOptions extends RemarkAndRehypePluginOptions {
   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;
@@ -75,6 +118,7 @@ export interface BlogTag {
 export interface BlogPost {
   id: string;
   metadata: MetaData;
+  content: string;
 }
 
 export interface BlogPaginatedMetadata {
@@ -94,28 +138,37 @@ 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;
   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[];
 }
 
-export interface Paginator {
-  title: string;
-  permalink: string;
+export interface Assets {
+  image?: string;
+  authorsImageUrls: (string | undefined)[]; // Array of same size as the original MetaData.authors array
 }
 
-export interface Tag {
-  label: string;
+export interface Paginator {
+  title: string;
   permalink: string;
 }
 

package/src/__tests__/__snapshots__/generateBlogFeed.test.ts.snap

@@ -1,76 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`blogFeed atom should not show feed without posts 1`] = `null`;
-
-exports[`blogFeed atom shows feed item for each post 1`] = `
-"<?xml version=\\"1.0\\" encoding=\\"utf-8\\"?>
-<feed xmlns=\\"http://www.w3.org/2005/Atom\\">
-    <id>https://docusaurus.io/myBaseUrl/blog</id>
-    <title>Hello Blog</title>
-    <updated>2020-02-27T00:00:00.000Z</updated>
-    <generator>https://github.com/jpmonette/feed</generator>
-    <link rel=\\"alternate\\" href=\\"https://docusaurus.io/myBaseUrl/blog\\"/>
-    <subtitle>Hello Blog</subtitle>
-    <icon>https://docusaurus.io/myBaseUrl/image/favicon.ico</icon>
-    <rights>Copyright</rights>
-    <entry>
-        <title type=\\"html\\"><![CDATA[draft]]></title>
-        <id>draft</id>
-        <link href=\\"https://docusaurus.io/myBaseUrl/blog/draft\\"/>
-        <updated>2020-02-27T00:00:00.000Z</updated>
-        <summary type=\\"html\\"><![CDATA[this post should not be published yet]]></summary>
-    </entry>
-    <entry>
-        <title type=\\"html\\"><![CDATA[date-matter]]></title>
-        <id>date-matter</id>
-        <link href=\\"https://docusaurus.io/myBaseUrl/blog/date-matter\\"/>
-        <updated>2019-01-01T00:00:00.000Z</updated>
-        <summary type=\\"html\\"><![CDATA[date inside front matter]]></summary>
-    </entry>
-    <entry>
-        <title type=\\"html\\"><![CDATA[Happy 1st Birthday Slash! (translated)]]></title>
-        <id>Happy 1st Birthday Slash! (translated)</id>
-        <link href=\\"https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash\\"/>
-        <updated>2018-12-14T00:00:00.000Z</updated>
-        <summary type=\\"html\\"><![CDATA[Happy birthday! (translated)]]></summary>
-    </entry>
-</feed>"
-`;
-
-exports[`blogFeed rss should not show feed without posts 1`] = `null`;
-
-exports[`blogFeed rss shows feed item for each post 1`] = `
-"<?xml version=\\"1.0\\" encoding=\\"utf-8\\"?>
-<rss version=\\"2.0\\">
-    <channel>
-        <title>Hello Blog</title>
-        <link>https://docusaurus.io/myBaseUrl/blog</link>
-        <description>Hello Blog</description>
-        <lastBuildDate>Thu, 27 Feb 2020 00:00:00 GMT</lastBuildDate>
-        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
-        <generator>https://github.com/jpmonette/feed</generator>
-        <copyright>Copyright</copyright>
-        <item>
-            <title><![CDATA[draft]]></title>
-            <link>https://docusaurus.io/myBaseUrl/blog/draft</link>
-            <guid>draft</guid>
-            <pubDate>Thu, 27 Feb 2020 00:00:00 GMT</pubDate>
-            <description><![CDATA[this post should not be published yet]]></description>
-        </item>
-        <item>
-            <title><![CDATA[date-matter]]></title>
-            <link>https://docusaurus.io/myBaseUrl/blog/date-matter</link>
-            <guid>date-matter</guid>
-            <pubDate>Tue, 01 Jan 2019 00:00:00 GMT</pubDate>
-            <description><![CDATA[date inside front matter]]></description>
-        </item>
-        <item>
-            <title><![CDATA[Happy 1st Birthday Slash! (translated)]]></title>
-            <link>https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash</link>
-            <guid>Happy 1st Birthday Slash! (translated)</guid>
-            <pubDate>Fri, 14 Dec 2018 00:00:00 GMT</pubDate>
-            <description><![CDATA[Happy birthday! (translated)]]></description>
-        </item>
-    </channel>
-</rss>"
-`;