@docusaurus/plugin-content-blog 2.4.0 → 3.0.0-alpha.0

package/lib/authors.d.ts

@@ -6,7 +6,7 @@
  */
 import type { BlogContentPaths } from './types';
 import type { Author, BlogPostFrontMatter } from '@docusaurus/plugin-content-blog';
-export declare type AuthorsMap = {
+export type AuthorsMap = {
     [authorKey: string]: Author;
 };
 export declare function validateAuthorsMap(content: unknown): AuthorsMap;
@@ -14,7 +14,7 @@ export declare function getAuthorsMap(params: {
     authorsMapPath: string;
     contentPaths: BlogContentPaths;
 }): Promise<AuthorsMap | undefined>;
-declare type AuthorsParam = {
+type AuthorsParam = {
     frontMatter: BlogPostFrontMatter;
     authorsMap: AuthorsMap | undefined;
 };

package/lib/blogUtils.d.ts

@@ -18,20 +18,21 @@ export declare function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, b
     blogDescription: string;
     postsPerPageOption: number | 'ALL';
 }): BlogPaginated[];
+export declare function shouldBeListed(blogPost: BlogPost): boolean;
 export declare function getBlogTags({ blogPosts, ...params }: {
     blogPosts: BlogPost[];
     blogTitle: string;
     blogDescription: string;
     postsPerPageOption: number | 'ALL';
 }): BlogTags;
