@docusaurus/plugin-content-docs 2.0.0-beta.17 → 2.0.0-beta.18

package/src/sidebars/utils.ts

@@ -20,7 +20,7 @@ import type {
 } from './types';
 
 import _ from 'lodash';
-import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
+import {toMessageRelativeFilePath} from '@docusaurus/utils';
 import type {DocMetadataBase, DocNavLink} from '../types';
 
 export function isCategoriesShorthand(
@@ -107,15 +107,15 @@ export function collectSidebarNavigation(
   });
 }
 
-export function collectSidebarsDocIds(
-  sidebars: Sidebars,
-): Record<string, string[]> {
+export function collectSidebarsDocIds(sidebars: Sidebars): {
+  [sidebarId: string]: string[];
+} {
   return _.mapValues(sidebars, collectSidebarDocIds);
 }
 
-export function collectSidebarsNavigations(
-  sidebars: Sidebars,
-): Record<string, SidebarNavigationItem[]> {
+export function collectSidebarsNavigations(sidebars: Sidebars): {
+  [sidebarId: string]: SidebarNavigationItem[];
+} {
   return _.mapValues(sidebars, collectSidebarNavigation);
 }
 
@@ -139,6 +139,11 @@ export type SidebarsUtils = {
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  /**
+   * This function may return undefined. This is usually a user mistake, because
+   * it means this sidebar will never be displayed; however, we can still use
+   * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+   */
   getFirstLink: (sidebarId: string) =>
     | {
         type: 'doc';
@@ -147,7 +152,7 @@ export type SidebarsUtils = {
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined;
@@ -201,12 +206,12 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     if (!sidebarName) {
       return emptySidebarNavigation();
     }
-    if (!sidebarNameToNavigationItems[sidebarName]) {
+    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    if (!navigationItems) {
       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;
@@ -220,11 +225,11 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
       return {sidebarName, next: undefined, previous: undefined};
     }
 
-    const {previous, next} = getElementsAround(
-      navigationItems,
-      currentItemIndex,
-    );
-    return {sidebarName, previous, next};
+    return {
+      sidebarName,
+      previous: navigationItems[currentItemIndex - 1],
+      next: navigationItems[currentItemIndex + 1],
+    };
   }
 
   function getCategoryGeneratedIndexList(): SidebarItemCategoryWithGeneratedIndex[] {
@@ -258,20 +263,16 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     const sidebarName = Object.entries(sidebarNameToNavigationItems).find(
       ([, navigationItems]) =>
         navigationItems.find(isCurrentCategoryGeneratedIndexItem),
-    )?.[0];
-
-    if (!sidebarName) {
-      return emptySidebarNavigation();
-    }
-    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    )![0];
+    const navigationItems = sidebarNameToNavigationItems[sidebarName]!;
     const currentItemIndex = navigationItems.findIndex(
       isCurrentCategoryGeneratedIndexItem,
     );
-    const {previous, next} = getElementsAround(
-      navigationItems,
-      currentItemIndex,
-    );
-    return {sidebarName, previous, next};
+    return {
+      sidebarName,
+      previous: navigationItems[currentItemIndex - 1],
+      next: navigationItems[currentItemIndex + 1],
+    };
   }
 
   function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
@@ -299,7 +300,7 @@ Available document ids are:
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined {
@@ -320,7 +321,7 @@ Available document ids are:
         } else if (item.link?.type === 'generated-index') {
           return {
             type: 'generated-index',
-            slug: item.link.slug,
+            permalink: item.link.permalink,
             label: item.label,
           };
         }
@@ -341,7 +342,7 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
-    getFirstLink: (id) => getFirstLink(sidebars[id]),
+    getFirstLink: (id) => getFirstLink(sidebars[id]!),
   };
 }
 
@@ -359,7 +360,7 @@ export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
 
 export function toNavigationLink(
   navigationItem: SidebarNavigationItem | undefined,
-  docsById: Record<string, DocMetadataBase>,
+  docsById: {[docId: string]: DocMetadataBase},
 ): DocNavLink | undefined {
   function getDocById(docId: string) {
     const doc = docsById[docId];
@@ -375,18 +376,13 @@ export function toNavigationLink(
     return undefined;
   }
 
-  if (navigationItem.type === 'doc') {
-    return toDocNavigationLink(getDocById(navigationItem.id));
-  } else if (navigationItem.type === 'category') {
-    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');
+  if (navigationItem.type === 'category') {
+    return navigationItem.link.type === 'doc'
+      ? toDocNavigationLink(getDocById(navigationItem.link.id))
+      : {
+          title: navigationItem.label,
+          permalink: navigationItem.link.permalink,
+        };
   }
-  throw new Error('unexpected navigation item');
+  return toDocNavigationLink(getDocById(navigationItem.id));
 }

package/src/sidebars/validation.ts

@@ -149,9 +149,9 @@ function validateSidebarItem(
   }
 }
 
-export function validateSidebars(
-  sidebars: Record<string, unknown>,
-): asserts sidebars is NormalizedSidebars {
+export function validateSidebars(sidebars: {
+  [sidebarId: string]: unknown;
+}): asserts sidebars is NormalizedSidebars {
   Object.values(sidebars as NormalizedSidebars).forEach((sidebar) => {
     sidebar.forEach(validateSidebarItem);
   });
@@ -164,6 +164,7 @@ const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
   collapsible: Joi.boolean(),
   className: Joi.string(),
   link: sidebarItemCategoryLinkSchema,
+  customProps: Joi.object().unknown(),
 });
 
 export function validateCategoryMetadataFile(

package/src/slug.ts

@@ -63,12 +63,11 @@ export default function getSlug({
   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.
+        `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 front matter is incorrect or you use weird chars in the file path?
-By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or there are special characters in the file path?
+By using front matter to set a custom slug, you should be able to fix this error:
 
-Example =>
 ---
 slug: /my/customDocPath
 ---

package/src/translations.ts

@@ -118,26 +118,24 @@ function getSidebarTranslationFileContent(
         },
       ]);
 
-      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}`,
-              },
-            ]);
-          }
+      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}`,
+            },
+          ]);
         }
       }
 
@@ -271,13 +269,14 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
 }
 function translateVersion(
   version: LoadedVersion,
-  translationFiles: Record<string, TranslationFile>,
+  translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion {
   const versionTranslations =
-    translationFiles[getVersionFileName(version.versionName)].content;
+    translationFiles[getVersionFileName(version.versionName)]!.content;
   return {
     ...version,
-    versionLabel: versionTranslations['version.label']?.message,
+    versionLabel:
+      versionTranslations['version.label']?.message ?? version.versionLabel,
     sidebars: translateSidebars(version, versionTranslations),
     // docs: translateDocs(version.docs, versionTranslations),
   };
@@ -290,7 +289,7 @@ function getVersionsTranslationFiles(
 }
 function translateVersions(
   versions: LoadedVersion[],
-  translationFiles: Record<string, TranslationFile>,
+  translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion[] {
   return versions.map((version) => translateVersion(version, translationFiles));
 }
@@ -304,7 +303,7 @@ export function translateLoadedContent(
   loadedContent: LoadedContent,
   translationFiles: TranslationFile[],
 ): LoadedContent {
-  const translationFilesMap: Record<string, TranslationFile> = _.keyBy(
+  const translationFilesMap: {[fileName: string]: TranslationFile} = _.keyBy(
     translationFiles,
     (f) => f.path,
   );

package/src/types.ts

@@ -8,11 +8,12 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {Sidebars} from './sidebars/types';
-import type {Tag, FrontMatterTag} from '@docusaurus/utils';
 import type {
-  BrokenMarkdownLink as IBrokenMarkdownLink,
+  Tag,
+  FrontMatterTag,
+  BrokenMarkdownLink,
   ContentPaths,
-} from '@docusaurus/utils/lib/markdownLinks';
+} from '@docusaurus/utils';
 import type {VersionBanner} from '@docusaurus/plugin-content-docs';
 
 export type DocFile = {
@@ -58,7 +59,7 @@ export type DocFrontMatter = {
   sidebar_label?: string;
   sidebar_position?: number;
   sidebar_class_name?: string;
-  sidebar_custom_props?: Record<string, unknown>;
+  sidebar_custom_props?: {[key: string]: unknown};
   displayed_sidebar?: string | null;
   pagination_label?: string;
   custom_edit_url?: string | null;
@@ -82,7 +83,7 @@ export type DocMetadataBase = LastUpdateData & {
   sidebarPosition?: number;
   editUrl?: string | null;
   tags: Tag[];
-  frontMatter: DocFrontMatter & Record<string, unknown>;
+  frontMatter: DocFrontMatter & {[key: string]: unknown};
 };
 
 export type DocNavLink = {
@@ -133,11 +134,11 @@ export type LoadedContent = {
   loadedVersions: LoadedVersion[];
 };
 
-export type BrokenMarkdownLink = IBrokenMarkdownLink<VersionMetadata>;
+export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
 
 export type DocsMarkdownOption = {
   versionsMetadata: VersionMetadata[];
   siteDir: string;
   sourceToPermalink: SourceToPermalink;
-  onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
+  onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
 };

package/src/versions.ts

@@ -74,9 +74,9 @@ function ensureValidVersionString(version: unknown): asserts version is string {
 function ensureValidVersionArray(
   versionArray: unknown,
 ): asserts versionArray is string[] {
-  if (!(versionArray instanceof Array)) {
+  if (!Array.isArray(versionArray)) {
     throw new Error(
-      `The versions file should contain an array of versions! Found content: ${JSON.stringify(
+      `The versions file should contain an array of version names! Found content: ${JSON.stringify(
         versionArray,
       )}`,
     );
@@ -464,11 +464,11 @@ Please set the docs "sidebarPath" field in your config file to:
 // "last version" is not a very good concept nor api surface
 function getDefaultLastVersionName(versionNames: string[]) {
   if (versionNames.length === 1) {
-    return versionNames[0];
+    return versionNames[0]!;
   }
   return versionNames.filter(
     (versionName) => versionName !== CURRENT_VERSION_NAME,
-  )[0];
+  )[0]!;
 }
 
 function checkVersionsOptions(
@@ -537,7 +537,7 @@ export function filterVersions(
 ): string[] {
   if (options.onlyIncludeVersions) {
     return versionNamesUnfiltered.filter((name) =>
-      (options.onlyIncludeVersions || []).includes(name),
+      options.onlyIncludeVersions!.includes(name),
     );
   }
   return versionNamesUnfiltered;