@docusaurus/plugin-content-docs 0.0.0-4996 → 0.0.0-4997

package/lib/sidebars/postProcessor.js

@@ -9,8 +9,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.postProcessSidebars = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
+const docs_1 = require("../docs");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function normalizeCategoryLink(category, params) {
+    if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
+        return undefined;
+    }
     if (category.link?.type === 'generated-index') {
         // Default slug logic can be improved
         const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
@@ -26,30 +30,35 @@ function normalizeCategoryLink(category, params) {
 }
 function postProcessSidebarItem(item, params) {
     if (item.type === 'category') {
+        // Fail-fast if there's actually no subitems, no because all subitems are
+        // drafts. This is likely a configuration mistake.
+        if (item.items.length === 0 && !item.link) {
+            throw new Error(`Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`);
+        }
         const category = {
             ...item,
             collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
             collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
             link: normalizeCategoryLink(item, params),
-            items: item.items.map((subItem) => postProcessSidebarItem(subItem, params)),
+            items: item.items
+                .map((subItem) => postProcessSidebarItem(subItem, params))
+                .filter((v) => Boolean(v)),
         };
         // If the current category doesn't have subitems, we render a normal link
         // instead.
         if (category.items.length === 0) {
-            if (!category.link) {
-                throw new Error(`Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`);
+            // Doesn't make sense to render an empty generated index page, so we
+            // filter the entire category out as well.
+            if (!category.link ||
+                category.link.type === 'generated-index' ||
+                params.draftIds.has(category.link.id)) {
+                return null;
             }
-            return category.link.type === 'doc'
-                ? {
-                    type: 'doc',
-                    label: category.label,
-                    id: category.link.id,
-                }
-                : {
-                    type: 'link',
-                    label: category.label,
-                    href: category.link.permalink,
-                };
+            return {
+                type: 'doc',
+                label: category.label,
+                id: category.link.id,
+            };
         }
         // A non-collapsible category can't be collapsed!
         if (category.collapsible === false) {
@@ -57,9 +66,16 @@ function postProcessSidebarItem(item, params) {
         }
         return category;
     }
+    if ((item.type === 'doc' || item.type === 'ref') &&
+        params.draftIds.has(item.id)) {
+        return null;
+    }
     return item;
 }
 function postProcessSidebars(sidebars, params) {
-    return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar.map((item) => postProcessSidebarItem(item, params)));
+    const draftIds = new Set(params.drafts.flatMap(docs_1.getDocIds));
+    return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar
+        .map((item) => postProcessSidebarItem(item, { ...params, draftIds }))
+        .filter((v) => Boolean(v)));
 }
 exports.postProcessSidebars = postProcessSidebars;

package/lib/sidebars/processor.js

@@ -30,7 +30,7 @@ function toSidebarItemsGeneratorVersion(version) {
 // Handle the generation of autogenerated sidebar items and other
 // post-processing checks
 async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
-    const { sidebarItemsGenerator, numberPrefixParser, docs, drafts, version } = params;
+    const { sidebarItemsGenerator, numberPrefixParser, docs, version } = params;
     // Just a minor lazy transformation optimization
     const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
@@ -51,23 +51,12 @@ async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
         // more autogenerated items, or when loop count (e.g. 10) is reached
         return processItems(generatedItems);
     }
-    const draftIds = new Set(drafts.flatMap(docs_1.getDocIds));
-    const isDraftItem = (item) => {
-        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) {
         if (item.type === 'category') {
             return [
                 {
                     ...item,
-                    items: await processItems(item.items),
+                    items: (await Promise.all(item.items.map(processItem))).flat(),
                 },
             ];
         }
@@ -77,7 +66,7 @@ async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
         return [item];
     }
     async function processItems(items) {
-        return (await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))).flat();
+        return (await Promise.all(items.map(processItem))).flat();
     }
     const processedSidebar = await processItems(unprocessedSidebar);
     return processedSidebar;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4996",
+  "version": "0.0.0-4997",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -25,11 +25,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4996",
-    "@docusaurus/logger": "0.0.0-4996",
-    "@docusaurus/mdx-loader": "0.0.0-4996",
-    "@docusaurus/utils": "0.0.0-4996",
-    "@docusaurus/utils-validation": "0.0.0-4996",
+    "@docusaurus/core": "0.0.0-4997",
+    "@docusaurus/logger": "0.0.0-4997",
+    "@docusaurus/mdx-loader": "0.0.0-4997",
+    "@docusaurus/utils": "0.0.0-4997",
+    "@docusaurus/utils-validation": "0.0.0-4997",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
     "import-fresh": "^3.3.0",
@@ -41,8 +41,8 @@
     "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4996",
