@docusaurus/plugin-content-docs 2.0.0-beta.15 → 2.0.0-beta.16

package/src/sidebars/index.ts

@@ -7,14 +7,18 @@
 
 import fs from 'fs-extra';
 import importFresh from 'import-fresh';
-import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types';
-import type {NormalizeSidebarsParams} from '../types';
-import {validateSidebars} from './validation';
+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} 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';
+import _ from 'lodash';
+import combinePromises from 'combine-promises';
 
 export const DefaultSidebars: SidebarsConfig = {
   defaultSidebar: [
@@ -38,9 +42,36 @@ export function resolveSidebarPathOption(
     : sidebarPathOption;
 }
 
-function loadSidebarsFileUnsafe(
+async function readCategoriesMetadata(contentPath: string) {
+  const categoryFiles = await Globby('**/_category_.{json,yml,yaml}', {
+    cwd: contentPath,
+  });
+  const categoryToFile = _.groupBy(categoryFiles, path.dirname);
+  return combinePromises(
+    _.mapValues(categoryToFile, async (files, folder) => {
+      const [filePath] = files;
+      if (files.length > 1) {
+        logger.warn`There are more than one category metadata files for path=${folder}: ${files.join(
+          ', ',
+        )}. The behavior is undetermined.`;
+      }
+      const content = await fs.readFile(
+        path.join(contentPath, filePath),
+        'utf-8',
+      );
+      try {
+        return validateCategoryMetadataFile(Yaml.load(content));
+      } catch (err) {
+        logger.error`The docs sidebar category metadata file path=${filePath} looks invalid!`;
+        throw err;
+      }
+    }),
+  );
+}
+
+export async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
-): SidebarsConfig {
+): Promise<SidebarsConfig> {
   // false => no sidebars
   if (sidebarFilePath === false) {
     return DisabledSidebars;
@@ -54,7 +85,7 @@ function loadSidebarsFileUnsafe(
   // Non-existent sidebars file: no sidebars
   // Note: this edge case can happen on versioned docs, not current version
   // We avoid creating empty versioned sidebars file with the CLI
-  if (!fs.existsSync(sidebarFilePath)) {
+  if (!(await fs.pathExists(sidebarFilePath))) {
     return DisabledSidebars;
   }
 
@@ -62,34 +93,21 @@ function loadSidebarsFileUnsafe(
   return importFresh(sidebarFilePath);
 }
 
-export function loadSidebarsFile(
-  sidebarFilePath: string | false | undefined,
-): SidebarsConfig {
-  const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
-  validateSidebars(sidebarsConfig);
-  return sidebarsConfig;
-}
-
-export function loadNormalizedSidebars(
-  sidebarFilePath: string | false | undefined,
-  params: NormalizeSidebarsParams,
-): NormalizedSidebars {
-  return normalizeSidebars(loadSidebarsFile(sidebarFilePath), params);
-}
-
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
   options: SidebarProcessorParams,
 ): Promise<Sidebars> {
-  const normalizeSidebarsParams: NormalizeSidebarsParams = {
-    ...options.sidebarOptions,
-    version: options.version,
-    categoryLabelSlugger: createSlugger(),
-  };
-  const normalizedSidebars = loadNormalizedSidebars(
-    sidebarFilePath,
-    normalizeSidebarsParams,
+  const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+  const normalizedSidebars = normalizeSidebars(sidebarsConfig);
+  validateSidebars(normalizedSidebars);
+  const categoriesMetadata = await readCategoriesMetadata(
+    options.version.contentPath,
+  );
+  const processedSidebars = await processSidebars(
+    normalizedSidebars,
+    categoriesMetadata,
+    options,
   );
-  return processSidebars(normalizedSidebars, 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,17 @@ 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;
-}
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
 
 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,31 +36,21 @@ function normalizeCategoriesShorthand(
  */
 export function normalizeItem(
   item: SidebarItemConfig,
-  options: NormalizeSidebarsParams,
 ): NormalizedSidebarItem[] {
   if (typeof item === 'string') {
-    return [
-      {
-        type: 'doc',
-        id: item,
-      },
-    ];
+    return [{type: 'doc', id: item}];
   }
   if (isCategoriesShorthand(item)) {
-    return normalizeCategoriesShorthand(item, options).flatMap((subItem) =>
-      normalizeItem(subItem, options),
-    );
+    // This will never throw anyways
+    return normalizeSidebar(item, 'sidebar items slice');
   }
   if (item.type === 'category') {
-    const link = normalizeCategoryLink(item, options);
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,
-      link,
-      items: (item.items ?? []).flatMap((subItem) =>
-        normalizeItem(subItem, options),
+      items: normalizeSidebar(
+        item.items,
+        logger.interpolate`code=${'items'} of the category name=${item.label}`,
       ),
-      collapsible: item.collapsible ?? options.sidebarCollapsible,
-      collapsed: item.collapsed ?? options.sidebarCollapsed,
     };
     return [normalizedCategory];
   }
@@ -94,20 +59,27 @@ export function normalizeItem(
 
 function normalizeSidebar(
   sidebar: SidebarConfig,
-  options: NormalizeSidebarsParams,
+  place: string,
 ): NormalizedSidebar {
+  if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) {
+    throw new Error(
+      logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
+        sidebar,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+    );
+  }
+
   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, (sidebar, id) =>
+    normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`),
+  );
 }

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 _ 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,44 +7,28 @@
 
 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 {mapValues, memoize, pick} from 'lodash';
+import {validateSidebars} from './validation';
+import _ 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;
-};
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
 ): SidebarItemsGeneratorDoc {
-  return pick(doc, [
+  return _.pick(doc, [
     'id',
     'unversionedId',
     'frontMatter',
@@ -57,14 +41,16 @@ function toSidebarItemsGeneratorDoc(
 function toSidebarItemsGeneratorVersion(
   version: VersionMetadata,
 ): SidebarItemsGeneratorVersion {
-  return pick(version, ['versionName', 'contentPath']);
+  return _.pick(version, ['versionName', 'contentPath']);
 }
 
-// Handle the generation of autogenerated sidebar items and other post-processing checks
+// Handle the generation of autogenerated sidebar items and other
+// post-processing checks
 async function processSidebar(
   unprocessedSidebar: NormalizedSidebar,
+  categoriesMetadata: Record<string, CategoryMetadataFile>,
   params: SidebarProcessorParams,
-): Promise<Sidebar> {
+): Promise<ProcessedSidebar> {
   const {
     sidebarItemsGenerator,
     numberPrefixParser,
@@ -74,24 +60,14 @@ async function processSidebar(
   } = params;
 
   // Just a minor lazy transformation optimization
-  const getSidebarItemsGeneratorDocsAndVersion = memoize(() => ({
+  const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
     docs: docs.map(toSidebarItemsGeneratorDoc),
     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,
@@ -99,22 +75,25 @@ async function processSidebar(
       isCategoryIndex,
       ...getSidebarItemsGeneratorDocsAndVersion(),
       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);
+    // Process again... weird but sidebar item generated might generate some
+    // auto-generated items?
+    // 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') {
-      return [await processCategoryItem(item)];
+      return [
+        {
+          ...item,
+          items: (await Promise.all(item.items.map(processItem))).flat(),
+        },
+      ];
     }
     if (item.type === 'autogenerated') {
       return processAutoGeneratedItem(item);
@@ -124,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(
-    mapValues(unprocessedSidebars, (unprocessedSidebar) =>
-      processSidebar(unprocessedSidebar, params),
+): Promise<ProcessedSidebars> {
+  const processedSidebars = await combinePromises(
+    _.mapValues(unprocessedSidebars, (unprocessedSidebar) =>
+      processSidebar(unprocessedSidebar, categoriesMetadata, params),
     ),
   );
+  validateSidebars(processedSidebars);
+  return processedSidebars;
 }

package/src/sidebars/types.ts

@@ -12,6 +12,7 @@ import type {
   SidebarOptions,
   CategoryIndexMatcher,
 } from '@docusaurus/plugin-content-docs';
+import type {Slugger} from '@docusaurus/utils';
 
 // Makes all properties visible when hovering over the type
 type Expand<T extends Record<string, unknown>> = {[P in keyof T]: T[P]};
@@ -27,6 +28,12 @@ export type SidebarItemDoc = SidebarItemBase & {
   id: string;
 };
 
+export type SidebarItemHtml = SidebarItemBase & {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean;
+};
+
 export type SidebarItemLink = SidebarItemBase & {
   type: 'link';
   href: string;
@@ -76,17 +83,18 @@ export type SidebarItemCategoryLink =
 // The user-given configuration in sidebars.js, before normalization
 export type SidebarItemCategoryConfig = Expand<
   Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
-    items: SidebarItemConfig[];
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
     link?: SidebarItemCategoryLinkConfig;
   }
 >;
 
 export type SidebarCategoriesShorthand = {
-  [sidebarCategory: string]: SidebarItemConfig[];
+  [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
 };
 
 export type SidebarItemConfig =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemAutogenerated
   | SidebarItemCategoryConfig
@@ -100,14 +108,15 @@ export type SidebarsConfig = {
 
 // Normalized but still has 'autogenerated', which will be handled in processing
 export type NormalizedSidebarItemCategory = Expand<
-  SidebarItemCategoryBase & {
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: NormalizedSidebarItem[];
-    link?: SidebarItemCategoryLink;
+    link?: SidebarItemCategoryLinkConfig;
   }
 >;
 
 export type NormalizedSidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | NormalizedSidebarItemCategory
   | SidebarItemAutogenerated;
@@ -117,6 +126,22 @@ export type NormalizedSidebars = {
   [sidebarId: string]: NormalizedSidebar;
 };
 
+export type ProcessedSidebarItemCategory = Expand<
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: ProcessedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+  }
+>;
+export type ProcessedSidebarItem =
+  | SidebarItemDoc
+  | SidebarItemHtml
+  | SidebarItemLink
+  | ProcessedSidebarItemCategory;
+export type ProcessedSidebar = ProcessedSidebarItem[];
+export type ProcessedSidebars = {
+  [sidebarId: string]: ProcessedSidebar;
+};
+
 export type SidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: SidebarItem[];
@@ -131,6 +156,7 @@ export type SidebarItemCategoryWithGeneratedIndex =
 
 export type SidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemCategory;
 
@@ -158,12 +184,21 @@ export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
 
-export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type PropSidebarItemHtml = SidebarItemHtml;
+
+export type PropSidebarItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory
+  | PropSidebarItemHtml;
 export type PropSidebar = PropSidebarItem[];
 export type PropSidebars = {
   [sidebarId: string]: PropSidebar;
 };
 
+export type PropSidebarBreadcrumbsItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory;
+
 export type PropVersionDoc = {
   id: string;
   title: string;
@@ -174,6 +209,20 @@ export type PropVersionDocs = {
   [docId: string]: PropVersionDoc;
 };
 
+export type CategoryMetadataFile = {
+  label?: string;
+  position?: number;
+  collapsed?: boolean;
+  collapsible?: boolean;
+  className?: string;
+  link?: SidebarItemCategoryLinkConfig | null;
+
+  // TODO should we allow "items" here? how would this work? would an
+  // "autogenerated" type be allowed?
+  // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
+  // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
+};
+
 // Reduce API surface for options.sidebarItemsGenerator
 // The user-provided generator fn should receive only a subset of metadata
 // A change to any of these metadata can be considered as a breaking change
@@ -197,19 +246,28 @@ export type SidebarItemsGeneratorArgs = {
   docs: SidebarItemsGeneratorDoc[];
   numberPrefixParser: NumberPrefixParser;
   isCategoryIndex: CategoryIndexMatcher;
+  categoriesMetadata: Record<string, CategoryMetadataFile>;
   options: SidebarOptions;
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,
-) => // TODO TS issue: the generator can generate un-normalized items!
-Promise<SidebarItem[]>;
-// Promise<SidebarItemConfig[]>;
+) => Promise<NormalizedSidebar>;
 
-// Also inject the default generator to conveniently wrap/enhance/sort the default sidebar gen logic
+// Also inject the default generator to conveniently wrap/enhance/sort the
+// default sidebar gen logic
 // see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
 export type SidebarItemsGeneratorOptionArgs = {
   defaultSidebarItemsGenerator: SidebarItemsGenerator;
 } & SidebarItemsGeneratorArgs;
 export type SidebarItemsGeneratorOption = (
   generatorArgs: SidebarItemsGeneratorOptionArgs,
-) => Promise<SidebarItem[]>;
+) => Promise<NormalizedSidebarItem[]>;
+
+export type SidebarProcessorParams = {
+  sidebarItemsGenerator: SidebarItemsGeneratorOption;
+  numberPrefixParser: NumberPrefixParser;
+  docs: DocMetadataBase[];
+  version: VersionMetadata;
+  categoryLabelSlugger: Slugger;
+  sidebarOptions: SidebarOptions;
+};