@docusaurus/plugin-content-docs 0.0.0-4545 → 0.0.0-4549

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4545",
+  "version": "0.0.0-4549",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4545",
-    "@docusaurus/logger": "0.0.0-4545",
-    "@docusaurus/mdx-loader": "0.0.0-4545",
-    "@docusaurus/utils": "0.0.0-4545",
-    "@docusaurus/utils-validation": "0.0.0-4545",
+    "@docusaurus/core": "0.0.0-4549",
+    "@docusaurus/logger": "0.0.0-4549",
+    "@docusaurus/mdx-loader": "0.0.0-4549",
+    "@docusaurus/utils": "0.0.0-4549",
+    "@docusaurus/utils-validation": "0.0.0-4549",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.0",
     "import-fresh": "^3.2.2",
@@ -40,8 +40,8 @@
     "webpack": "^5.68.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4545",
-    "@docusaurus/types": "0.0.0-4545",
+    "@docusaurus/module-type-aliases": "0.0.0-4549",
+    "@docusaurus/types": "0.0.0-4549",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "2fd48f443b78b58b3b511f797a0050d407370f07"
+  "gitHead": "ed41c3cb08710f3a6211b2a17ff658f9dd41f164"
 }

package/src/cli.ts

@@ -16,7 +16,7 @@ import type {
   PathOptions,
   SidebarOptions,
 } from '@docusaurus/plugin-content-docs';