-declare type ParsedBlogFileName = {
+type ParsedBlogFileName = {
     date: Date | undefined;
     text: string;
     slug: string;
 };
 export declare function parseBlogFileName(blogSourceRelative: string): ParsedBlogFileName;
 export declare function generateBlogPosts(contentPaths: BlogContentPaths, context: LoadContext, options: PluginOptions): Promise<BlogPost[]>;
-export declare type LinkifyParams = {
+export type LinkifyParams = {
     filePath: string;
     fileString: string;
 } & Pick<BlogMarkdownLoaderOptions, 'sourceToPermalink' | 'siteDir' | 'contentPaths' | 'onBrokenMarkdownLink'>;

package/lib/blogUtils.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.linkify = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.paginateBlogPosts = exports.getSourceToPermalink = exports.truncate = void 0;
+exports.linkify = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.shouldBeListed = exports.paginateBlogPosts = exports.getSourceToPermalink = exports.truncate = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -55,18 +55,29 @@ function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription,
     return pages;
 }
 exports.paginateBlogPosts = paginateBlogPosts;
+function shouldBeListed(blogPost) {
+    return !blogPost.metadata.unlisted;
+}
+exports.shouldBeListed = shouldBeListed;
 function getBlogTags({ blogPosts, ...params }) {
     const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
-    return lodash_1.default.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 lodash_1.default.mapValues(groups, ({ tag, items: tagBlogPosts }) => {
+        const tagVisibility = (0, utils_1.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,
+        };
+    });
 }
 exports.getBlogTags = getBlogTags;
 const DATE_FILENAME_REGEX = /^(?<folder>.*)(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(?:\/index)?.mdx?$/;
@@ -125,7 +136,9 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
     const blogSourceAbsolute = path_1.default.join(blogDirPath, blogSourceRelative);
     const { frontMatter, content, contentTitle, excerpt } = await parseBlogPostMarkdownFile(blogSourceAbsolute);
     const aliasedSource = (0, utils_1.aliasedSitePath)(blogSourceAbsolute, siteDir);
-    if (frontMatter.draft && process.env.NODE_ENV === 'production') {
+    const draft = (0, utils_1.isDraft)({ frontMatter });
+    const unlisted = (0, utils_1.isUnlisted)({ frontMatter });
+    if (draft) {
         return undefined;
     }
     if (frontMatter.id) {
@@ -213,6 +226,7 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
             hasTruncateMarker: truncateMarker.test(content),
             authors,
             frontMatter,
+            unlisted,
         },
         content,
     };
@@ -230,15 +244,15 @@ async function generateBlogPosts(contentPaths, context, options) {
         contentPaths,
         authorsMapPath: options.authorsMapPath,
     });
-    const blogPosts = (await Promise.all(blogSourceFiles.map(async (blogSourceFile) => {
+    async function doProcessBlogSourceFile(blogSourceFile) {
         try {
             return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, authorsMap);
         }
         catch (err) {
-            logger_1.default.error `Processing of blog source file path=${blogSourceFile} failed.`;
-            throw err;
+            throw new Error(`Processing of blog source file path=${blogSourceFile} failed.`, { cause: err });
         }
-    }))).filter(Boolean);
+    }
+    const blogPosts = (await Promise.all(blogSourceFiles.map(doProcessBlogSourceFile))).filter(Boolean);
     blogPosts.sort((a, b) => b.metadata.date.getTime() - a.metadata.date.getTime());
     if (options.sortPosts === 'ascending') {
         return blogPosts.reverse();

package/lib/feed.d.ts

@@ -6,7 +6,7 @@
  */
 import type { DocusaurusConfig } from '@docusaurus/types';
 import type { PluginOptions, BlogPost } from '@docusaurus/plugin-content-blog';
-export declare function createBlogFeedFiles({ blogPosts, options, siteConfig, outDir, locale, }: {
+export declare function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, }: {
     blogPosts: BlogPost[];
     options: PluginOptions;
     siteConfig: DocusaurusConfig;

package/lib/feed.js

@@ -93,7 +93,13 @@ async function createBlogFeedFile({ feed, feedType, generatePath, }) {
         throw err;
     }
 }
-async function createBlogFeedFiles({ blogPosts, options, siteConfig, outDir, locale, }) {
+function shouldBeInFeed(blogPost) {
+    const excluded = blogPost.metadata.frontMatter.draft ||
+        blogPost.metadata.frontMatter.unlisted;
+    return !excluded;
+}
+async function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, }) {
+    const blogPosts = allBlogPosts.filter(shouldBeInFeed);
     const feed = await generateBlogFeed({
         blogPosts,
         options,

package/lib/frontMatter.js

@@ -23,7 +23,6 @@ const BlogFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     title: utils_validation_1.JoiFrontMatter.string().allow(''),
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     tags: utils_validation_1.FrontMatterTagsSchema,
-    draft: utils_validation_1.JoiFrontMatter.boolean(),
     date: utils_validation_1.JoiFrontMatter.date().raw(),
     // New multi-authors front matter:
     authors: utils_validation_1.JoiFrontMatter.alternatives()
@@ -53,9 +52,11 @@ const BlogFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
     hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
     ...utils_validation_1.FrontMatterTOCHeadingLevels,
-}).messages({
+})
+    .messages({
     'deprecate.error': '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
-});
+})
+    .concat(utils_validation_1.ContentVisibilitySchema);
 function validateBlogPostFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, BlogFrontMatterSchema);
 }

package/lib/index.js

@@ -15,6 +15,7 @@ const blogUtils_1 = require("./blogUtils");
 const footnoteIDFixer_1 = tslib_1.__importDefault(require("./remark/footnoteIDFixer"));
 const translations_1 = require("./translations");
 const feed_1 = require("./feed");
