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

package/src/sidebars/utils.ts

@@ -16,18 +16,17 @@ import type {
   SidebarCategoriesShorthand,
   SidebarItemConfig,
   SidebarItemCategoryWithGeneratedIndex,
-  SidebarItemCategoryWithLink,
   SidebarNavigationItem,
 } from './types';
 
-import {mapValues, difference, uniq} from 'lodash';
+import _ from 'lodash';
 import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
 import type {DocMetadataBase, DocNavLink} from '../types';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
 ): item is SidebarCategoriesShorthand {
-  return typeof item !== 'string' && !item.type;
+  return typeof item === 'object' && !item.type;
 }
 
 export function transformSidebarItems(
@@ -46,8 +45,11 @@ 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
+/**
+ * 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'
@@ -108,13 +110,13 @@ export function collectSidebarNavigation(
 export function collectSidebarsDocIds(
   sidebars: Sidebars,
 ): Record<string, string[]> {
-  return mapValues(sidebars, collectSidebarDocIds);
+  return _.mapValues(sidebars, collectSidebarDocIds);
 }
 
 export function collectSidebarsNavigations(
   sidebars: Sidebars,
 ): Record<string, SidebarNavigationItem[]> {
-  return mapValues(sidebars, collectSidebarNavigation);
+  return _.mapValues(sidebars, collectSidebarNavigation);
 }
 
 export type SidebarNavigation = {
@@ -196,34 +198,33 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
       sidebarName = getSidebarNameByDocId(docId);
     }
 
-    if (sidebarName) {
-      if (!sidebarNameToNavigationItems[sidebarName]) {
-        throw new Error(
-          `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
-        );
+    if (!sidebarName) {
+      return emptySidebarNavigation();
+    }
+    if (!sidebarNameToNavigationItems[sidebarName]) {
+      throw new Error(
+        `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
+      );
+    }
+    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    const currentItemIndex = navigationItems.findIndex((item) => {
+      if (item.type === 'doc') {
+        return item.id === docId;
       }
-      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;
-      });
-      if (currentItemIndex === -1) {
-        return {sidebarName, next: undefined, previous: undefined};
+      if (item.type === 'category' && item.link.type === 'doc') {
+        return item.link.id === docId;
       }
-
-      const {previous, next} = getElementsAround(
-        navigationItems,
-        currentItemIndex,
-      );
-      return {sidebarName, previous, next};
-    } else {
-      return emptySidebarNavigation();
+      return false;
+    });
+    if (currentItemIndex === -1) {
+      return {sidebarName, next: undefined, previous: undefined};
     }
+
+    const {previous, next} = getElementsAround(
+      navigationItems,
+      currentItemIndex,
+    );
+    return {sidebarName, previous, next};
   }
 
   function getCategoryGeneratedIndexList(): SidebarItemCategoryWithGeneratedIndex[] {
@@ -237,8 +238,10 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
       });
   }
 
-  // We identity the category generated index by its permalink (should be unique)
-  // More reliable than using object identity
+  /**
+   * We identity the category generated index by its permalink (should be
+   * unique). More reliable than using object identity
+   */
   function getCategoryGeneratedIndexNavigation(
     categoryGeneratedIndexPermalink: string,
   ): SidebarNavigation {
@@ -257,24 +260,23 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
         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 {
+    if (!sidebarName) {
       return emptySidebarNavigation();
     }
+    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    const currentItemIndex = navigationItems.findIndex(
+      isCurrentCategoryGeneratedIndexItem,
+    );
+    const {previous, next} = getElementsAround(
+      navigationItems,
+      currentItemIndex,
+    );
+    return {sidebarName, previous, next};
   }
 
   function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
     const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
-    const invalidSidebarDocIds = difference(allSidebarDocIds, validDocIds);
+    const invalidSidebarDocIds = _.difference(allSidebarDocIds, validDocIds);
     if (invalidSidebarDocIds.length > 0) {
       throw new Error(
         `Invalid sidebar file at "${toMessageRelativeFilePath(
@@ -284,7 +286,7 @@ These sidebar document ids do not exist:
 - ${invalidSidebarDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${uniq(validDocIds).sort().join('\n- ')}`,
+- ${_.uniq(validDocIds).sort().join('\n- ')}`,
       );
     }
   }
@@ -301,7 +303,6 @@ Available document ids are:
         label: string;
       }
     | undefined {
-    // eslint-disable-next-line no-restricted-syntax
     for (const item of sidebar) {
       if (item.type === 'doc') {
         return {
@@ -322,11 +323,10 @@ Available document ids are:
             slug: item.link.slug,
             label: item.label,
           };
-        } else {
-          const firstSubItem = getFirstLink(item.items);
-          if (firstSubItem) {
-            return firstSubItem;
-          }
+        }
+        const firstSubItem = getFirstLink(item.items);
+        if (firstSubItem) {
+          return firstSubItem;
         }
       }
     }
@@ -371,18 +371,6 @@ export function toNavigationLink(
     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;
   }
@@ -390,8 +378,15 @@ export function toNavigationLink(
   if (navigationItem.type === 'doc') {
     return toDocNavigationLink(getDocById(navigationItem.id));
   } else if (navigationItem.type === 'category') {
-    return handleCategory(navigationItem);
-  } else {
-    throw new Error('unexpected navigation item');
+    if (navigationItem.link.type === 'doc') {
+      return toDocNavigationLink(getDocById(navigationItem.link.id));
+    } else if (navigationItem.link.type === 'generated-index') {
+      return {
+        title: navigationItem.label,
+        permalink: navigationItem.link.permalink,
+      };
+    }
+    throw new Error('unexpected category link type');
   }
+  throw new Error('unexpected navigation item');
 }

package/src/sidebars/validation.ts

@@ -8,22 +8,24 @@
 import {Joi, URISchema} from '@docusaurus/utils-validation';
 import type {
   SidebarItemConfig,
-  SidebarCategoriesShorthand,
   SidebarItemBase,
   SidebarItemAutogenerated,
   SidebarItemDoc,
+  SidebarItemHtml,
   SidebarItemLink,
   SidebarItemCategoryConfig,
   SidebarItemCategoryLink,
-  SidebarsConfig,
   SidebarItemCategoryLinkDoc,
   SidebarItemCategoryLinkGeneratedIndex,
+  NormalizedSidebars,
+  NormalizedSidebarItem,
+  NormalizedSidebarItemCategory,
+  CategoryMetadataFile,
 } from './types';
-import {isCategoriesShorthand} from './utils';
-import type {CategoryMetadataFile} from './generator';
 
 // 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 in normalization
+// Config types are exposed to users for typechecking and we use the same type
+// in normalization
 
 const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
   className: Joi.string(),
@@ -35,7 +37,7 @@ const sidebarItemAutogeneratedSchema =
     type: 'autogenerated',
     dirName: Joi.string()
       .required()
-      .pattern(/^[^/](.*[^/])?$/)
+      .pattern(/^[^/](?:.*[^/])?$/)
       .message(
         '"dirName" must be a dir path relative to the docs folder root, and should not start or end with slash',
       ),
@@ -47,6 +49,12 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
   label: Joi.string(),
 });
 
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean(),
+});
+
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
   type: 'link',
   href: URISchema.required(),
@@ -56,6 +64,7 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
 });
 
 const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
+  .allow(null)
   .when('.type', {
     switch: [
       {
@@ -70,7 +79,8 @@ const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
         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
+          // This one is not in the user config, only in the normalized version
+          // permalink: Joi.string().optional(),
           title: Joi.string().optional(),
           description: Joi.string().optional(),
           image: Joi.string().optional(),
@@ -78,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>({
@@ -93,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',
@@ -106,54 +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: '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);
+  // Because we can't use Joi to validate nested items (see above), we do it
+  // manually
+  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/slug.ts

@@ -48,17 +48,16 @@ export default function getSlug({
   function computeSlug(): string {
     if (frontMatterSlug?.startsWith('/')) {
       return frontMatterSlug;
-    } else {
-      const dirNameSlug = getDirNameSlug();
-      if (
-        !frontMatterSlug &&
-        isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
-      ) {
-        return dirNameSlug;
-      }
-      const baseSlug = frontMatterSlug || baseID;
-      return resolvePathname(baseSlug, getDirNameSlug());
     }
+    const dirNameSlug = getDirNameSlug();
+    if (
+      !frontMatterSlug &&
+      isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
+    ) {
+      return dirNameSlug;
+    }
+    const baseSlug = frontMatterSlug || baseID;
+    return resolvePathname(baseSlug, getDirNameSlug());
   }
 
   function ensureValidSlug(slug: string): string {

package/src/tags.ts

@@ -7,11 +7,11 @@
 
 import {groupTaggedItems} from '@docusaurus/utils';
 import type {VersionTags, DocMetadata} from './types';
-import {mapValues} from 'lodash';
+import _ from 'lodash';
 
 export function getVersionTags(docs: DocMetadata[]): VersionTags {
   const groups = groupTaggedItems(docs, (doc) => doc.tags);
-  return mapValues(groups, (group) => ({
+  return _.mapValues(groups, (group) => ({
     name: group.tag.label,
     docIds: group.items.map((item) => item.id),
     permalink: group.tag.permalink,

package/src/translations.ts

@@ -13,7 +13,7 @@ import type {
   Sidebars,
 } from './sidebars/types';
 
-import {chain, mapValues, keyBy} from 'lodash';
+import _ from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
@@ -31,11 +31,10 @@ import {CURRENT_VERSION_NAME} from './constants';
 function getVersionFileName(versionName: string): string {
   if (versionName === CURRENT_VERSION_NAME) {
     return versionName;
-  } else {
-    // I don't like this "version-" prefix,
-    // but it's for consistency with site/versioned_docs
-    return `version-${versionName}`;
   }
+  // I don't like this "version-" prefix,
+  // but it's for consistency with site/versioned_docs
+  return `version-${versionName}`;
 }
 
 // TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
@@ -68,7 +67,8 @@ function getDocTranslations(doc: DocMetadata): TranslationFileContent {
       ? {
           [`${doc.unversionedId}.sidebar_label`]: {
             message: doc.sidebar_label,
-            description: `The sidebar label for doc with id=${doc.unversionedId}`,
+            description:
+              `The sidebar label for doc with id=${doc.unversionedId}`,
           },
         }
       : undefined),
@@ -146,13 +146,15 @@ function getSidebarTranslationFileContent(
   );
 
   const links = collectSidebarLinks(sidebar);
-  const linksContent: TranslationFileContent = chain(links)
-    .keyBy((link) => `sidebar.${sidebarName}.link.${link.label}`)
-    .mapValues((link) => ({
-      message: link.label,
-      description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
-    }))
-    .value();
+  const linksContent: TranslationFileContent = Object.fromEntries(
+    links.map((link) => [
+      `sidebar.${sidebarName}.link.${link.label}`,
+      {
+        message: link.label,
+        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+      },
+    ]),
+  );
 
   return mergeTranslations([categoryContent, linksContent]);
 }
@@ -230,7 +232,7 @@ function translateSidebars(
   version: LoadedVersion,
   sidebarsTranslations: TranslationFileContent,
 ): Sidebars {
-  return mapValues(version.sidebars, (sidebar, sidebarName) =>
+  return _.mapValues(version.sidebars, (sidebar, sidebarName) =>
     translateSidebar({
       sidebar,
       sidebarName: getNormalizedSidebarName({
@@ -253,7 +255,8 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
   const sidebarsTranslations: TranslationFileContent =
     getSidebarsTranslations(version);
 
-  // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
+  // const docsTranslations: TranslationFileContent =
+  //   getDocsTranslations(version);
 
   return [
     {
@@ -301,7 +304,7 @@ export function translateLoadedContent(
   loadedContent: LoadedContent,
   translationFiles: TranslationFile[],
 ): LoadedContent {
-  const translationFilesMap: Record<string, TranslationFile> = keyBy(
+  const translationFilesMap: Record<string, TranslationFile> = _.keyBy(
     translationFiles,
     (f) => f.path,
   );

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;
@@ -66,6 +58,7 @@ export type DocFrontMatter = {
   sidebar_label?: string;
   sidebar_position?: number;
   sidebar_class_name?: string;
+  sidebar_custom_props?: Record<string, unknown>;
   displayed_sidebar?: string | null;
   pagination_label?: string;
   custom_edit_url?: string | null;