@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4244

package/src/sidebars/utils.ts

@@ -16,8 +16,15 @@ import type {
   SidebarCategoriesShorthand,
   SidebarItemConfig,
 } from './types';
-import {mapValues, difference} from 'lodash';
+
+import {mapValues, difference, uniq} from 'lodash';
 import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
+import {DocMetadataBase, DocNavLink} from '../types';
+import {
+  SidebarItemCategoryWithGeneratedIndex,
+  SidebarItemCategoryWithLink,
+  SidebarNavigationItem,
+} from './types';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
@@ -41,21 +48,24 @@ export function transformSidebarItems(
   return sidebar.map(transformRecursive);
 }
 
+// Flatten sidebar items into a single flat array (containing categories/docs on the same level)
+// /!\ order matters (useful for next/prev nav), top categories appear before their child elements
+function flattenSidebarItems(items: SidebarItem[]): SidebarItem[] {
+  function flattenRecursive(item: SidebarItem): SidebarItem[] {
+    return item.type === 'category'
+      ? [item, ...item.items.flatMap(flattenRecursive)]
+      : [item];
+  }
+  return items.flatMap(flattenRecursive);
+}
+
 function collectSidebarItemsOfType<
   Type extends SidebarItemType,
   Item extends SidebarItem & {type: SidebarItemType},
 >(type: Type, sidebar: Sidebar): Item[] {
-  function collectRecursive(item: SidebarItem): Item[] {
-    const currentItemsCollected: Item[] =
-      item.type === type ? [item as Item] : [];
-
-    const childItemsCollected: Item[] =
-      item.type === 'category' ? item.items.flatMap(collectRecursive) : [];
-
-    return [...currentItemsCollected, ...childItemsCollected];
-  }
-
-  return sidebar.flatMap(collectRecursive);
+  return flattenSidebarItems(sidebar).filter(
+    (item) => item.type === type,
+  ) as Item[];
 }
 
 export function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[] {
@@ -70,25 +80,72 @@ export function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[] {
   return collectSidebarItemsOfType('link', sidebar);
 }
 
+// /!\ docId order matters for navigation!
+export function collectSidebarDocIds(sidebar: Sidebar): string[] {
+  return flattenSidebarItems(sidebar).flatMap((item) => {
+    if (item.type === 'category') {
+      return item.link?.type === 'doc' ? [item.link.id] : [];
+    }
+    if (item.type === 'doc') {
+      return [item.id];
+    }
+    return [];
+  });
+}
+
+export function collectSidebarNavigation(
+  sidebar: Sidebar,
+): SidebarNavigationItem[] {
+  return flattenSidebarItems(sidebar).flatMap((item) => {
+    if (item.type === 'category' && item.link) {
+      return [item as SidebarNavigationItem];
+    }
+    if (item.type === 'doc') {
+      return [item];
+    }
+    return [];
+  });
+}
+
 export function collectSidebarsDocIds(
   sidebars: Sidebars,
 ): Record<string, string[]> {
-  return mapValues(sidebars, (sidebar) =>
-    collectSidebarDocItems(sidebar).map((docItem) => docItem.id),
-  );
+  return mapValues(sidebars, collectSidebarDocIds);
+}
+
+export function collectSidebarsNavigations(
+  sidebars: Sidebars,
+): Record<string, SidebarNavigationItem[]> {
+  return mapValues(sidebars, collectSidebarNavigation);
 }
 
-export function createSidebarsUtils(sidebars: Sidebars): {
+export type SidebarNavigation = {
+  sidebarName: string | undefined;
+  previous: SidebarNavigationItem | undefined;
+  next: SidebarNavigationItem | undefined;
+};
+
+// A convenient and performant way to query the sidebars content
+export type SidebarsUtils = {
+  sidebars: Sidebars;
   getFirstDocIdOfFirstSidebar: () => string | undefined;
   getSidebarNameByDocId: (docId: string) => string | undefined;
-  getDocNavigation: (docId: string) => {
-    sidebarName: string | undefined;
-    previousId: string | undefined;
-    nextId: string | undefined;
-  };
+  getDocNavigation: (
+    unversionedId: string,
+    versionedId: string,
+  ) => SidebarNavigation;
+  getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
+  getCategoryGeneratedIndexNavigation: (
+    categoryGeneratedIndexPermalink: string,
+  ) => SidebarNavigation;
+
   checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
-} {
+};
+
+export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
   const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
+  const sidebarNameToNavigationItems = collectSidebarsNavigations(sidebars);
+
   // Reverse mapping
   const docIdToSidebarName = Object.fromEntries(
     Object.entries(sidebarNameToDocIds).flatMap(([sidebarName, docIds]) =>
@@ -104,27 +161,91 @@ export function createSidebarsUtils(sidebars: Sidebars): {
     return docIdToSidebarName[docId];
   }
 
-  function getDocNavigation(docId: string): {
-    sidebarName: string | undefined;
-    previousId: string | undefined;
-    nextId: string | undefined;
-  } {
-    const sidebarName = getSidebarNameByDocId(docId);
+  function emptySidebarNavigation(): SidebarNavigation {
+    return {
+      sidebarName: undefined,
+      previous: undefined,
+      next: undefined,
+    };
+  }
+
+  function getDocNavigation(
+    unversionedId: string,
+    versionedId: string,
+  ): SidebarNavigation {
+    // TODO legacy id retro-compatibility!
+    let docId = unversionedId;
+    let sidebarName = getSidebarNameByDocId(docId);
+    if (!sidebarName) {
+      docId = versionedId;
+      sidebarName = getSidebarNameByDocId(docId);
+    }
+
     if (sidebarName) {
-      const docIds = sidebarNameToDocIds[sidebarName];
-      const currentIndex = docIds.indexOf(docId);
-      const {previous, next} = getElementsAround(docIds, currentIndex);
-      return {
-        sidebarName,
-        previousId: previous,
-        nextId: next,
-      };
+      const navigationItems = sidebarNameToNavigationItems[sidebarName];
+      const currentItemIndex = navigationItems.findIndex((item) => {
+        if (item.type === 'doc') {
+          return item.id === docId;
+        }
+        if (item.type === 'category' && item.link.type === 'doc') {
+          return item.link.id === docId;
+        }
+        return false;
+      });
+
+      const {previous, next} = getElementsAround(
+        navigationItems,
+        currentItemIndex,
+      );
+      return {sidebarName, previous, next};
     } else {
-      return {
-        sidebarName: undefined,
-        previousId: undefined,
-        nextId: undefined,
-      };
+      return emptySidebarNavigation();
+    }
+  }
+
+  function getCategoryGeneratedIndexList(): SidebarItemCategoryWithGeneratedIndex[] {
+    return Object.values(sidebarNameToNavigationItems)
+      .flat()
+      .flatMap((item) => {
+        if (item.type === 'category' && item.link.type === 'generated-index') {
+          return [item as SidebarItemCategoryWithGeneratedIndex];
+        }
+        return [];
+      });
+  }
+
+  // We identity the category generated index by its permalink (should be unique)
+  // More reliable than using object identity
+  function getCategoryGeneratedIndexNavigation(
+    categoryGeneratedIndexPermalink: string,
+  ): SidebarNavigation {
+    function isCurrentCategoryGeneratedIndexItem(
+      item: SidebarNavigationItem,
+    ): boolean {
+      return (
+        item.type === 'category' &&
+        item.link?.type === 'generated-index' &&
+        item.link.permalink === categoryGeneratedIndexPermalink
+      );
+    }
+
+    const sidebarName = Object.entries(sidebarNameToNavigationItems).find(
+      ([, navigationItems]) =>
+        navigationItems.find(isCurrentCategoryGeneratedIndexItem),
+    )?.[0];
+
+    if (sidebarName) {
+      const navigationItems = sidebarNameToNavigationItems[sidebarName];
+      const currentItemIndex = navigationItems.findIndex(
+        isCurrentCategoryGeneratedIndexItem,
+      );
+      const {previous, next} = getElementsAround(
+        navigationItems,
+        currentItemIndex,
+      );
+      return {sidebarName, previous, next};
+    } else {
+      return emptySidebarNavigation();
     }
   }
 
@@ -140,15 +261,69 @@ These sidebar document ids do not exist:
 - ${invalidSidebarDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${validDocIds.sort().join('\n- ')}`,
+- ${uniq(validDocIds).sort().join('\n- ')}`,
       );
     }
   }
 
   return {
+    sidebars,
     getFirstDocIdOfFirstSidebar,
     getSidebarNameByDocId,
     getDocNavigation,
+    getCategoryGeneratedIndexList,
+    getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
   };
 }
+
+export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
+  const {
+    title,
+    permalink,
+    frontMatter: {
+      pagination_label: paginationLabel,
+      sidebar_label: sidebarLabel,
+    },
+  } = doc;
+  return {title: paginationLabel ?? sidebarLabel ?? title, permalink};
+}
+
+export function toNavigationLink(
+  navigationItem: SidebarNavigationItem | undefined,
+  docsById: Record<string, DocMetadataBase>,
+): DocNavLink | undefined {
+  function getDocById(docId: string) {
+    const doc = docsById[docId];
+    if (!doc) {
+      throw new Error(
+        `Can't create navigation link: no doc found with id=${docId}`,
+      );
+    }
+    return doc;
+  }
+
+  function handleCategory(category: SidebarItemCategoryWithLink): DocNavLink {
+    if (category.link.type === 'doc') {
+      return toDocNavigationLink(getDocById(category.link.id));
+    } else if (category.link.type === 'generated-index') {
+      return {
+        title: category.label,
+        permalink: category.link.permalink,
+      };
+    } else {
+      throw new Error('unexpected category link type');
+    }
+  }
+  if (!navigationItem) {
+    return undefined;
+  }
+
+  if (navigationItem.type === 'doc') {
+    return toDocNavigationLink(getDocById(navigationItem.id));
+  } else if (navigationItem.type === 'category') {
+    return handleCategory(navigationItem);
+  } else {
+    throw new Error('unexpected navigation item');
+  }
+}

package/src/sidebars/validation.ts

@@ -14,9 +14,13 @@ import type {
   SidebarItemDoc,
   SidebarItemLink,
   SidebarItemCategoryConfig,
+  SidebarItemCategoryLink,
   SidebarsConfig,
+  SidebarItemCategoryLinkDoc,
+  SidebarItemCategoryLinkGeneratedIndex,
 } from './types';
 import {isCategoriesShorthand} from './utils';
+import {CategoryMetadataFile} from './generator';
 
 const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
   className: Joi.string(),
@@ -48,6 +52,36 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
     .messages({'any.unknown': '"label" must be a string'}),
 });
 
