feat(content-docs): draft docs excluded from build & sidebars (#6457)

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

packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts

@@ -14,6 +14,7 @@ import {
   readDocFile,
   addDocNavigation,
   isCategoryIndex,
+  type DocEnv,
 } from '../docs';
 import {loadSidebars} from '../sidebars';
 import type {Sidebars} from '../sidebars/types';
@@ -62,46 +63,51 @@ ${markdown}
   };
 };
 
+type TestUtilsArg = {
+  siteDir: string;
+  context: LoadContext;
+  versionMetadata: VersionMetadata;
+  options: MetadataOptions;
+  env?: DocEnv;
+};
+
 function createTestUtils({
   siteDir,
   context,
   versionMetadata,
   options,
-}: {
-  siteDir: string;
-  context: LoadContext;
-  versionMetadata: VersionMetadata;
-  options: MetadataOptions;
-}) {
+  env = 'production',
+}: TestUtilsArg) {
   async function readDoc(docFileSource: string) {
     return readDocFile(versionMetadata, docFileSource, options);
   }
-  function processDocFile(docFile: DocFile) {
+  async function processDocFile(docFileArg: DocFile | string) {
+    const docFile: DocFile =
+      typeof docFileArg === 'string' ? await readDoc(docFileArg) : docFileArg;
+
     return processDocMetadata({
       docFile,
       versionMetadata,
       options,
       context,
+      env,
     });
   }
+
   async function testMeta(
     docFileSource: string,
     expectedMetadata: Optional<
       DocMetadataBase,
-      'source' | 'lastUpdatedBy' | 'lastUpdatedAt' | 'editUrl'
+      'source' | 'lastUpdatedBy' | 'lastUpdatedAt' | 'editUrl' | 'draft'
     >,
   ) {
     const docFile = await readDoc(docFileSource);
-    const metadata = await processDocMetadata({
-      docFile,
-      versionMetadata,
-      context,
-      options,
-    });
+    const metadata = await processDocFile(docFile);
     expect(metadata).toEqual({
       lastUpdatedBy: undefined,
       lastUpdatedAt: undefined,
       editUrl: undefined,
+      draft: false,
       source: path.posix.join(
         '@site',
         posixPath(path.relative(siteDir, versionMetadata.contentPath)),
@@ -118,6 +124,7 @@ function createTestUtils({
       versionMetadata,
       context,
       options,
+      env,
     });
     expect(metadata.permalink).toEqual(expectedPermalink);
   }
@@ -136,6 +143,7 @@ function createTestUtils({
         versionMetadata,
         context,
         options,
+        env: 'production',
       }),
     );
     const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
@@ -143,6 +151,7 @@ function createTestUtils({
         defaultSidebarItemsGenerator({...args}),
       numberPrefixParser: options.numberPrefixParser,
       docs: rawDocs,
+      drafts: [],
       version: versionMetadata,
       sidebarOptions: {
         sidebarCollapsed: false,
@@ -181,20 +190,27 @@ describe('simple site', () => {
       options,
     });
     expect(versionsMetadata).toHaveLength(1);
-    const [currentVersion] = versionsMetadata;
+    const currentVersion = versionsMetadata[0]!;
+
+    function createTestUtilsPartial(args: Partial<TestUtilsArg>) {
+      return createTestUtils({
+        siteDir,
+        context,
+        options,
+        versionMetadata: currentVersion,
+        ...args,
+      });
+    }
+
+    const defaultTestUtils = createTestUtilsPartial({});
 
-    const defaultTestUtils = createTestUtils({
-      siteDir,
-      context,
-      options,
-      versionMetadata: currentVersion,
-    });
     return {
       siteDir,
       context,
       options,
       versionsMetadata,
       defaultTestUtils,
+      createTestUtilsPartial,
       currentVersion,
     };
   }
@@ -213,6 +229,7 @@ describe('simple site', () => {
         'rootTryToEscapeSlug.md',
         'headingAsTitle.md',
         'doc with space.md',
+        'doc-draft.md',
         'foo/bar.md',
         'foo/baz.md',
         'slugs/absoluteSlug.md',
@@ -273,13 +290,14 @@ describe('simple site', () => {
   });
 
   it('docs with editUrl', async () => {
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
-      },
-    });
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
+        },
+      });
 
-    const testUtilsLocal = createTestUtils({
+    const testUtilsLocal = createTestUtilsPartial({
       siteDir,
       context,
       options,
@@ -347,13 +365,14 @@ describe('simple site', () => {
 
     const editUrlFunction: EditUrlFunction = jest.fn(() => hardcodedEditUrl);
 
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {
-        editUrl: editUrlFunction,
-      },
-    });
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          editUrl: editUrlFunction,
+        },
+      });
 
-    const testUtilsLocal = createTestUtils({
+    const testUtilsLocal = createTestUtilsPartial({
       siteDir,
       context,
       options,
@@ -404,14 +423,15 @@ describe('simple site', () => {
   });
 
   it('docs with last update time and author', async () => {
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {
-        showLastUpdateAuthor: true,
-        showLastUpdateTime: true,
-      },
-    });
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
+        },
+      });
 
-    const testUtilsLocal = createTestUtils({
+    const testUtilsLocal = createTestUtilsPartial({
       siteDir,
       context,
       options,
@@ -439,6 +459,28 @@ describe('simple site', () => {
     });
   });
 
+  it('docs with draft frontmatter', async () => {
+    const {createTestUtilsPartial} = await loadSite();
+
+    const testUtilsProd = createTestUtilsPartial({
+      env: 'production',
+    });
+    await expect(
+      testUtilsProd.processDocFile('doc-draft.md'),
+    ).resolves.toMatchObject({
+      draft: true,
+    });
+
+    const testUtilsDev = createTestUtilsPartial({
+      env: 'development',
+    });
+    await expect(
+      testUtilsDev.processDocFile('doc-draft.md'),
+    ).resolves.toMatchObject({
+      draft: false,
+    });
+  });
+
   it('docs with slugs', async () => {
     const {defaultTestUtils} = await loadSite();
 
@@ -495,7 +537,7 @@ describe('simple site', () => {
 
   it('custom pagination', async () => {
     const {defaultTestUtils, options, versionsMetadata} = await loadSite();
-    const docs = await readVersionDocs(versionsMetadata[0], options);
+    const docs = await readVersionDocs(versionsMetadata[0]!, options);
     await expect(
       defaultTestUtils.generateNavigation(docs),
     ).resolves.toMatchSnapshot();
@@ -503,7 +545,7 @@ describe('simple site', () => {
 
   it('bad pagination', async () => {
     const {defaultTestUtils, options, versionsMetadata} = await loadSite();
-    const docs = await readVersionDocs(versionsMetadata[0], options);
+    const docs = await readVersionDocs(versionsMetadata[0]!, options);
     docs.push(
       createFakeDocFile({
         source: 'bad',
@@ -539,8 +581,11 @@ describe('versioned site', () => {
       options,
     });
     expect(versionsMetadata).toHaveLength(4);
-    const [currentVersion, version101, version100, versionWithSlugs] =
-      versionsMetadata;
+
+    const currentVersion = versionsMetadata[0]!;
+    const version101 = versionsMetadata[1]!;
+    const version100 = versionsMetadata[2]!;
+    const versionWithSlugs = versionsMetadata[3]!;
 
     const currentVersionTestUtils = createTestUtils({
       siteDir,