-    "@docusaurus/types": "0.0.0-4996",
+    "@docusaurus/module-type-aliases": "0.0.0-4997",
+    "@docusaurus/types": "0.0.0-4997",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -58,5 +58,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "a9b7bc9b63dd9dd26f64b9ee837e94a3202678f3"
+  "gitHead": "f3fed88a945da54cc2d17b5d6f463332d1965b1b"
 }

package/src/sidebars/README.md

@@ -6,4 +6,5 @@ This part is very complicated and hard to navigate. Sidebars are loaded through
 2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
 3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
 4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
+   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
 5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

package/src/sidebars/postProcessor.ts

@@ -15,12 +15,20 @@ import type {
   ProcessedSidebars,
   SidebarItemCategoryLink,
 } from './types';
+import {getDocIds} from '../docs';
 import _ from 'lodash';
 
+type SidebarPostProcessorParams = SidebarProcessorParams & {
+  draftIds: Set<string>;
+};
+
 function normalizeCategoryLink(
   category: ProcessedSidebarItemCategory,
-  params: SidebarProcessorParams,
+  params: SidebarPostProcessorParams,
 ): SidebarItemCategoryLink | undefined {
+  if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
+    return undefined;
+  }
   if (category.link?.type === 'generated-index') {
     // Default slug logic can be improved
     const getDefaultSlug = () =>
@@ -38,37 +46,42 @@ function normalizeCategoryLink(
 
 function postProcessSidebarItem(
   item: ProcessedSidebarItem,
-  params: SidebarProcessorParams,
-): SidebarItem {
+  params: SidebarPostProcessorParams,
+): SidebarItem | null {
   if (item.type === 'category') {
+    // Fail-fast if there's actually no subitems, no because all subitems are
+    // drafts. This is likely a configuration mistake.
+    if (item.items.length === 0 && !item.link) {
+      throw new Error(
+        `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
+      );
+    }
     const category = {
       ...item,
       collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
       collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
       link: normalizeCategoryLink(item, params),
-      items: item.items.map((subItem) =>
-        postProcessSidebarItem(subItem, params),
-      ),
+      items: item.items
+        .map((subItem) => postProcessSidebarItem(subItem, params))
+        .filter((v): v is SidebarItem => Boolean(v)),
     };
     // If the current category doesn't have subitems, we render a normal link
     // instead.
     if (category.items.length === 0) {
-      if (!category.link) {
-        throw new Error(
-          `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
-        );
+      // Doesn't make sense to render an empty generated index page, so we
+      // filter the entire category out as well.
+      if (
+        !category.link ||
+        category.link.type === 'generated-index' ||
+        params.draftIds.has(category.link.id)
+      ) {
+        return null;
       }
-      return category.link.type === 'doc'
-        ? {
-            type: 'doc',
-            label: category.label,
-            id: category.link.id,
-          }
-        : {
-            type: 'link',
-            label: category.label,
-            href: category.link.permalink,
-          };
+      return {
+        type: 'doc',
+        label: category.label,
+        id: category.link.id,
+      };
     }
     // A non-collapsible category can't be collapsed!
     if (category.collapsible === false) {
@@ -76,6 +89,12 @@ function postProcessSidebarItem(
     }
     return category;
   }
+  if (
+    (item.type === 'doc' || item.type === 'ref') &&
+    params.draftIds.has(item.id)
+  ) {
+    return null;
+  }
   return item;
 }
 
@@ -83,7 +102,11 @@ export function postProcessSidebars(
   sidebars: ProcessedSidebars,
   params: SidebarProcessorParams,
 ): Sidebars {
+  const draftIds = new Set(params.drafts.flatMap(getDocIds));
+
   return _.mapValues(sidebars, (sidebar) =>
-    sidebar.map((item) => postProcessSidebarItem(item, params)),
+    sidebar
+      .map((item) => postProcessSidebarItem(item, {...params, draftIds}))
+      .filter((v): v is SidebarItem => Boolean(v)),
   );
 }

package/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 {getDocIds, isCategoryIndex} from '../docs';
+import {isCategoryIndex} from '../docs';
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -55,8 +55,7 @@ async function processSidebar(
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {sidebarItemsGenerator, numberPrefixParser, docs, drafts, version} =
-    params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -82,19 +81,6 @@ 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[]> {
@@ -102,7 +88,7 @@ async function processSidebar(
       return [
         {
           ...item,
-          items: await processItems(item.items),
+          items: (await Promise.all(item.items.map(processItem))).flat(),
         },
       ];
     }
@@ -115,9 +101,7 @@ async function processSidebar(
   async function processItems(
     items: NormalizedSidebarItem[],
   ): Promise<ProcessedSidebarItem[]> {
-    return (
-      await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))
-    ).flat();
+    return (await Promise.all(items.map(processItem))).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);