+const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
+  .when('.type', {
+    switch: [
+      {
+        is: 'doc',
+        then: Joi.object<SidebarItemCategoryLinkDoc>({
+          type: 'doc',
+          id: Joi.string().required(),
+        }),
+      },
+      {
+        is: 'generated-index',
+        then: Joi.object<SidebarItemCategoryLinkGeneratedIndex>({
+          type: 'generated-index',
+          slug: Joi.string().optional(),
+          // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
+          title: Joi.string().optional(),
+          description: Joi.string().optional(),
+        }),
+      },
+      {
+        is: Joi.string().required(),
+        then: Joi.forbidden().messages({
+          'any.unknown': 'Unknown sidebar category link type "{.type}".',
+        }),
+      },
+    ],
+  })
+  .id('sidebarCategoryLinkSchema');
+
 const sidebarItemCategorySchema =
   sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
     type: 'category',
@@ -58,6 +92,7 @@ const sidebarItemCategorySchema =
     items: Joi.array()
       .required()
       .messages({'any.unknown': '"items" must be an array'}), // .items(Joi.link('#sidebarItemSchema')),
+    link: sidebarItemCategoryLinkSchema,
     collapsed: Joi.boolean().messages({
       'any.unknown': '"collapsed" must be a boolean',
     }),
