@docusaurus/plugin-content-blog 2.4.1 → 3.0.0-beta.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.4.1",
+  "version": "3.0.0-beta.0",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
   "scripts": {
     "build": "tsc",
-    "watch": "tsc --watch"
+    "watch": "tsc --watch",
+    "test:generate-build-snap": "yarn docusaurus build src/__tests__/__fixtures__/website --out-dir build-snap && yarn rimraf src/__tests__/__fixtures__/website/.docusaurus && yarn rimraf src/__tests__/__fixtures__/website/build-snap/assets && git add src/__tests__/__fixtures__/website/build-snap"
   },
   "repository": {
     "type": "git",
@@ -18,29 +19,30 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.4.1",
-    "@docusaurus/logger": "2.4.1",
-    "@docusaurus/mdx-loader": "2.4.1",
-    "@docusaurus/types": "2.4.1",
-    "@docusaurus/utils": "2.4.1",
-    "@docusaurus/utils-common": "2.4.1",
-    "@docusaurus/utils-validation": "2.4.1",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/logger": "3.0.0-beta.0",
+    "@docusaurus/mdx-loader": "3.0.0-beta.0",
+    "@docusaurus/types": "3.0.0-beta.0",
+    "@docusaurus/utils": "3.0.0-beta.0",
+    "@docusaurus/utils-common": "3.0.0-beta.0",
+    "@docusaurus/utils-validation": "3.0.0-beta.0",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
-    "fs-extra": "^10.1.0",
+    "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
-    "tslib": "^2.4.0",
+    "srcset": "^4.0.0",
+    "tslib": "^2.6.0",
     "unist-util-visit": "^2.0.3",
     "utility-types": "^3.10.0",
-    "webpack": "^5.73.0"
+    "webpack": "^5.88.1"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "60e657d8ae5a4a9ed1c2d777f9defd882cc12681"
+  "gitHead": "27a1e90d9fff88af90ecad35bea16d4d7230482a"
 }

package/src/blogUtils.ts