-import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
+import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 
@@ -34,7 +34,8 @@ async function createVersionedSidebarFile({
   // Load current sidebar and create a new versioned sidebars file (if needed).
   // Note: we don't need the sidebars file to be normalized: it's ok to let
   // plugin option changes to impact older, versioned sidebars
-  const sidebars = await loadSidebarsFile(sidebarPath);
+  // We don't validate here, assuming the user has already built the version
+  const sidebars = await loadSidebarsFileUnsafe(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty
   // or sidebars are disabled/false)

package/src/sidebars/README.md

@@ -0,0 +1,9 @@
+# Sidebars
+
+This part is very complicated and hard to navigate. Sidebars are loaded through the following steps:
+
+1. **Loading**. The sidebars file is read. Returns `SidebarsConfig`.
+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`.
+5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

package/src/sidebars/generator.ts

@@ -6,12 +6,12 @@
  */
 
 import type {
-  SidebarItem,
   SidebarItemDoc,
-  SidebarItemCategory,
   SidebarItemsGenerator,
   SidebarItemsGeneratorDoc,
-  SidebarItemCategoryLink,
+  NormalizedSidebarItemCategory,
+  NormalizedSidebarItem,
+  SidebarItemCategoryLinkConfig,
 } from './types';
 import {sortBy, last} from 'lodash';
 import {addTrailingSlash, posixPath} from '@docusaurus/utils';
@@ -48,7 +48,6 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   numberPrefixParser,
   isCategoryIndex,
   docs: allDocs,
-  options,
   item: {dirName: autogenDir},
   categoriesMetadata,
 }) => {
@@ -125,7 +124,9 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    * Step 3. Recursively transform the tree-like structure to sidebar items.
    * (From a record to an array of items, akin to normalizing shorthand)
    */
-  function generateSidebar(fsModel: Dir): Promise<WithPosition<SidebarItem>[]> {
+  function generateSidebar(
+    fsModel: Dir,
+  ): Promise<WithPosition<NormalizedSidebarItem>[]> {
     function createDocItem(id: string): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
@@ -145,7 +146,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       dir: Dir,
       fullPath: string,
       folderName: string,
-    ): Promise<WithPosition<SidebarItemCategory>> {
+    ): Promise<WithPosition<NormalizedSidebarItemCategory>> {
       const categoryMetadata =
         categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
       const className = categoryMetadata?.className;
@@ -160,18 +161,19 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
       function findDocByLocalId(localId: string): SidebarItemDoc | undefined {
         return allItems.find(
-          (item) => item.type === 'doc' && getLocalDocId(item.id) === localId,
-        ) as SidebarItemDoc | undefined;
+          (item): item is SidebarItemDoc =>
+            item.type === 'doc' && getLocalDocId(item.id) === localId,
+        );
       }
 
       function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
-        return allItems.find((item) => {
+        return allItems.find((item): item is SidebarItemDoc => {
           if (item.type !== 'doc') {
             return false;
           }
           const doc = getDoc(item.id);
           return isCategoryIndex(toCategoryIndexMatcherParam(doc));
-        }) as SidebarItemDoc | undefined;
+        });
       }
 
       function getCategoryLinkedDocId(): string | undefined {
@@ -190,13 +192,13 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
 
       const categoryLinkedDocId = getCategoryLinkedDocId();
 
-      const link: SidebarItemCategoryLink | undefined = categoryLinkedDocId
-        ? {
-            type: 'doc',
-            id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
-          }
-        : // TODO typing issue
-          (categoryMetadata?.link as SidebarItemCategoryLink | undefined);
+      const link: SidebarItemCategoryLinkConfig | null | undefined =
+        categoryLinkedDocId
+          ? {
+              type: 'doc',
+              id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+            }
+          : categoryMetadata?.link;
 
       // If a doc is linked, remove it from the category subItems
       const items = allItems.filter(
@@ -206,9 +208,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       return {
         type: 'category',
         label: categoryMetadata?.label ?? filename,
-        collapsible:
-          categoryMetadata?.collapsible ?? options.sidebarCollapsible,
-        collapsed: categoryMetadata?.collapsed ?? options.sidebarCollapsed,
+        collapsible: categoryMetadata?.collapsible,
+        collapsed: categoryMetadata?.collapsed,
         position: categoryMetadata?.position ?? numberPrefix,
         ...(className !== undefined && {className}),
         items,
@@ -219,7 +220,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       dir: Dir | null, // The directory item to be transformed.
       itemKey: string, // For docs, it's the doc ID; for categories, it's used to generate the next `relativePath`.
       fullPath: string, // `dir`'s full path relative to the autogen dir.
-    ): Promise<WithPosition<SidebarItem>> {
+    ): Promise<WithPosition<NormalizedSidebarItem>> {
       return dir
         ? createCategoryItem(dir, fullPath, itemKey)
         : createDocItem(itemKey.substring(docIdPrefix.length));
@@ -238,7 +239,9 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    * consecutive sidebar slices (i.e. a whole category composed of multiple
    * autogenerated items)
    */
-  function sortItems(sidebarItems: WithPosition<SidebarItem>[]): SidebarItem[] {
+  function sortItems(
+    sidebarItems: WithPosition<NormalizedSidebarItem>[],
+  ): NormalizedSidebarItem[] {
     const processedSidebarItems = sidebarItems.map((item) => {
       if (item.type === 'category') {
         return {...item, items: sortItems(item.items)};

package/src/sidebars/index.ts

@@ -7,13 +7,13 @@
 
 import fs from 'fs-extra';
 import importFresh from 'import-fresh';
-import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types';
-import type {NormalizeSidebarsParams} from '../types';
+import type {SidebarsConfig, Sidebars, SidebarProcessorParams} from './types';
 import {validateSidebars, validateCategoryMetadataFile} from './validation';
 import {normalizeSidebars} from './normalization';
-import {processSidebars, type SidebarProcessorParams} from './processor';
+import {processSidebars} from './processor';
+import {postProcessSidebars} from './postProcessor';
 import path from 'path';
-import {createSlugger, Globby} from '@docusaurus/utils';
+import {Globby} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import Yaml from 'js-yaml';
@@ -69,7 +69,7 @@ async function readCategoriesMetadata(contentPath: string) {
   );
 }
 
-async function loadSidebarsFileUnsafe(
+export async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
 ): Promise<SidebarsConfig> {
   // false => no sidebars
@@ -93,37 +93,21 @@ async function loadSidebarsFileUnsafe(
   return importFresh(sidebarFilePath);
 }
 
-export async function loadSidebarsFile(
-  sidebarFilePath: string | false | undefined,
-): Promise<SidebarsConfig> {
-  const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
-  validateSidebars(sidebarsConfig);
-  return sidebarsConfig;
-}
-
-export async function loadNormalizedSidebars(
-  sidebarFilePath: string | false | undefined,
-  params: NormalizeSidebarsParams,
-): Promise<NormalizedSidebars> {
-  return normalizeSidebars(await loadSidebarsFile(sidebarFilePath), params);
-}
-
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
-  options: Omit<SidebarProcessorParams, 'categoriesMetadata'>,
+  options: SidebarProcessorParams,
 ): Promise<Sidebars> {
-  const normalizeSidebarsParams: NormalizeSidebarsParams = {
-    ...options.sidebarOptions,
-    version: options.version,
-    categoryLabelSlugger: createSlugger(),
-  };
-  const normalizedSidebars = await loadNormalizedSidebars(
-    sidebarFilePath,
-    normalizeSidebarsParams,
-  );
+  const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+  const normalizedSidebars = normalizeSidebars(sidebarsConfig);
+  validateSidebars(normalizedSidebars);
   const categoriesMetadata = await readCategoriesMetadata(
     options.version.contentPath,
   );
-  return processSidebars(normalizedSidebars, {...options, categoriesMetadata});
+  const processedSidebars = await processSidebars(
+    normalizedSidebars,
+    categoriesMetadata,
+    options,
+  );
+  return postProcessSidebars(processedSidebars, options);
 }

package/src/sidebars/normalization.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {NormalizeSidebarsParams} from '../types';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,
@@ -15,41 +14,16 @@ import type {
   SidebarItemConfig,
   SidebarConfig,
   SidebarsConfig,
-  SidebarItemCategoryLink,
   NormalizedSidebarItemCategory,
 } from './types';
 import {isCategoriesShorthand} from './utils';
 import {mapValues} from 'lodash';
-import {normalizeUrl} from '@docusaurus/utils';
-import type {SidebarOptions} from '@docusaurus/plugin-content-docs';
-
-function normalizeCategoryLink(
-  category: SidebarItemCategoryConfig,
-  params: NormalizeSidebarsParams,
-): SidebarItemCategoryLink | undefined {
-  if (category.link?.type === 'generated-index') {
-    // default slug logic can be improved
-    const getDefaultSlug = () =>
-      `/category/${params.categoryLabelSlugger.slug(category.label)}`;
-    const slug = category.link.slug ?? getDefaultSlug();
-    const permalink = normalizeUrl([params.version.versionPath, slug]);
-    return {
-      ...category.link,
-      slug,
-      permalink,
-    };
-  }
-  return category.link;
-}
 
 function normalizeCategoriesShorthand(
   sidebar: SidebarCategoriesShorthand,
-  options: SidebarOptions,
 ): SidebarItemCategoryConfig[] {
   return Object.entries(sidebar).map(([label, items]) => ({
     type: 'category',
-    collapsed: options.sidebarCollapsed,
-    collapsible: options.sidebarCollapsible,
     label,
     items,
   }));
@@ -61,7 +35,6 @@ function normalizeCategoriesShorthand(
  */
 export function normalizeItem(
   item: SidebarItemConfig,
-  options: NormalizeSidebarsParams,
 ): NormalizedSidebarItem[] {
   if (typeof item === 'string') {
     return [
@@ -72,42 +45,41 @@ export function normalizeItem(
     ];
   }
   if (isCategoriesShorthand(item)) {
-    return normalizeCategoriesShorthand(item, options).flatMap((subItem) =>
-      normalizeItem(subItem, options),
+    return normalizeCategoriesShorthand(item).flatMap((subItem) =>
+      normalizeItem(subItem),
     );
   }
   if (item.type === 'category') {
-    const link = normalizeCategoryLink(item, options);
+    if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
+      throw new Error(
+        `Invalid category ${JSON.stringify(
+          item,
+        )}: items must be an array of sidebar items or a category shorthand`,
+      );
+    }
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,
-      link,
-      items: (item.items ?? []).flatMap((subItem) =>
-        normalizeItem(subItem, options),
-      ),
-      collapsible: item.collapsible ?? options.sidebarCollapsible,
-      collapsed: item.collapsed ?? options.sidebarCollapsed,
+      items: Array.isArray(item.items)
+        ? item.items.flatMap((subItem) => normalizeItem(subItem))
+        : normalizeCategoriesShorthand(item.items).flatMap((subItem) =>
+            normalizeItem(subItem),
+          ),
     };
     return [normalizedCategory];
   }
   return [item];
 }
 
-function normalizeSidebar(
-  sidebar: SidebarConfig,
-  options: NormalizeSidebarsParams,
-): NormalizedSidebar {
+function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar {
   const normalizedSidebar = Array.isArray(sidebar)
     ? sidebar
-    : normalizeCategoriesShorthand(sidebar, options);
+    : normalizeCategoriesShorthand(sidebar);
 
-  return normalizedSidebar.flatMap((subItem) =>
-    normalizeItem(subItem, options),
-  );
+  return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
 }
 
 export function normalizeSidebars(
   sidebars: SidebarsConfig,
-  params: NormalizeSidebarsParams,
 ): NormalizedSidebars {
-  return mapValues(sidebars, (items) => normalizeSidebar(items, params));
+  return mapValues(sidebars, normalizeSidebar);
 }

package/src/sidebars/postProcessor.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 {normalizeUrl} from '@docusaurus/utils';
+import type {
+  SidebarItem,
+  Sidebars,
+  SidebarProcessorParams,
+  ProcessedSidebarItemCategory,
+  ProcessedSidebarItem,
+  ProcessedSidebars,
+  SidebarItemCategoryLink,
+} from './types';
+import {mapValues} from 'lodash';
+
+function normalizeCategoryLink(
+  category: ProcessedSidebarItemCategory,
+  params: SidebarProcessorParams,
+): SidebarItemCategoryLink | undefined {
+  if (category.link?.type === 'generated-index') {
+    // default slug logic can be improved
+    const getDefaultSlug = () =>
+      `/category/${params.categoryLabelSlugger.slug(category.label)}`;
+    const slug = category.link.slug ?? getDefaultSlug();
+    const permalink = normalizeUrl([params.version.versionPath, slug]);
+    return {
+      ...category.link,
+      slug,
+      permalink,
+    };
+  }
+  return category.link;
+}
+
+function postProcessSidebarItem(
+  item: ProcessedSidebarItem,
+  params: SidebarProcessorParams,
+): SidebarItem {
+  if (item.type === 'category') {
+    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),
+      ),
+    };
+    // 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.`,
+        );
+      }
+      switch (category.link.type) {
+        case 'doc':
+          return {
+            type: 'doc',
+            label: category.label,
+            id: category.link.id,
+          };
+        case 'generated-index':
+          return {
+            type: 'link',
+            label: category.label,
+            href: category.link.permalink,
+          };
+        default:
+          throw new Error('Unexpected sidebar category link type');
+      }
+    }
+    // A non-collapsible category can't be collapsed!
+    if (category.collapsible === false) {
+      category.collapsed = false;
+    }
+    return category;
+  }
+  return item;
+}
+
+export function postProcessSidebars(
+  sidebars: ProcessedSidebars,
+  params: SidebarProcessorParams,
+): Sidebars {
+  return mapValues(sidebars, (sidebar) =>
+    sidebar.map((item) => postProcessSidebarItem(item, params)),
+  );
+}