@@ -77,14 +112,7 @@ const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
       {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
       {is: 'category', then: sidebarItemCategorySchema},
       {
-        is: 'subcategory',
-        then: Joi.forbidden().messages({
-          'any.unknown':
-            'Docusaurus v2: "subcategory" has been renamed as "category".',
-        }),
-      },
-      {
-        is: Joi.string().required(),
+        is: Joi.any().required(),
         then: Joi.forbidden().messages({
           'any.unknown': 'Unknown sidebar item type "{.type}".',
         }),
@@ -105,6 +133,7 @@ function validateSidebarItem(item: unknown): asserts item is SidebarItemConfig {
     );
   } else {
     Joi.assert(item, sidebarItemSchema);
+
     if ((item as SidebarItemCategoryConfig).type === 'category') {
       (item as SidebarItemCategoryConfig).items.forEach(validateSidebarItem);
     }
@@ -122,3 +151,18 @@ export function validateSidebars(
     }
   });
 }
+
+const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
+  label: Joi.string(),
+  position: Joi.number(),
+  collapsed: Joi.boolean(),
+  collapsible: Joi.boolean(),
+  className: Joi.string(),
+  link: sidebarItemCategoryLinkSchema,
+});
+
+export function validateCategoryMetadataFile(
+  unsafeContent: unknown,
+): CategoryMetadataFile {
+  return Joi.attempt(unsafeContent, categoryMetadataFileSchema);
+}