@@ -21,8 +21,11 @@ import {
   Globby,
   normalizeFrontMatterTags,
   groupTaggedItems,
+  getTagVisibility,
   getFileCommitDate,
   getContentPathList,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
@@ -96,6 +99,10 @@ export function paginateBlogPosts({
   return pages;
 }
 
+export function shouldBeListed(blogPost: BlogPost): boolean {
+  return !blogPost.metadata.unlisted;
+}
+
 export function getBlogTags({
   blogPosts,
   ...params
@@ -109,17 +116,23 @@ export function getBlogTags({
     blogPosts,
     (blogPost) => blogPost.metadata.tags,
   );
-
-  return _.mapValues(groups, ({tag, items: tagBlogPosts}) => ({
-    label: tag.label,
-    items: tagBlogPosts.map((item) => item.id),
-    permalink: tag.permalink,
-    pages: paginateBlogPosts({
-      blogPosts: tagBlogPosts,
-      basePageUrl: tag.permalink,
-      ...params,
-    }),
-  }));
+  return _.mapValues(groups, ({tag, items: tagBlogPosts}) => {
+    const tagVisibility = getTagVisibility({
+      items: tagBlogPosts,
+      isUnlisted: (item) => item.metadata.unlisted,
+    });
+    return {
+      label: tag.label,
+      items: tagVisibility.listedItems.map((item) => item.id),
+      permalink: tag.permalink,
+      pages: paginateBlogPosts({
+        blogPosts: tagVisibility.listedItems,
+        basePageUrl: tag.permalink,
+        ...params,
+      }),
+      unlisted: tagVisibility.unlisted,
+    };
+  });
 }
 
 const DATE_FILENAME_REGEX =
@@ -219,7 +232,10 @@ async function processBlogSourceFile(
 
   const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir);
 
-  if (frontMatter.draft && process.env.NODE_ENV === 'production') {
+  const draft = isDraft({frontMatter});
+  const unlisted = isUnlisted({frontMatter});
+
+  if (draft) {
     return undefined;
   }
 
@@ -326,6 +342,7 @@ async function processBlogSourceFile(
       hasTruncateMarker: truncateMarker.test(content),
       authors,
       frontMatter,
+      unlisted,
     },
     content,
   };
@@ -352,23 +369,25 @@ export async function generateBlogPosts(
     authorsMapPath: options.authorsMapPath,
   });
 
+  async function doProcessBlogSourceFile(blogSourceFile: string) {
+    try {
+      return await processBlogSourceFile(
+        blogSourceFile,
+        contentPaths,
+        context,
+        options,
+        authorsMap,
+      );
+    } catch (err) {
+      throw new Error(
+        `Processing of blog source file path=${blogSourceFile} failed.`,
+        {cause: err as Error},
+      );
+    }
+  }
+
   const blogPosts = (
-    await Promise.all(
-      blogSourceFiles.map(async (blogSourceFile: string) => {
-        try {
-          return await processBlogSourceFile(
-            blogSourceFile,
-            contentPaths,
-            context,
-            options,
-            authorsMap,
-          );
-        } catch (err) {
-          logger.error`Processing of blog source file path=${blogSourceFile} failed.`;
-          throw err;
-        }
-      }),
-    )
+    await Promise.all(blogSourceFiles.map(doProcessBlogSourceFile))
   ).filter(Boolean) as BlogPost[];
 
   blogPosts.sort(

package/src/feed.ts

@@ -9,6 +9,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
 import {Feed, type Author as FeedAuthor} from 'feed';
+import * as srcset from 'srcset';
 import {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
 import {blogPostContainerID} from '@docusaurus/utils-common';
 import {load as cheerioLoad} from 'cheerio';
@@ -42,7 +43,12 @@ async function generateBlogFeed({
   const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
   const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, routeBasePath]);
 
-  const updated = blogPosts[0]?.metadata.date;
+  const blogPostsForFeed =
+    feedOptions.limit === false || feedOptions.limit === null
+      ? blogPosts
+      : blogPosts.slice(0, feedOptions.limit);
+
+  const updated = blogPostsForFeed[0]?.metadata.date;
 
   const feed = new Feed({
     id: blogBaseUrl,
@@ -59,7 +65,7 @@ async function generateBlogFeed({
     options.feedOptions.createFeedItems ?? defaultCreateFeedItems;
 
   const feedItems = await createFeedItems({
-    blogPosts,
+    blogPosts: blogPostsForFeed,
     siteConfig,
     outDir,
     defaultCreateFeedItems,
@@ -105,11 +111,41 @@ async function defaultCreateFeedItems({
       );
       const $ = cheerioLoad(content);
 
-      const link = normalizeUrl([siteUrl, permalink]);
+      const blogPostAbsoluteUrl = normalizeUrl([siteUrl, permalink]);
+
+      const toAbsoluteUrl = (src: string) =>
+        String(new URL(src, blogPostAbsoluteUrl));
+
+      // Make links and image urls absolute
+      // See https://github.com/facebook/docusaurus/issues/9136
+      $(`div#${blogPostContainerID} a, div#${blogPostContainerID} img`).each(
+        (_, elm) => {
+          if (elm.tagName === 'a') {
+            const {href} = elm.attribs;
+            if (href) {
+              elm.attribs.href = toAbsoluteUrl(href);
+            }
+          } else if (elm.tagName === 'img') {
+            const {src, srcset: srcsetAttr} = elm.attribs;
+            if (src) {
+              elm.attribs.src = toAbsoluteUrl(src);
+            }
+            if (srcsetAttr) {
+              elm.attribs.srcset = srcset.stringify(
+                srcset.parse(srcsetAttr).map((props) => ({
+                  ...props,
+                  url: toAbsoluteUrl(props.url),
+                })),
+              );
+            }
+          }
+        },
+      );
+
       const feedItem: BlogFeedItem = {
         title: metadataTitle,
-        id: link,
-        link,
+        id: blogPostAbsoluteUrl,
+        link: blogPostAbsoluteUrl,
         date,
         description,
         // Atom feed demands the "term", while other feeds use "name"
@@ -158,8 +194,15 @@ async function createBlogFeedFile({
   }
 }
 
+function shouldBeInFeed(blogPost: BlogPost): boolean {
+  const excluded =
+    blogPost.metadata.frontMatter.draft ||
+    blogPost.metadata.frontMatter.unlisted;
+  return !excluded;
+}
+
 export async function createBlogFeedFiles({
-  blogPosts,
+  blogPosts: allBlogPosts,
   options,
   siteConfig,
   outDir,
@@ -171,6 +214,8 @@ export async function createBlogFeedFiles({
   outDir: string;
   locale: string;
 }): Promise<void> {
+  const blogPosts = allBlogPosts.filter(shouldBeInFeed);
+
   const feed = await generateBlogFeed({
     blogPosts,
     options,

package/src/frontMatter.ts

@@ -11,6 +11,7 @@ import {
   validateFrontMatter,
   FrontMatterTagsSchema,
   FrontMatterTOCHeadingLevels,
+  ContentVisibilitySchema,
 } from '@docusaurus/utils-validation';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
@@ -32,7 +33,6 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   title: Joi.string().allow(''),
   description: Joi.string().allow(''),
   tags: FrontMatterTagsSchema,
-  draft: Joi.boolean(),
   date: Joi.date().raw(),
 
   // New multi-authors front matter:
@@ -69,10 +69,12 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   hide_table_of_contents: Joi.boolean(),
 
   ...FrontMatterTOCHeadingLevels,
-}).messages({
-  'deprecate.error':
-    '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
-});
+})
+  .messages({
+    'deprecate.error':
+      '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
+  })
+  .concat(ContentVisibilitySchema);
 
 export function validateBlogPostFrontMatter(frontMatter: {
   [key: string]: unknown;

package/src/index.ts

@@ -18,19 +18,19 @@ import {
   getContentPathList,
   getDataFilePath,
   DEFAULT_PLUGIN_ID,
-  type TagsListItem,
-  type TagModule,
 } from '@docusaurus/utils';
 import {
   generateBlogPosts,
   getSourceToPermalink,
   getBlogTags,
   paginateBlogPosts,
+  shouldBeListed,
 } from './blogUtils';
 import footnoteIDFixer from './remark/footnoteIDFixer';
 import {translateContent, getTranslationFiles} from './translations';
 import {createBlogFeedFiles} from './feed';
 
+import {toTagProp, toTagsProp} from './props';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
 import type {
@@ -112,6 +112,7 @@ export default async function pluginContentBlog(
       const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
       const blogTagsListPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
       const blogPosts = await generateBlogPosts(contentPaths, context, options);
+      const listedBlogPosts = blogPosts.filter(shouldBeListed);
 
       if (!blogPosts.length) {
         return {
@@ -125,8 +126,8 @@ export default async function pluginContentBlog(
       }
 
       // Colocate next and prev metadata.
-      blogPosts.forEach((blogPost, index) => {
-        const prevItem = index > 0 ? blogPosts[index - 1] : null;
+      listedBlogPosts.forEach((blogPost, index) => {
+        const prevItem = index > 0 ? listedBlogPosts[index - 1] : null;
         if (prevItem) {
           blogPost.metadata.prevItem = {
             title: prevItem.metadata.title,
@@ -135,7 +136,9 @@ export default async function pluginContentBlog(
         }
 
         const nextItem =
-          index < blogPosts.length - 1 ? blogPosts[index + 1] : null;
+          index < listedBlogPosts.length - 1
+            ? listedBlogPosts[index + 1]
+            : null;
         if (nextItem) {
           blogPost.metadata.nextItem = {
             title: nextItem.metadata.title,
@@ -145,7 +148,7 @@ export default async function pluginContentBlog(
       });
 
       const blogListPaginated: BlogPaginated[] = paginateBlogPosts({
-        blogPosts,
+        blogPosts: listedBlogPosts,
         blogTitle,
         blogDescription,
         postsPerPageOption,
@@ -242,6 +245,7 @@ export default async function pluginContentBlog(
             items: sidebarBlogPosts.map((blogPost) => ({
               title: blogPost.metadata.title,
               permalink: blogPost.metadata.permalink,
+              unlisted: blogPost.metadata.unlisted,
             })),
           },
           null,
@@ -303,17 +307,10 @@ export default async function pluginContentBlog(
       }
 
       async function createTagsListPage() {
-        const tagsProp: TagsListItem[] = Object.values(blogTags).map((tag) => ({
-          label: tag.label,
-          permalink: tag.permalink,
-          count: tag.items.length,
-        }));
-
         const tagsPropPath = await createData(
           `${docuHash(`${blogTagsListPath}-tags`)}.json`,
-          JSON.stringify(tagsProp, null, 2),
+          JSON.stringify(toTagsProp({blogTags}), null, 2),
         );
-
         addRoute({
           path: blogTagsListPath,
           component: blogTagsListComponent,
@@ -329,15 +326,9 @@ export default async function pluginContentBlog(
         await Promise.all(
           tag.pages.map(async (blogPaginated) => {
             const {metadata, items} = blogPaginated;
-            const tagProp: TagModule = {
-              label: tag.label,
-              permalink: tag.permalink,
-              allTagsPath: blogTagsListPath,
-              count: tag.items.length,
-            };
             const tagPropPath = await createData(
               `${docuHash(metadata.permalink)}.json`,
-              JSON.stringify(tagProp, null, 2),
+              JSON.stringify(toTagProp({tag, blogTagsListPath}), null, 2),
             );
 
             const listMetadataPath = await createData(
@@ -368,7 +359,7 @@ export default async function pluginContentBlog(
       return translateContent(content, translationFiles);
     },
 
-    configureWebpack(_config, isServer, {getJSLoader}, content) {
+    configureWebpack(_config, isServer, utils, content) {
       const {
         admonitions,
         rehypePlugins,
@@ -408,7 +399,6 @@ export default async function pluginContentBlog(
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
               use: [
-                getJSLoader({isServer}),
                 {
                   loader: require.resolve('@docusaurus/mdx-loader'),
                   options: {

package/src/options.ts

@@ -10,6 +10,7 @@ import {
   RemarkPluginsSchema,
   RehypePluginsSchema,
   AdmonitionsSchema,
+  RouteBasePathSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
@@ -21,11 +22,11 @@ import type {
 import type {OptionValidationContext} from '@docusaurus/types';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
-  feedOptions: {type: ['rss', 'atom'], copyright: ''},
+  feedOptions: {type: ['rss', 'atom'], copyright: '', limit: 20},
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: true,
-  truncateMarker: /<!--\s*truncate\s*-->/,
+  truncateMarker: /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/,
   rehypePlugins: [],
   remarkPlugins: [],
   showReadingTime: true,
@@ -56,10 +57,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   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),
+  routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
   tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
@@ -125,6 +123,9 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     }),
     language: Joi.string(),
     createFeedItems: Joi.function(),
+    limit: Joi.alternatives()
+      .try(Joi.number(), Joi.valid(null), Joi.valid(false))
+      .default(DEFAULT_OPTIONS.feedOptions.limit),
   }).default(DEFAULT_OPTIONS.feedOptions),
   authorsMapPath: Joi.string().default(DEFAULT_OPTIONS.authorsMapPath),
   readingTime: Joi.function().default(() => DEFAULT_OPTIONS.readingTime),

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

@@ -97,6 +97,10 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      * Marks the post as draft and excludes it from the production build.
      */
     draft?: boolean;
+    /**
+     * Marks the post as unlisted and visibly hides it unless directly accessed.
+     */
+    unlisted?: boolean;
     /**
      * Will override the default publish date inferred from git/filename. Yaml
      * only converts standard yyyy-MM-dd format to dates, so this may stay as a
@@ -229,6 +233,10 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
     /** Tags, normalized. */
     readonly tags: Tag[];
+    /**
+     * Marks the post as unlisted and visibly hides it unless directly accessed.
+     */
+    readonly unlisted: boolean;
   };
   /**
    * @returns The edit URL that's directly plugged into metadata.
@@ -264,6 +272,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     language?: string;
     /** Allow control over the construction of BlogFeedItems */
     createFeedItems?: CreateFeedItemsFn;
+    /** Limits the feed to the specified number of posts, false|null for all */
+    limit?: number | false | null;
   };
 
   type DefaultCreateFeedItemsParams = {
@@ -432,9 +442,15 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     }
   >;
 
+  export type BlogSidebarItem = {
+    title: string;
+    permalink: string;
+    unlisted: boolean;
+  };
+
   export type BlogSidebar = {
     title: string;
-    items: {title: string; permalink: string}[];
+    items: BlogSidebarItem[];
   };
 
   export type BlogContent = {
@@ -453,6 +469,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     /** Blog post permalinks. */
     items: string[];
     pages: BlogPaginated[];
+    unlisted: boolean;
   };
 
   export type BlogPost = {

package/src/props.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 {TagsListItem, TagModule} from '@docusaurus/utils';
+import type {BlogTag, BlogTags} from '@docusaurus/plugin-content-blog';
+
+export function toTagsProp({blogTags}: {blogTags: BlogTags}): TagsListItem[] {
+  return Object.values(blogTags)
+    .filter((tag) => !tag.unlisted)
+    .map((tag) => ({
+      label: tag.label,
+      permalink: tag.permalink,
+      count: tag.items.length,
+    }));
+}
+
+export function toTagProp({
+  blogTagsListPath,
+  tag,
+}: {
+  blogTagsListPath: string;
+  tag: BlogTag;
+}): TagModule {
+  return {
+    label: tag.label,
+    permalink: tag.permalink,
+    allTagsPath: blogTagsListPath,
+    count: tag.items.length,
+    unlisted: tag.unlisted,
+  };
+}

package/src/remark/footnoteIDFixer.ts

@@ -7,6 +7,7 @@
 
 import visit from 'unist-util-visit';
 import {simpleHash} from '@docusaurus/utils';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 import type {FootnoteReference, FootnoteDefinition} from 'mdast';