@docusaurus/plugin-content-docs 0.0.0-4546 → 0.0.0-4550

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]};
@@ -82,13 +83,13 @@ 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 =
@@ -107,9 +108,9 @@ 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;
   }
 >;
 
@@ -125,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[];
@@ -230,9 +247,7 @@ export type SidebarItemsGeneratorArgs = {
 };
 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
@@ -242,4 +257,13 @@ export type SidebarItemsGeneratorOptionArgs = {
 } & 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;
+};

package/src/sidebars/validation.ts

@@ -8,7 +8,6 @@
 import {Joi, URISchema} from '@docusaurus/utils-validation';
 import type {
   SidebarItemConfig,
-  SidebarCategoriesShorthand,
   SidebarItemBase,
   SidebarItemAutogenerated,
   SidebarItemDoc,
@@ -16,12 +15,13 @@ import type {
   SidebarItemLink,
   SidebarItemCategoryConfig,
   SidebarItemCategoryLink,
-  SidebarsConfig,
   SidebarItemCategoryLinkDoc,
   SidebarItemCategoryLinkGeneratedIndex,
+  NormalizedSidebars,
+  NormalizedSidebarItem,
+  NormalizedSidebarItemCategory,
   CategoryMetadataFile,
 } from './types';
-import {isCategoriesShorthand} from './utils';
 
 // NOTE: we don't add any default values during validation on purpose!
 // Config types are exposed to users for typechecking and we use the same type
@@ -52,7 +52,7 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
 const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
   type: 'html',
   value: Joi.string().required(),
-  defaultStyle: Joi.boolean().default(false),
+  defaultStyle: Joi.boolean(),
 });
 
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
@@ -88,14 +88,13 @@ const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
         }),
       },
       {
-        is: Joi.string().required(),
+        is: Joi.required(),
         then: Joi.forbidden().messages({
           'any.unknown': 'Unknown sidebar category link type "{.type}".',
         }),
       },
     ],
-  })
-  .id('sidebarCategoryLinkSchema');
+  });
 
 const sidebarItemCategorySchema =
   sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
@@ -103,10 +102,11 @@ const sidebarItemCategorySchema =
     label: Joi.string()
       .required()
       .messages({'any.unknown': '"label" must be a string'}),
-    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
     items: Joi.array()
       .required()
-      .messages({'any.unknown': '"items" must be an array'}), // .items(Joi.link('#sidebarItemSchema')),
+      .messages({'any.unknown': '"items" must be an array'}),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    // .items(Joi.link('#sidebarItemSchema')),
     link: sidebarItemCategoryLinkSchema,
     collapsed: Joi.boolean().messages({
       'any.unknown': '"collapsed" must be a boolean',
@@ -116,56 +116,44 @@ const sidebarItemCategorySchema =
     }),
   });
 
-const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
-  .when('.type', {
-    switch: [
-      {is: 'link', then: sidebarItemLinkSchema},
-      {
-        is: Joi.string().valid('doc', 'ref').required(),
-        then: sidebarItemDocSchema,
-      },
-      {is: 'html', then: sidebarItemHtmlSchema},
-      {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
-      {is: 'category', then: sidebarItemCategorySchema},
-      {
-        is: Joi.any().required(),
-        then: Joi.forbidden().messages({
-          'any.unknown': 'Unknown sidebar item type "{.type}".',
-        }),
-      },
-    ],
-  })
-  .id('sidebarItemSchema');
+const sidebarItemSchema = Joi.object<SidebarItemConfig>().when('.type', {
+  switch: [
+    {is: 'link', then: sidebarItemLinkSchema},
+    {
+      is: Joi.string().valid('doc', 'ref').required(),
+      then: sidebarItemDocSchema,
+    },
+    {is: 'html', then: sidebarItemHtmlSchema},
+    {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
+    {is: 'category', then: sidebarItemCategorySchema},
+    {
+      is: Joi.any().required(),
+      then: Joi.forbidden().messages({
+        'any.unknown': 'Unknown sidebar item type "{.type}".',
+      }),
+    },
+  ],
+});
+// .id('sidebarItemSchema');
 
-function validateSidebarItem(item: unknown): asserts item is SidebarItemConfig {
-  if (typeof item === 'string') {
-    return;
-  }
+function validateSidebarItem(
+  item: unknown,
+): asserts item is NormalizedSidebarItem {
   // TODO: remove once with proper Joi support
   // Because we can't use Joi to validate nested items (see above), we do it
   // manually
-  if (isCategoriesShorthand(item as SidebarItemConfig)) {
-    Object.values(item as SidebarCategoriesShorthand).forEach((category) =>
-      category.forEach(validateSidebarItem),
-    );
-  } else {
-    Joi.assert(item, sidebarItemSchema);
+  Joi.assert(item, sidebarItemSchema);
 
-    if ((item as SidebarItemCategoryConfig).type === 'category') {
-      (item as SidebarItemCategoryConfig).items.forEach(validateSidebarItem);
-    }
+  if ((item as NormalizedSidebarItemCategory).type === 'category') {
+    (item as NormalizedSidebarItemCategory).items.forEach(validateSidebarItem);
   }
 }
 
 export function validateSidebars(
-  sidebars: unknown,
-): asserts sidebars is SidebarsConfig {
-  Object.values(sidebars as SidebarsConfig).forEach((sidebar) => {
-    if (Array.isArray(sidebar)) {
-      sidebar.forEach(validateSidebarItem);
-    } else {
-      validateSidebarItem(sidebar);
-    }
+  sidebars: Record<string, unknown>,
+): asserts sidebars is NormalizedSidebars {
+  Object.values(sidebars as NormalizedSidebars).forEach((sidebar) => {
+    sidebar.forEach(validateSidebarItem);
   });
 }
 

package/src/types.ts

@@ -8,15 +8,12 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {Sidebars} from './sidebars/types';
-import type {Tag, FrontMatterTag, Slugger} from '@docusaurus/utils';
+import type {Tag, FrontMatterTag} from '@docusaurus/utils';
 import type {
   BrokenMarkdownLink as IBrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
-import type {
-  VersionBanner,
-  SidebarOptions,
-} from '@docusaurus/plugin-content-docs';
+import type {VersionBanner} from '@docusaurus/plugin-content-docs';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -41,11 +38,6 @@ export type VersionMetadata = ContentPaths & {
   routePriority: number | undefined; // -1 for the latest docs
 };
 
-export type NormalizeSidebarsParams = SidebarOptions & {
-  version: VersionMetadata;
-  categoryLabelSlugger: Slugger;
-};
-
 export type LastUpdateData = {
   lastUpdatedAt?: number;
   formattedLastUpdatedAt?: string;