package/src/slug.ts

@@ -15,39 +15,52 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import type {NumberPrefixParser} from './types';
+import type {DocMetadataBase, NumberPrefixParser} from './types';
+import {isConventionalDocIndex} from './docs';
 
 export default function getSlug({
   baseID,
   frontmatterSlug,
-  dirName,
+  source,
+  sourceDirName,
   stripDirNumberPrefixes = true,
   numberPrefixParser = DefaultNumberPrefixParser,
 }: {
   baseID: string;
   frontmatterSlug?: string;
-  dirName: string;
+  source: DocMetadataBase['slug'];
+  sourceDirName: DocMetadataBase['sourceDirName'];
   stripDirNumberPrefixes?: boolean;
   numberPrefixParser?: NumberPrefixParser;
 }): string {
-  const baseSlug = frontmatterSlug || baseID;
-  let slug: string;
-  if (baseSlug.startsWith('/')) {
-    slug = baseSlug;
-  } else {
+  function getDirNameSlug(): string {
     const dirNameStripped = stripDirNumberPrefixes
-      ? stripPathNumberPrefixes(dirName, numberPrefixParser)
-      : dirName;
+      ? stripPathNumberPrefixes(sourceDirName, numberPrefixParser)
+      : sourceDirName;
     const resolveDirname =
-      dirName === '.'
+      sourceDirName === '.'
         ? '/'
         : addLeadingSlash(addTrailingSlash(dirNameStripped));
-    slug = resolvePathname(baseSlug, resolveDirname);
+    return resolveDirname;
   }
 
-  if (!isValidPathname(slug)) {
-    throw new Error(
-      `We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+  function computeSlug(): string {
+    if (frontmatterSlug?.startsWith('/')) {
+      return frontmatterSlug;
+    } else {
+      const dirNameSlug = getDirNameSlug();
+      if (!frontmatterSlug && isConventionalDocIndex({source, sourceDirName})) {
+        return dirNameSlug;
+      }
+      const baseSlug = frontmatterSlug || baseID;
+      return resolvePathname(baseSlug, getDirNameSlug());
+    }
+  }
+
+  function ensureValidSlug(slug: string): string {
+    if (!isValidPathname(slug)) {
+      throw new Error(
+        `We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" directory.
 The slug we computed looks invalid: ${slug}.
 Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
 By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
@@ -57,8 +70,10 @@ Example =>
 slug: /my/customDocPath
 ---
 `,
-    );
+      );
+    }
+    return slug;
   }
 
-  return slug;
+  return ensureValidSlug(computeSlug());
 }

package/src/translations.ts

@@ -6,7 +6,12 @@
  */
 
 import type {LoadedVersion, LoadedContent} from './types';
-import type {Sidebar, Sidebars} from './sidebars/types';
+import type {
+  Sidebar,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+  Sidebars,
+} from './sidebars/types';
 
 import {chain, mapValues, keyBy} from 'lodash';
 import {
@@ -21,6 +26,7 @@ import type {
 } from '@docusaurus/types';
 import {mergeTranslations} from '@docusaurus/utils';
 import {CURRENT_VERSION_NAME} from './constants';
+import {TranslationMessage} from '@docusaurus/types';
 
 function getVersionFileName(versionName: string): string {
   if (versionName === CURRENT_VERSION_NAME) {
@@ -96,14 +102,48 @@ function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
 ): TranslationFileContent {
+  type TranslationMessageEntry = [string, TranslationMessage];
+
   const categories = collectSidebarCategories(sidebar);
-  const categoryContent: TranslationFileContent = chain(categories)
-    .keyBy((category) => `sidebar.${sidebarName}.category.${category.label}`)
-    .mapValues((category) => ({
-      message: category.label,
-      description: `The label for category ${category.label} in sidebar ${sidebarName}`,
-    }))
-    .value();
+
+  const categoryContent: TranslationFileContent = Object.fromEntries(
+    categories.flatMap((category) => {
+      const entries: TranslationMessageEntry[] = [];
+
+      entries.push([
+        `sidebar.${sidebarName}.category.${category.label}`,
+        {
+          message: category.label,
+          description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+        },
+      ]);
+
+      if (category.link) {
+        if (category.link.type === 'generated-index') {
+          if (category.link.title) {
+            entries.push([
+              `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`,
+              {
+                message: category.link.title,
+                description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
+              },
+            ]);
+          }
+          if (category.link.description) {
+            entries.push([
+              `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`,
+              {
+                message: category.link.description,
+                description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
+              },
+            ]);
+          }
+        }
+      }
+
+      return entries;
+    }),
+  );
 
   const links = collectSidebarLinks(sidebar);
   const linksContent: TranslationFileContent = chain(links)
@@ -126,13 +166,39 @@ function translateSidebar({
   sidebarName: string;
   sidebarsTranslations: TranslationFileContent;
 }): Sidebar {
+  function transformSidebarCategoryLink(
+    category: SidebarItemCategory,
+  ): SidebarItemCategoryLink | undefined {
+    if (!category.link) {
+      return undefined;
+    }
+    if (category.link.type === 'generated-index') {
+      const title =
+        sidebarsTranslations[
+          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`
+        ]?.message ?? category.link.title;
+      const description =
+        sidebarsTranslations[
+          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`
+        ]?.message ?? category.link.description;
+      return {
+        ...category.link,
+        title,
+        description,
+      };
+    }
+    return category.link;
+  }
+
   return transformSidebarItems(sidebar, (item) => {
     if (item.type === 'category') {
+      const link = transformSidebarCategoryLink(item);
       return {
         ...item,
         label:
           sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]
             ?.message ?? item.label,
+        ...(link && {link}),
       };
     }
     if (item.type === 'link') {

package/src/types.ts

@@ -8,7 +8,7 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import type {Tag, FrontMatterTag} from '@docusaurus/utils';
+import type {Tag, FrontMatterTag, Slugger} from '@docusaurus/utils';
 import type {
   BrokenMarkdownLink as IBrokenMarkdownLink,
   ContentPaths,
@@ -86,6 +86,11 @@ export type SidebarOptions = {
   sidebarCollapsed: boolean;
 };
 
+export type NormalizeSidebarsParams = SidebarOptions & {
+  version: VersionMetadata;
+  categoryLabelSlugger: Slugger;
+};
+
 export type PluginOptions = MetadataOptions &
   PathOptions &
   VersionsOptions &
@@ -98,6 +103,7 @@ export type PluginOptions = MetadataOptions &
     docItemComponent: string;
     docTagDocListComponent: string;
     docTagsListComponent: string;
+    docCategoryGeneratedIndexComponent: string;
     admonitions: Record<string, unknown>;
     disableVersioning: boolean;
     includeCurrentVersion: boolean;
@@ -135,14 +141,14 @@ export type DocFrontMatter = {
 };
 
 export type DocMetadataBase = LastUpdateData & {
+  id: string; // TODO legacy versioned id => try to remove
+  unversionedId: string; // TODO new unversioned id => try to rename to "id"
   version: VersionName;
-  unversionedId: string;
-  id: string;
   isDocsHomePage: boolean;
   title: string;
   description: string;
-  source: string;
-  sourceDirName: string; // relative to the docs folder (can be ".")
+  source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
+  sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
   slug: string;
   permalink: string;
   sidebarPosition?: number;
@@ -162,6 +168,16 @@ export type DocMetadata = DocMetadataBase & {
   next?: DocNavLink;
 };
 
+export type CategoryGeneratedIndexMetadata = {
+  title: string;
+  description?: string;
+  slug: string;
+  permalink: string;
+  sidebar: string;
+  previous?: DocNavLink;
+  next?: DocNavLink;
+};
+
 export type SourceToPermalink = {
   [source: string]: string;
 };
@@ -180,6 +196,7 @@ export type LoadedVersion = VersionMetadata & {
   mainDocId: string;
   docs: DocMetadata[];
   sidebars: Sidebars;
+  categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
 
 export type LoadedContent = {