package/src/sidebars/processor.ts

@@ -7,41 +7,23 @@
 
 import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
-  Sidebars,
-  Sidebar,
-  SidebarItem,
   NormalizedSidebarItem,
   NormalizedSidebar,
   NormalizedSidebars,
-  SidebarItemsGeneratorOption,
   SidebarItemsGeneratorDoc,
   SidebarItemsGeneratorVersion,
-  NormalizedSidebarItemCategory,
-  SidebarItemCategory,
   SidebarItemAutogenerated,
+  ProcessedSidebarItem,
+  ProcessedSidebar,
+  ProcessedSidebars,
+  SidebarProcessorParams,
   CategoryMetadataFile,
 } from './types';
-import {transformSidebarItems} from './utils';
 import {DefaultSidebarItemsGenerator} from './generator';
+import {validateSidebars} from './validation';
 import {mapValues, memoize, pick} from 'lodash';
 import combinePromises from 'combine-promises';
-import {normalizeItem} from './normalization';
 import {isCategoryIndex} from '../docs';
-import type {Slugger} from '@docusaurus/utils';
-import type {
-  NumberPrefixParser,
-  SidebarOptions,
-} from '@docusaurus/plugin-content-docs';
-
-export type SidebarProcessorParams = {
-  sidebarItemsGenerator: SidebarItemsGeneratorOption;
-  numberPrefixParser: NumberPrefixParser;
-  docs: DocMetadataBase[];
-  version: VersionMetadata;
-  categoryLabelSlugger: Slugger;
-  sidebarOptions: SidebarOptions;
-  categoriesMetadata: Record<string, CategoryMetadataFile>;
-};
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -66,15 +48,15 @@ function toSidebarItemsGeneratorVersion(
 // post-processing checks
 async function processSidebar(
   unprocessedSidebar: NormalizedSidebar,
+  categoriesMetadata: Record<string, CategoryMetadataFile>,
   params: SidebarProcessorParams,
-): Promise<Sidebar> {
+): Promise<ProcessedSidebar> {
   const {
     sidebarItemsGenerator,
     numberPrefixParser,
     docs,
     version,
     sidebarOptions,
-    categoriesMetadata,
   } = params;
 
   // Just a minor lazy transformation optimization
@@ -83,20 +65,9 @@ async function processSidebar(
     version: toSidebarItemsGeneratorVersion(version),
   }));
 
