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

package/src/feed.ts

@@ -0,0 +1,169 @@
+/**
+ * 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, type Author as FeedAuthor, type Item as FeedItem} from 'feed';
+import {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
+import {load as cheerioLoad} from 'cheerio';
+import type {DocusaurusConfig} from '@docusaurus/types';
+import path from 'path';
+import fs from 'fs-extra';
+import type {
+  FeedType,
+  PluginOptions,
+  Author,
+  BlogPost,
+} from '@docusaurus/plugin-content-blog';
+import {blogPostContainerID} from '@docusaurus/utils-common';
+
+async function generateBlogFeed({
+  blogPosts,
+  options,
+  siteConfig,
+  outDir,
+  locale,
+}: {
+  blogPosts: BlogPost[];
+  options: PluginOptions;
+  siteConfig: DocusaurusConfig;
+  outDir: string;
+  locale: string;
+}): 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]?.metadata.date;
+
+  const feed = new Feed({
+    id: blogBaseUrl,
+    title: feedOptions.title ?? `${title} Blog`,
+    updated,
+    language: feedOptions.language ?? locale,
+    link: blogBaseUrl,
+    description: feedOptions.description ?? `${siteConfig.title} Blog`,
+    favicon: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
+    copyright: feedOptions.copyright,
+  });
+
+  function toFeedAuthor(author: Author): FeedAuthor {
+    return {name: author.name, link: author.url, email: author.email};
+  }
+
+  await Promise.all(
+    blogPosts.map(async (post) => {
+      const {
+        id,
+        metadata: {
+          title: metadataTitle,
+          permalink,
+          date,
+          description,
+          authors,
+          tags,
+        },
+      } = post;
+
+      const content = await readOutputHTMLFile(
+        permalink.replace(siteConfig.baseUrl, ''),
+        outDir,
+        siteConfig.trailingSlash,
+      );
+      const $ = cheerioLoad(content);
+
+      const feedItem: FeedItem = {
+        title: metadataTitle,
+        id,
+        link: normalizeUrl([siteUrl, permalink]),
+        date,
+        description,
+        // 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;
+      }
+
+      return feedItem;
+    }),
+  ).then((items) => items.forEach(feed.addItem));
+
+  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,
+  locale,
+}: {
+  blogPosts: BlogPost[];
+  options: PluginOptions;
+  siteConfig: DocusaurusConfig;
+  outDir: string;
+  locale: string;
+}): Promise<void> {
+  const feed = await generateBlogFeed({
+    blogPosts,
+    options,
+    siteConfig,
+    outDir,
+    locale,
+  });
+
+  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/frontMatter.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 {
+  JoiFrontMatter as Joi, // Custom instance for front matter
+  URISchema,
+  validateFrontMatter,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
+} from '@docusaurus/utils-validation';
+import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
+
+const BlogPostFrontMatterAuthorSchema = Joi.object({
+  key: Joi.string(),
+  name: Joi.string(),
+  title: Joi.string(),
+  url: URISchema,
+  imageURL: Joi.string(),
+})
+  .or('key', 'name', 'imageURL')
+  .rename('image_url', 'imageURL', {alias: true});
+
+const FrontMatterAuthorErrorMessage =
+  '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).';
+
+const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
+  id: Joi.string(),
+  title: Joi.string().allow(''),
+  description: Joi.string().allow(''),
+  tags: FrontMatterTagsSchema,
+  draft: Joi.boolean(),
+  date: Joi.date().raw(),
+
+  // New multi-authors front matter:
+  authors: Joi.alternatives()
+    .try(
+      Joi.string(),
+      BlogPostFrontMatterAuthorSchema,
+      Joi.array()
+        .items(Joi.string(), BlogPostFrontMatterAuthorSchema)
+        .messages({
+          'array.sparse': FrontMatterAuthorErrorMessage,
+          'array.includes': FrontMatterAuthorErrorMessage,
+        }),
+    )
+    .messages({
+      'alternatives.match': FrontMatterAuthorErrorMessage,
+    }),
+  // Legacy author front matter
+  author: Joi.string(),
+  author_title: Joi.string(),
+  author_url: URISchema,
+  author_image_url: URISchema,
+  // TODO enable deprecation warnings later
+  authorURL: URISchema,
+  // .warning('deprecate.error', { alternative: '"author_url"'}),
+  authorTitle: Joi.string(),
+  // .warning('deprecate.error', { alternative: '"author_title"'}),
+  authorImageURL: URISchema,
+  // .warning('deprecate.error', { alternative: '"author_image_url"'}),
+
+  slug: Joi.string(),
+  image: URISchema,
+  keywords: Joi.array().items(Joi.string().required()),
+  hide_table_of_contents: Joi.boolean(),
+
+  ...FrontMatterTOCHeadingLevels,
+}).messages({
+  'deprecate.error':
+    '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
+});
+
+export function validateBlogPostFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): BlogPostFrontMatter {
+  return validateFrontMatter(frontMatter, BlogFrontMatterSchema);
+}