feat(docs,blog,pages): add support for "unlisted" front matter - hide md content in production (#8004)

Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap

@@ -19,6 +19,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = `
     "source": "@site/src/pages/hello/index.md",
     "title": "Index",
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "description": "my MDX page",
@@ -30,6 +31,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = `
     "source": "@site/src/pages/hello/mdxPage.mdx",
     "title": "MDX page",
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "permalink": "/hello/translatedJs",
@@ -43,6 +45,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = `
     "source": "@site/src/pages/hello/translatedMd.md",
     "title": undefined,
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "permalink": "/hello/world",
@@ -71,6 +74,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat
     "source": "@site/src/pages/hello/index.md",
     "title": "Index",
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "description": "my MDX page",
@@ -82,6 +86,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat
     "source": "@site/src/pages/hello/mdxPage.mdx",
     "title": "MDX page",
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "permalink": "/fr/hello/translatedJs",
@@ -95,6 +100,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat
     "source": "@site/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md",
     "title": undefined,
     "type": "mdx",
+    "unlisted": false,
   },
   {
     "permalink": "/fr/hello/world",

packages/docusaurus-plugin-content-pages/src/frontMatter.ts

@@ -9,6 +9,7 @@ import {
   Joi,
   validateFrontMatter,
   FrontMatterTOCHeadingLevels,
+  ContentVisibilitySchema,
 } from '@docusaurus/utils-validation';
 import type {FrontMatter} from '@docusaurus/plugin-content-pages';
 
@@ -18,7 +19,7 @@ const PageFrontMatterSchema = Joi.object<FrontMatter>({
   wrapperClassName: Joi.string(),
   hide_table_of_contents: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
-});
+}).concat(ContentVisibilitySchema);
 
 export function validatePageFrontMatter(frontMatter: {
   [key: string]: unknown;

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -20,6 +20,8 @@ import {
   normalizeUrl,
   DEFAULT_PLUGIN_ID,
   parseMarkdownString,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 import {validatePageFrontMatter} from './frontMatter';
 
@@ -82,7 +84,9 @@ export default function pluginContentPages(
         ignore: options.exclude,
       });
 
-      async function toMetadata(relativeSource: string): Promise<Metadata> {
+      async function processPageSourceFile(
+        relativeSource: string,
+      ): Promise<Metadata | undefined> {
         // Lookup in localized folder in priority
         const contentPath = await getFolderContainingFile(
           getContentPathList(contentPaths),
@@ -110,6 +114,12 @@ export default function pluginContentPages(
           excerpt,
         } = parseMarkdownString(content);
         const frontMatter = validatePageFrontMatter(unsafeFrontMatter);
+
+        if (isDraft({frontMatter})) {
+          return undefined;
+        }
+        const unlisted = isUnlisted({frontMatter});
+
         return {
           type: 'mdx',
           permalink,
@@ -117,10 +127,24 @@ export default function pluginContentPages(
           title: frontMatter.title ?? contentTitle,
           description: frontMatter.description ?? excerpt,
           frontMatter,
+          unlisted,
         };
       }
 
-      return Promise.all(pagesFiles.map(toMetadata));
+      async function doProcessPageSourceFile(relativeSource: string) {
+        try {
+          return await processPageSourceFile(relativeSource);
+        } catch (err) {
+          throw new Error(
+            `Processing of page source file path=${relativeSource} failed.`,
+            {cause: err as Error},
+          );
+        }
+      }
+
+      return (
+        await Promise.all(pagesFiles.map(doProcessPageSourceFile))
+      ).filter(Boolean) as Metadata[];
     },
 
     async contentLoaded({content, actions}) {

packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts

@@ -27,6 +27,8 @@ declare module '@docusaurus/plugin-content-pages' {
     readonly hide_table_of_contents?: string;
     readonly toc_min_heading_level?: number;
     readonly toc_max_heading_level?: number;
+    readonly draft?: boolean;
+    readonly unlisted?: boolean;
   };
 
   export type JSXPageMetadata = {
@@ -42,6 +44,7 @@ declare module '@docusaurus/plugin-content-pages' {
     frontMatter: FrontMatter & {[key: string]: unknown};
     title?: string;
     description?: string;
+    unlisted: boolean;
   };
 
   export type Metadata = JSXPageMetadata | MDXPageMetadata;