-  async function processCategoryItem(
-    item: NormalizedSidebarItemCategory,
-  ): Promise<SidebarItemCategory> {
-    return {
-      ...item,
-      items: (await Promise.all(item.items.map(processItem))).flat(),
-    };
-  }
-
   async function processAutoGeneratedItem(
     item: SidebarItemAutogenerated,
-  ): Promise<SidebarItem[]> {
-    // TODO the returned type can't be trusted in practice (generator can be
-    // user-provided)
+  ): Promise<ProcessedSidebarItem[]> {
     const generatedItems = await sidebarItemsGenerator({
       item,
       numberPrefixParser,
@@ -106,50 +77,23 @@ async function processSidebar(
       options: sidebarOptions,
       categoriesMetadata,
     });
-    // TODO validate generated items: user can generate bad items
-
-    const generatedItemsNormalized = generatedItems.flatMap((generatedItem) =>
-      normalizeItem(generatedItem, {...params, ...sidebarOptions}),
-    );
-
     // Process again... weird but sidebar item generated might generate some
     // auto-generated items?
-    return processItems(generatedItemsNormalized);
+    // TODO repeatedly process & unwrap autogenerated items until there are no
+    // more autogenerated items, or when loop count (e.g. 10) is reached
+    return processItems(generatedItems);
   }
 
   async function processItem(
     item: NormalizedSidebarItem,
-  ): Promise<SidebarItem[]> {
+  ): Promise<ProcessedSidebarItem[]> {
     if (item.type === 'category') {
-      // If the current category doesn't have subitems, we render a normal doc link instead.
-      if (item.items.length === 0) {
-        if (!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.`,
-          );
-        }
-        switch (item.link.type) {
-          case 'doc':
-            return [
-              {
-                type: 'doc',
-                label: item.label,
-                id: item.link.id,
-              },
-            ];
-          case 'generated-index':
-            return [
-              {
-                type: 'link',
-                label: item.label,
-                href: item.link.permalink,
-              },
-            ];
-          default:
-            throw new Error('Unexpected sidebar category link type');
-        }
-      }
-      return [await processCategoryItem(item)];
+      return [
+        {
+          ...item,
+          items: (await Promise.all(item.items.map(processItem))).flat(),
+        },
+      ];
     }
     if (item.type === 'autogenerated') {
       return processAutoGeneratedItem(item);
@@ -159,32 +103,24 @@ async function processSidebar(
 
   async function processItems(
     items: NormalizedSidebarItem[],
-  ): Promise<SidebarItem[]> {
+  ): Promise<ProcessedSidebarItem[]> {
     return (await Promise.all(items.map(processItem))).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);
-
-  const fixSidebarItemInconsistencies = (item: SidebarItem): SidebarItem => {
-    // A non-collapsible category can't be collapsed!
-    if (item.type === 'category' && !item.collapsible && item.collapsed) {
-      return {
-        ...item,
-        collapsed: false,
-      };
-    }
-    return item;
-  };
-  return transformSidebarItems(processedSidebar, fixSidebarItemInconsistencies);
+  return processedSidebar;
 }
 
 export async function processSidebars(
   unprocessedSidebars: NormalizedSidebars,
+  categoriesMetadata: Record<string, CategoryMetadataFile>,
   params: SidebarProcessorParams,
-): Promise<Sidebars> {
-  return combinePromises(
+): Promise<ProcessedSidebars> {
+  const processedSidebars = await combinePromises(
     mapValues(unprocessedSidebars, (unprocessedSidebar) =>
-      processSidebar(unprocessedSidebar, params),
+      processSidebar(unprocessedSidebar, categoriesMetadata, params),
     ),
   );
+  validateSidebars(processedSidebars);
+  return processedSidebars;
 }