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/sidebars/__tests__/__snapshots__/index.test.ts.snap

@@ -247,6 +247,31 @@ exports[`loadSidebars sidebars with known sidebar item type 1`] = `
 }
 `;
 
+exports[`loadSidebars sidebars with some draft items 1`] = `
+{
+  "docs": [
+    {
+      "collapsed": true,
+      "collapsible": true,
+      "items": [
+        {
+          "id": "foo/bar",
+          "type": "doc",
+        },
+        {
+          "href": "https://github.com",
+          "label": "GitHub",
+          "type": "link",
+        },
+      ],
+      "label": "Test",
+      "link": undefined,
+      "type": "category",
+    },
+  ],
+}
+`;
+
 exports[`loadSidebars undefined path 1`] = `
 {
   "defaultSidebar": [

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

@@ -10,6 +10,7 @@ import path from 'path';
 import {loadSidebars, DisabledSidebars} from '../index';
 import type {SidebarProcessorParams} from '../types';
 import {DefaultSidebarItemsGenerator} from '../generator';
+import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 
 describe('loadSidebars', () => {
   const fixtureDir = path.join(__dirname, '__fixtures__', 'sidebars');
@@ -24,6 +25,7 @@ describe('loadSidebars', () => {
         frontMatter: {},
       },
     ],
+    drafts: [],
     version: {
       contentPath: path.join(fixtureDir, 'docs'),
       contentPathLocalized: path.join(fixtureDir, 'docs'),
@@ -37,6 +39,16 @@ describe('loadSidebars', () => {
     expect(result).toMatchSnapshot();
   });
 
+  it('sidebars with some draft items', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars.json');
+    const paramsWithDrafts: SidebarProcessorParams = {
+      ...params,
+      drafts: [{id: 'foo/baz'} as DocMetadata, {id: 'hello'} as DocMetadata],
+    };
+    const result = await loadSidebars(sidebarPath, paramsWithDrafts);
+    expect(result).toMatchSnapshot();
+  });
+
   it('sidebars with deep level of category', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-category.js');
     const result = await loadSidebars(sidebarPath, params);

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

@@ -46,6 +46,7 @@ describe('processSidebars', () => {
   const params: SidebarProcessorParams = {
     sidebarItemsGenerator: StaticSidebarItemsGenerator,
     docs: [],
+    drafts: [],
     version,
     numberPrefixParser: DefaultNumberPrefixParser,
     categoryLabelSlugger: createSlugger(),

packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts

@@ -26,7 +26,7 @@ import {DefaultSidebarItemsGenerator} from './generator';
 import {validateSidebars} from './validation';
 import _ from 'lodash';
 import combinePromises from 'combine-promises';
-import {isCategoryIndex} from '../docs';
+import {getDocIds, isCategoryIndex} from '../docs';
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -55,7 +55,8 @@ async function processSidebar(
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, drafts, version} =
+    params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -81,6 +82,19 @@ async function processSidebar(
     return processItems(generatedItems);
   }
 
+  const draftIds = new Set(drafts.flatMap(getDocIds));
+
+  const isDraftItem = (item: NormalizedSidebarItem): boolean => {
+    if (item.type === 'doc' || item.type === 'ref') {
+      return draftIds.has(item.id);
+    }
+    // If a category only contains draft items, it should be filtered entirely.
+    if (item.type === 'category') {
+      return item.items.every(isDraftItem);
+    }
+    return false;
+  };
+
   async function processItem(
     item: NormalizedSidebarItem,
   ): Promise<ProcessedSidebarItem[]> {
@@ -88,7 +102,7 @@ async function processSidebar(
       return [
         {
           ...item,
-          items: (await Promise.all(item.items.map(processItem))).flat(),
+          items: await processItems(item.items),
         },
       ];
     }
@@ -101,7 +115,9 @@ async function processSidebar(
   async function processItems(
     items: NormalizedSidebarItem[],
   ): Promise<ProcessedSidebarItem[]> {
-    return (await Promise.all(items.map(processItem))).flat();
+    return (
+      await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))
+    ).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -269,6 +269,7 @@ export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;
   numberPrefixParser: NumberPrefixParser;
   docs: DocMetadataBase[];
+  drafts: DocMetadataBase[];
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
   sidebarOptions: SidebarOptions;