+const props_1 = require("./props");
 async function pluginContentBlog(context, options) {
     const { siteDir, siteConfig, generatedFilesDir, localizationDir, i18n: { currentLocale }, } = context;
     const { onBrokenMarkdownLinks, baseUrl } = siteConfig;
@@ -50,6 +51,7 @@ async function pluginContentBlog(context, options) {
             const baseBlogUrl = (0, utils_1.normalizeUrl)([baseUrl, routeBasePath]);
             const blogTagsListPath = (0, utils_1.normalizeUrl)([baseBlogUrl, tagsBasePath]);
             const blogPosts = await (0, blogUtils_1.generateBlogPosts)(contentPaths, context, options);
+            const listedBlogPosts = blogPosts.filter(blogUtils_1.shouldBeListed);
             if (!blogPosts.length) {
                 return {
                     blogSidebarTitle,
@@ -61,15 +63,17 @@ async function pluginContentBlog(context, options) {
                 };
             }
             // 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,
                         permalink: prevItem.metadata.permalink,
                     };
                 }
-                const nextItem = index < blogPosts.length - 1 ? blogPosts[index + 1] : null;
+                const nextItem = index < listedBlogPosts.length - 1
+                    ? listedBlogPosts[index + 1]
+                    : null;
                 if (nextItem) {
                     blogPost.metadata.nextItem = {
                         title: nextItem.metadata.title,
@@ -78,7 +82,7 @@ async function pluginContentBlog(context, options) {
                 }
             });
             const blogListPaginated = (0, blogUtils_1.paginateBlogPosts)({
-                blogPosts,
+                blogPosts: listedBlogPosts,
                 blogTitle,
                 blogDescription,
                 postsPerPageOption,
@@ -146,6 +150,7 @@ async function pluginContentBlog(context, options) {
                 items: sidebarBlogPosts.map((blogPost) => ({
                     title: blogPost.metadata.title,
                     permalink: blogPost.metadata.permalink,
+                    unlisted: blogPost.metadata.unlisted,
                 })),
             }, null, 2));
             // Create routes for blog entries.
@@ -187,12 +192,7 @@ async function pluginContentBlog(context, options) {
                 return;
             }
             async function createTagsListPage() {
-                const tagsProp = Object.values(blogTags).map((tag) => ({
-                    label: tag.label,
-                    permalink: tag.permalink,
-                    count: tag.items.length,
-                }));
-                const tagsPropPath = await createData(`${(0, utils_1.docuHash)(`${blogTagsListPath}-tags`)}.json`, JSON.stringify(tagsProp, null, 2));
+                const tagsPropPath = await createData(`${(0, utils_1.docuHash)(`${blogTagsListPath}-tags`)}.json`, JSON.stringify((0, props_1.toTagsProp)({ blogTags }), null, 2));
                 addRoute({
                     path: blogTagsListPath,
                     component: blogTagsListComponent,
@@ -206,13 +206,7 @@ async function pluginContentBlog(context, options) {
             async function createTagPostsListPage(tag) {
                 await Promise.all(tag.pages.map(async (blogPaginated) => {
                     const { metadata, items } = blogPaginated;
-                    const tagProp = {
-                        label: tag.label,
-                        permalink: tag.permalink,
-                        allTagsPath: blogTagsListPath,
-                        count: tag.items.length,
-                    };
-                    const tagPropPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}.json`, JSON.stringify(tagProp, null, 2));
+                    const tagPropPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}.json`, JSON.stringify((0, props_1.toTagProp)({ tag, blogTagsListPath }), null, 2));
                     const listMetadataPath = await createData(`${(0, utils_1.docuHash)(metadata.permalink)}-list.json`, JSON.stringify(metadata, null, 2));
                     addRoute({
                         path: metadata.permalink,
@@ -233,7 +227,7 @@ async function pluginContentBlog(context, options) {
         translateContent({ content, translationFiles }) {
             return (0, translations_1.translateContent)(content, translationFiles);
         },
-        configureWebpack(_config, isServer, { getJSLoader }, content) {
+        configureWebpack(_config, isServer, utils, content) {
             const { admonitions, rehypePlugins, remarkPlugins, truncateMarker, beforeDefaultRemarkPlugins, beforeDefaultRehypePlugins, } = options;
             const markdownLoaderOptions = {
                 siteDir,
@@ -262,7 +256,6 @@ async function pluginContentBlog(context, options) {
                                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                                 .map(utils_1.addTrailingPathSeparator),
                             use: [
-                                getJSLoader({ isServer }),
                                 {
                                     loader: require.resolve('@docusaurus/mdx-loader'),
                                     options: {

package/lib/options.js

@@ -14,7 +14,7 @@ exports.DEFAULT_OPTIONS = {
     beforeDefaultRehypePlugins: [],
     beforeDefaultRemarkPlugins: [],
     admonitions: true,
-    truncateMarker: /<!--\s*truncate\s*-->/,
+    truncateMarker: /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/,
     rehypePlugins: [],
     remarkPlugins: [],
     showReadingTime: true,
@@ -44,10 +44,7 @@ const PluginOptionSchema = utils_validation_1.Joi.object({
     archiveBasePath: utils_validation_1.Joi.string()
         .default(exports.DEFAULT_OPTIONS.archiveBasePath)
         .allow(null),
-    routeBasePath: utils_validation_1.Joi.string()
-        // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
-        // .allow('')
-        .default(exports.DEFAULT_OPTIONS.routeBasePath),
+    routeBasePath: utils_validation_1.RouteBasePathSchema.default(exports.DEFAULT_OPTIONS.routeBasePath),
     tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
     include: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.include),
     exclude: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.exclude),

package/lib/props.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function toTagsProp({ blogTags }: {
+    blogTags: BlogTags;
+}): TagsListItem[];
+export declare function toTagProp({ blogTagsListPath, tag, }: {
+    blogTagsListPath: string;
+    tag: BlogTag;
+}): TagModule;

package/lib/props.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTagProp = exports.toTagsProp = void 0;
+function toTagsProp({ blogTags }) {
+    return Object.values(blogTags)
+        .filter((tag) => !tag.unlisted)
+        .map((tag) => ({
+        label: tag.label,
+        permalink: tag.permalink,
+        count: tag.items.length,
+    }));
+}
+exports.toTagsProp = toTagsProp;
+function toTagProp({ blogTagsListPath, tag, }) {
+    return {
+        label: tag.label,
+        permalink: tag.permalink,
+        allTagsPath: blogTagsListPath,
+        count: tag.items.length,
+        unlisted: tag.unlisted,
+    };
+}
+exports.toTagProp = toTagProp;

package/lib/types.d.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BrokenMarkdownLink, ContentPaths } from '@docusaurus/utils';
-export declare type BlogContentPaths = ContentPaths;
-export declare type BlogBrokenMarkdownLink = BrokenMarkdownLink<BlogContentPaths>;
-export declare type BlogMarkdownLoaderOptions = {
+export type BlogContentPaths = ContentPaths;
+export type BlogBrokenMarkdownLink = BrokenMarkdownLink<BlogContentPaths>;
+export type BlogMarkdownLoaderOptions = {
     siteDir: string;
     contentPaths: BlogContentPaths;
     truncateMarker: RegExp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "2.4.0",
+  "version": "3.0.0-alpha.0",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -18,29 +18,29 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.4.0",
-    "@docusaurus/logger": "2.4.0",
-    "@docusaurus/mdx-loader": "2.4.0",
-    "@docusaurus/types": "2.4.0",
-    "@docusaurus/utils": "2.4.0",
-    "@docusaurus/utils-common": "2.4.0",
-    "@docusaurus/utils-validation": "2.4.0",
+    "@docusaurus/core": "3.0.0-alpha.0",
+    "@docusaurus/logger": "3.0.0-alpha.0",
+    "@docusaurus/mdx-loader": "3.0.0-alpha.0",
+    "@docusaurus/types": "3.0.0-alpha.0",
+    "@docusaurus/utils": "3.0.0-alpha.0",
+    "@docusaurus/utils-common": "3.0.0-alpha.0",
+    "@docusaurus/utils-validation": "3.0.0-alpha.0",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
-    "fs-extra": "^10.1.0",
+    "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
-    "tslib": "^2.4.0",
+    "tslib": "^2.5.0",
     "unist-util-visit": "^2.0.3",
     "utility-types": "^3.10.0",
-    "webpack": "^5.73.0"
+    "webpack": "^5.76.0"
   },
   "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": "898b85ef134cc43bf3b1209aad0ca8cdcfb214c5"
+  "gitHead": "7327f7ff880ed97ad7855744e59c9c55d467a950"
 }

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

@@ -158,8 +158,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 +178,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';
@@ -25,7 +26,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   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),

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.
@@ -432,9 +440,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 +467,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';