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

package/src/sidebars/types.ts

@@ -6,20 +6,21 @@
  */
 
 import type {Optional, Required} from 'utility-types';
-import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
   NumberPrefixParser,
   SidebarOptions,
   CategoryIndexMatcher,
+  DocMetadataBase,
+  VersionMetadata,
 } 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]};
+type Expand<T extends {[x: string]: unknown}> = {[P in keyof T]: T[P]};
 
 export type SidebarItemBase = {
   className?: string;
-  customProps?: Record<string, unknown>;
+  customProps?: {[key: string]: unknown};
 };
 
 export type SidebarItemDoc = SidebarItemBase & {
@@ -179,7 +180,6 @@ export type PropSidebarItemCategory = Expand<
   }
 >;
 
-// we may want to use a union type in props instead of this generic link?
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
@@ -199,16 +199,6 @@ export type PropSidebarBreadcrumbsItem =
   | PropSidebarItemLink
   | PropSidebarItemCategory;
 
-export type PropVersionDoc = {
-  id: string;
-  title: string;
-  description?: string;
-  sidebar?: string;
-};
-export type PropVersionDocs = {
-  [docId: string]: PropVersionDoc;
-};
-
 export type CategoryMetadataFile = {
   label?: string;
   position?: number;
@@ -216,6 +206,7 @@ export type CategoryMetadataFile = {
   collapsible?: boolean;
   className?: string;
   link?: SidebarItemCategoryLinkConfig | null;
+  customProps?: {[key: string]: unknown};
 
   // TODO should we allow "items" here? how would this work? would an
   // "autogenerated" type be allowed?
@@ -230,6 +221,7 @@ export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   | 'id'
   | 'unversionedId'
+  | 'title'
   | 'frontMatter'
   | 'source'
   | 'sourceDirName'
@@ -241,32 +233,42 @@ export type SidebarItemsGeneratorVersion = Pick<
 >;
 
 export type SidebarItemsGeneratorArgs = {
+  /** The sidebar item with type "autogenerated" to be transformed. */
   item: SidebarItemAutogenerated;
+  /** Useful metadata for the version this sidebar belongs to. */
   version: SidebarItemsGeneratorVersion;
+  /** All the docs of that version (unfiltered). */
   docs: SidebarItemsGeneratorDoc[];
+  /** Number prefix parser configured for this plugin. */
   numberPrefixParser: NumberPrefixParser;
+  /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
-  categoriesMetadata: Record<string, CategoryMetadataFile>;
-  options: SidebarOptions;
+  /**
+   * Key is the path relative to the doc content directory, value is the
+   * category metadata file's content.
+   */
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,
 ) => Promise<NormalizedSidebar>;
 
-// 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
-export type SidebarItemsGeneratorOptionArgs = {
-  defaultSidebarItemsGenerator: SidebarItemsGenerator;
-} & SidebarItemsGeneratorArgs;
 export type SidebarItemsGeneratorOption = (
-  generatorArgs: SidebarItemsGeneratorOptionArgs,
+  generatorArgs: {
+    /**
+     * Useful to re-use/enhance the default sidebar generation logic from
+     * Docusaurus.
+     * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
+     */
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+  } & SidebarItemsGeneratorArgs,
 ) => Promise<NormalizedSidebarItem[]>;
 
 export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;
   numberPrefixParser: NumberPrefixParser;
   docs: DocMetadataBase[];
+  drafts: DocMetadataBase[];
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
   sidebarOptions: SidebarOptions;

package/src/sidebars/utils.ts

@@ -20,8 +20,11 @@ import type {
 } from './types';
 
 import _ from 'lodash';
-import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
-import type {DocMetadataBase, DocNavLink} from '../types';
+import {toMessageRelativeFilePath} from '@docusaurus/utils';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
@@ -107,15 +110,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 +142,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 +155,7 @@ export type SidebarsUtils = {
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined;
@@ -201,12 +209,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 +228,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 +266,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 +303,7 @@ Available document ids are:
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined {
@@ -320,7 +324,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,11 +345,11 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
-    getFirstLink: (id) => getFirstLink(sidebars[id]),
+    getFirstLink: (id) => getFirstLink(sidebars[id]!),
   };
 }
 
-export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
+export function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink {
   const {
     title,
     permalink,
@@ -359,8 +363,8 @@ export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
 
 export function toNavigationLink(
   navigationItem: SidebarNavigationItem | undefined,
-  docsById: Record<string, DocMetadataBase>,
-): DocNavLink | undefined {
+  docsById: {[docId: string]: DocMetadataBase},
+): PropNavigationLink | undefined {
   function getDocById(docId: string) {
     const doc = docsById[docId];
     if (!doc) {
@@ -375,18 +379,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

@@ -15,9 +15,11 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import type {DocMetadataBase} from './types';
 import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
-import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
+import type {
+  NumberPrefixParser,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,
@@ -63,12 +65,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/tags.ts

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

package/src/translations.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {LoadedVersion, LoadedContent} from './types';
+import type {
+  LoadedVersion,
+  LoadedContent,
+} from '@docusaurus/plugin-content-docs';
 import type {
   Sidebar,
   SidebarItemCategory,
@@ -22,7 +25,6 @@ import {
 import type {
   TranslationFileContent,
   TranslationFile,
-  TranslationFiles,
   TranslationMessage,
 } from '@docusaurus/types';
 import {mergeTranslations} from '@docusaurus/utils';
@@ -54,50 +56,6 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadata?
-// It seems translating front matter labels is good enough
-function getDocTranslations(doc: DocMetadata): TranslationFileContent {
-  return {
-    [`${doc.unversionedId}.title`]: {
-      message: doc.title,
-      description: `The title for doc with id=${doc.unversionedId}`,
-    },
-    ...(doc.sidebar_label
-      ? {
-          [`${doc.unversionedId}.sidebar_label`]: {
-            message: doc.sidebar_label,
-            description:
-              `The sidebar label for doc with id=${doc.unversionedId}`,
-          },
-        }
-      : undefined),
-  };
-}
-function translateDoc(
-  doc: DocMetadata,
-  docsTranslations: TranslationFileContent,
-): DocMetadata {
-  return {
-    ...doc,
-    title: docsTranslations[`${doc.unversionedId}.title`]?.message ?? doc.title,
-    sidebar_label:
-      docsTranslations[`${doc.unversionedId}.sidebar_label`]?.message ??
-      doc.sidebar_label,
-  };
-}
-
-function getDocsTranslations(version: LoadedVersion): TranslationFileContent {
-  return mergeTranslations(version.docs.map(getDocTranslations));
-}
-function translateDocs(
-  docs: DocMetadata[],
-  docsTranslations: TranslationFileContent,
-): DocMetadata[] {
-  return docs.map((doc) => translateDoc(doc, docsTranslations));
-}
- */
-
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
@@ -118,26 +76,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}`,
+            },
+          ]);
         }
       }
 
@@ -244,10 +200,10 @@ function translateSidebars(
   );
 }
 
-function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
+function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
   const versionTranslations: TranslationFileContent = {
     'version.label': {
-      message: version.versionLabel,
+      message: version.label,
       description: `The label for version ${version.versionName}`,
     },
   };
@@ -255,56 +211,48 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
   const sidebarsTranslations: TranslationFileContent =
     getSidebarsTranslations(version);
 
-  // const docsTranslations: TranslationFileContent =
-  //   getDocsTranslations(version);
-
   return [
     {
       path: getVersionFileName(version.versionName),
-      content: mergeTranslations([
-        versionTranslations,
-        sidebarsTranslations,
-        // docsTranslations,
-      ]),
+      content: mergeTranslations([versionTranslations, sidebarsTranslations]),
     },
   ];
 }
 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,
+    label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
-    // docs: translateDocs(version.docs, versionTranslations),
   };
 }
 
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
-): TranslationFiles {
+): TranslationFile[] {
   return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],
-  translationFiles: Record<string, TranslationFile>,
+  translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion[] {
   return versions.map((version) => translateVersion(version, translationFiles));
 }
 
 export function getLoadedContentTranslationFiles(
   loadedContent: LoadedContent,
-): TranslationFiles {
+): TranslationFile[] {
   return getVersionsTranslationFiles(loadedContent.loadedVersions);
 }
 export function translateLoadedContent(
   loadedContent: LoadedContent,
   translationFiles: TranslationFile[],
 ): LoadedContent {
-  const translationFilesMap: Record<string, TranslationFile> = _.keyBy(
+  const translationFilesMap: {[fileName: string]: TranslationFile} = _.keyBy(
     translationFiles,
     (f) => f.path,
   );