@docusaurus/plugin-content-docs 0.0.0-4238 → 0.0.0-4243

package/src/sidebars/index.ts

@@ -8,11 +8,12 @@
 import fs from 'fs-extra';
 import importFresh from 'import-fresh';
 import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types';
-import type {PluginOptions} from '../types';
+import type {NormalizeSidebarsParams, PluginOptions} from '../types';
 import {validateSidebars} from './validation';
 import {normalizeSidebars} from './normalization';
-import {processSidebars, SidebarProcessorProps} from './processor';
+import {processSidebars, SidebarProcessorParams} from './processor';
 import path from 'path';
+import {createSlugger} from '@docusaurus/utils';
 
 export const DefaultSidebars: SidebarsConfig = {
   defaultSidebar: [
@@ -36,7 +37,7 @@ export function resolveSidebarPathOption(
     : sidebarPathOption;
 }
 
-function loadSidebarFile(
+function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
 ): SidebarsConfig {
   // false => no sidebars
@@ -60,25 +61,34 @@ function loadSidebarFile(
   return importFresh(sidebarFilePath);
 }
 
-export function loadUnprocessedSidebars(
+export function loadSidebarsFile(
   sidebarFilePath: string | false | undefined,
-  options: SidebarProcessorProps['options'],
-): NormalizedSidebars {
-  const sidebarsConfig = loadSidebarFile(sidebarFilePath);
+): SidebarsConfig {
+  const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
   validateSidebars(sidebarsConfig);
+  return sidebarsConfig;
+}
 
-  const normalizedSidebars = normalizeSidebars(sidebarsConfig, options);
-  return normalizedSidebars;
+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: SidebarProcessorProps,
+  options: SidebarProcessorParams,
 ): Promise<Sidebars> {
-  const unprocessedSidebars = loadUnprocessedSidebars(
+  const normalizeSidebarsParams: NormalizeSidebarsParams = {
+    ...options.sidebarOptions,
+    version: options.version,
+    categoryLabelSlugger: createSlugger(),
+  };
+  const normalizedSidebars = loadNormalizedSidebars(
     sidebarFilePath,
-    options.options,
+    normalizeSidebarsParams,
   );
-  return processSidebars(unprocessedSidebars, options);
+  return processSidebars(normalizedSidebars, options);
 }

package/src/sidebars/normalization.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {SidebarOptions} from '../types';
+import type {NormalizeSidebarsParams, SidebarOptions} from '../types';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,
@@ -15,9 +15,31 @@ import type {
   SidebarItemConfig,
   SidebarConfig,
   SidebarsConfig,
+  SidebarItemCategoryLink,
+  NormalizedSidebarItemCategory,
 } from './types';
-import {mapValues} from 'lodash';
 import {isCategoriesShorthand} from './utils';
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+
+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,
@@ -36,9 +58,9 @@ function normalizeCategoriesShorthand(
  * Normalizes recursively item and all its children. Ensures that at the end
  * each item will be an object with the corresponding type.
  */
-function normalizeItem(
+export function normalizeItem(
   item: SidebarItemConfig,
-  options: SidebarOptions,
+  options: NormalizeSidebarsParams,
 ): NormalizedSidebarItem[] {
   if (typeof item === 'string') {
     return [
@@ -49,40 +71,42 @@ function normalizeItem(
     ];
   }
   if (isCategoriesShorthand(item)) {
-    return normalizeCategoriesShorthand(item, options).flatMap((subitem) =>
-      normalizeItem(subitem, options),
+    return normalizeCategoriesShorthand(item, options).flatMap((subItem) =>
+      normalizeItem(subItem, options),
     );
   }
-  return item.type === 'category'
-    ? [
-        {
-          ...item,
-          items: item.items.flatMap((subItem) =>
-            normalizeItem(subItem, options),
-          ),
-          collapsible: item.collapsible ?? options.sidebarCollapsible,
-          collapsed: item.collapsed ?? options.sidebarCollapsed,
-        },
-      ]
-    : [item];
+  if (item.type === 'category') {
+    const link = normalizeCategoryLink(item, options);
+    const normalizedCategory: NormalizedSidebarItemCategory = {
+      ...item,
+      link,
+      items: (item.items ?? []).flatMap((subItem) =>
+        normalizeItem(subItem, options),
+      ),
+      collapsible: item.collapsible ?? options.sidebarCollapsible,
+      collapsed: item.collapsed ?? options.sidebarCollapsed,
+    };
+    return [normalizedCategory];
+  }
+  return [item];
 }
 
 function normalizeSidebar(
   sidebar: SidebarConfig,
-  options: SidebarOptions,
+  options: NormalizeSidebarsParams,
 ): NormalizedSidebar {
   const normalizedSidebar = Array.isArray(sidebar)
     ? sidebar
     : normalizeCategoriesShorthand(sidebar, options);
 
-  return normalizedSidebar.flatMap((subitem) =>
-    normalizeItem(subitem, options),
+  return normalizedSidebar.flatMap((subItem) =>
+    normalizeItem(subItem, options),
   );
 }
 
 export function normalizeSidebars(
   sidebars: SidebarsConfig,
-  options: SidebarOptions,
+  params: NormalizeSidebarsParams,
 ): NormalizedSidebars {
-  return mapValues(sidebars, (subitem) => normalizeSidebar(subitem, options));
+  return mapValues(sidebars, (items) => normalizeSidebar(items, params));
 }

package/src/sidebars/processor.ts

@@ -21,18 +21,24 @@ import type {
   SidebarItemsGeneratorOption,
   SidebarItemsGeneratorDoc,
   SidebarItemsGeneratorVersion,
+  NormalizedSidebarItemCategory,
+  SidebarItemCategory,
+  SidebarItemAutogenerated,
 } from './types';
 import {transformSidebarItems} from './utils';
 import {DefaultSidebarItemsGenerator} from './generator';
 import {mapValues, memoize, pick} from 'lodash';
 import combinePromises from 'combine-promises';
+import {normalizeItem} from './normalization';
+import {Slugger} from '@docusaurus/utils';
 
-export type SidebarProcessorProps = {
+export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;
   numberPrefixParser: NumberPrefixParser;
   docs: DocMetadataBase[];
   version: VersionMetadata;
-  options: SidebarOptions;
+  categoryLabelSlugger: Slugger;
+  sidebarOptions: SidebarOptions;
 };
 
 function toSidebarItemsGeneratorDoc(
@@ -40,6 +46,7 @@ function toSidebarItemsGeneratorDoc(
 ): SidebarItemsGeneratorDoc {
   return pick(doc, [
     'id',
+    'unversionedId',
     'frontMatter',
     'source',
     'sourceDirName',
@@ -56,48 +63,71 @@ function toSidebarItemsGeneratorVersion(
 // Handle the generation of autogenerated sidebar items and other post-processing checks
 async function processSidebar(
   unprocessedSidebar: NormalizedSidebar,
-  {
+  params: SidebarProcessorParams,
+): Promise<Sidebar> {
+  const {
     sidebarItemsGenerator,
     numberPrefixParser,
     docs,
     version,
-    options,
-  }: SidebarProcessorProps,
-): Promise<Sidebar> {
+    sidebarOptions,
+  } = params;
+
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = memoize(() => ({
     docs: docs.map(toSidebarItemsGeneratorDoc),
     version: toSidebarItemsGeneratorVersion(version),
   }));
 
-  async function handleAutoGeneratedItems(
+  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)
+    const generatedItems = await sidebarItemsGenerator({
+      item,
+      numberPrefixParser,
+      defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      ...getSidebarItemsGeneratorDocsAndVersion(),
+      options: sidebarOptions,
+    });
+    // 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);
+  }
+
+  async function processItem(
     item: NormalizedSidebarItem,
   ): Promise<SidebarItem[]> {
     if (item.type === 'category') {
-      return [
-        {
-          ...item,
-          items: (
-            await Promise.all(item.items.map(handleAutoGeneratedItems))
-          ).flat(),
-        },
-      ];
+      return [await processCategoryItem(item)];
     }
     if (item.type === 'autogenerated') {
-      return sidebarItemsGenerator({
-        item,
-        numberPrefixParser,
-        defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
-        ...getSidebarItemsGeneratorDocsAndVersion(),
-        options,
-      });
+      return processAutoGeneratedItem(item);
     }
     return [item];
   }
 
-  const processedSidebar = (
-    await Promise.all(unprocessedSidebar.map(handleAutoGeneratedItems))
-  ).flat();
+  async function processItems(
+    items: NormalizedSidebarItem[],
+  ): Promise<SidebarItem[]> {
+    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!
@@ -114,11 +144,11 @@ async function processSidebar(
 
 export async function processSidebars(
   unprocessedSidebars: NormalizedSidebars,
-  props: SidebarProcessorProps,
+  params: SidebarProcessorParams,
 ): Promise<Sidebars> {
   return combinePromises(
     mapValues(unprocessedSidebars, (unprocessedSidebar) =>
-      processSidebar(unprocessedSidebar, props),
+      processSidebar(unprocessedSidebar, params),
     ),
   );
 }

package/src/sidebars/types.ts

@@ -12,6 +12,7 @@ import type {
   NumberPrefixParser,
   SidebarOptions,
 } from '../types';
+import {Required} from 'utility-types';
 
 // Makes all properties visible when hovering over the type
 type Expand<T extends Record<string, unknown>> = {[P in keyof T]: T[P]};
@@ -45,10 +46,35 @@ type SidebarItemCategoryBase = SidebarItemBase & {
   collapsible: boolean;
 };
 
+export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string};
+
+export type SidebarItemCategoryLinkGeneratedIndexConfig = {
+  type: 'generated-index';
+  slug?: string;
+  title?: string;
+  description?: string;
+};
+export type SidebarItemCategoryLinkGeneratedIndex = {
+  type: 'generated-index';
+  slug: string;
+  permalink: string;
+  title?: string;
+  description?: string;
+};
+
+export type SidebarItemCategoryLinkConfig =
+  | SidebarItemCategoryLinkDoc
+  | SidebarItemCategoryLinkGeneratedIndexConfig;
+
+export type SidebarItemCategoryLink =
+  | SidebarItemCategoryLinkDoc
+  | SidebarItemCategoryLinkGeneratedIndex;
+
 // The user-given configuration in sidebars.js, before normalization
 export type SidebarItemCategoryConfig = Expand<
   Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: SidebarItemConfig[];
+    link?: SidebarItemCategoryLinkConfig;
   }
 >;
 
@@ -73,6 +99,7 @@ export type SidebarsConfig = {
 export type NormalizedSidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLink;
   }
 >;
 
@@ -90,14 +117,25 @@ export type NormalizedSidebars = {
 export type SidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: SidebarItem[];
+    link?: SidebarItemCategoryLink;
   }
 >;
 
+export type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
+
+export type SidebarItemCategoryWithGeneratedIndex =
+  SidebarItemCategoryWithLink & {link: SidebarItemCategoryLinkGeneratedIndex};
+
 export type SidebarItem =
   | SidebarItemDoc
   | SidebarItemLink
   | SidebarItemCategory;
 
+// A sidebar item that is part of the previous/next ordered navigation
+export type SidebarNavigationItem =
+  | SidebarItemDoc
+  | SidebarItemCategoryWithLink;
+
 export type Sidebar = SidebarItem[];
 export type SidebarItemType = SidebarItem['type'];
 export type Sidebars = {
@@ -108,21 +146,42 @@ export type Sidebars = {
 export type PropSidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: PropSidebarItem[];
+    href?: string;
   }
 >;
 
-export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+// we may want to use a union type in props instead of this generic link?
+export type PropSidebarItemLink = SidebarItemLink & {
+  docId?: string;
+};
+
+export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
 export type PropSidebar = PropSidebarItem[];
 export type PropSidebars = {
   [sidebarId: string]: PropSidebar;
 };
 
+export type PropVersionDoc = {
+  id: string;
+  title: string;
+  description?: string;
+  sidebar?: string;
+};
+export type PropVersionDocs = {
+  [docId: string]: PropVersionDoc;
+};
+
 // 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
 export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
-  'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'
+  | 'id'
+  | 'unversionedId'
+  | 'frontMatter'
+  | 'source'
+  | 'sourceDirName'
+  | 'sidebarPosition'
 >;
 export type SidebarItemsGeneratorVersion = Pick<
   VersionMetadata,
@@ -138,7 +197,9 @@ export type SidebarItemsGeneratorArgs = {
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,
-) => Promise<SidebarItem[]>;
+) => // TODO TS issue: the generator can generate un-normalized items!
+Promise<SidebarItem[]>;
+// Promise<SidebarItemConfig[]>;
 
 // 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