@docusaurus/plugin-content-docs 2.0.0-beta.0e652730d → 2.0.0-beta.10

package/src/sidebars/validation.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {Joi, URISchema} from '@docusaurus/utils-validation';
+import type {
+  SidebarItemConfig,
+  SidebarCategoriesShorthand,
+  SidebarItemBase,
+  SidebarItemAutogenerated,
+  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(),
+  customProps: Joi.object().unknown(),
+});
+
+const sidebarItemAutogeneratedSchema =
+  sidebarItemBaseSchema.append<SidebarItemAutogenerated>({
+    type: 'autogenerated',
+    dirName: Joi.string()
+      .required()
+      .pattern(/^[^/](.*[^/])?$/)
+      .message(
+        '"dirName" must be a dir path relative to the docs folder root, and should not start or end with slash',
+      ),
+  });
+
+const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
+  type: Joi.string().valid('doc', 'ref').required(),
+  id: Joi.string().required(),
+  label: Joi.string(),
+});
+
+const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
+  type: 'link',
+  href: URISchema.required(),
+  label: Joi.string()
+    .required()
+    .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',
+    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')),
+    link: sidebarItemCategoryLinkSchema,
+    collapsed: Joi.boolean().messages({
+      'any.unknown': '"collapsed" must be a boolean',
+    }),
+    collapsible: Joi.boolean().messages({
+      'any.unknown': '"collapsible" must be a boolean',
+    }),
+  });
+
+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');
+
+function validateSidebarItem(item: unknown): asserts item is SidebarItemConfig {
+  if (typeof item === 'string') {
+    return;
+  }
+  // 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);
+
+    if ((item as SidebarItemCategoryConfig).type === 'category') {
+      (item as SidebarItemCategoryConfig).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);
+    }
+  });
+}
+
+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 {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/tags.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {groupTaggedItems} from '@docusaurus/utils';
+import type {VersionTags, DocMetadata} from './types';
+import {mapValues} from 'lodash';
+
+export function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return mapValues(groups, (group) => ({
+    name: group.tag.label,
+    docIds: group.items.map((item) => item.id),
+    permalink: group.tag.permalink,
+  }));
+}

package/src/theme/hooks/useDocs.ts

@@ -24,11 +24,15 @@ import {
   GetActivePluginOptions,
 } from '../../client/docsClientUtils';
 
+// Important to use a constant object to avoid React useEffect executions etc...,
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+
 // Not using useAllPluginInstancesData() because in blog-only mode, docs hooks are still used by the theme
 // We need a fail-safe fallback when the docs plugin is not in use
 export const useAllDocsData = (): Record<string, GlobalPluginData> =>
   // useAllPluginInstancesData('docusaurus-plugin-content-docs');
-  useGlobalData()['docusaurus-plugin-content-docs'] ?? {};
+  useGlobalData()['docusaurus-plugin-content-docs'] ?? StableEmptyObject;
 
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;

package/src/translations.ts

@@ -5,27 +5,28 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
+import type {LoadedVersion, LoadedContent} from './types';
+import type {
   Sidebar,
-  LoadedContent,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
   Sidebars,
-  SidebarItem,
-} from './types';
+} from './sidebars/types';
 
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import {chain, mapValues, keyBy} from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
-import {
+} from './sidebars/utils';
+import type {
   TranslationFileContent,
   TranslationFile,
   TranslationFiles,
 } 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) {
@@ -55,7 +56,7 @@ function getNormalizedSidebarName({
 }
 
 /*
-// Do we need to translate doc metadatas?
+// Do we need to translate doc metadata?
 // It seems translating frontmatter labels is good enough
 function getDocTranslations(doc: DocMetadata): TranslationFileContent {
   return {
@@ -101,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)
@@ -131,29 +166,51 @@ function translateSidebar({
   sidebarName: string;
   sidebarsTranslations: TranslationFileContent;
 }): Sidebar {
-  return transformSidebarItems(
-    sidebar,
-    (item: SidebarItem): SidebarItem => {
-      if (item.type === 'category') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[
-              `sidebar.${sidebarName}.category.${item.label}`
-            ]?.message ?? item.label,
-        };
-      }
-      if (item.type === 'link') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
-              ?.message ?? item.label,
-        };
-      }
-      return item;
-    },
-  );
+  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') {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
+            ?.message ?? item.label,
+      };
+    }
+    return item;
+  });
 }
 
 function getSidebarsTranslations(
@@ -173,16 +230,16 @@ function translateSidebars(
   version: LoadedVersion,
   sidebarsTranslations: TranslationFileContent,
 ): Sidebars {
-  return mapValues(version.sidebars, (sidebar, sidebarName) => {
-    return translateSidebar({
+  return mapValues(version.sidebars, (sidebar, sidebarName) =>
+    translateSidebar({
       sidebar,
       sidebarName: getNormalizedSidebarName({
         sidebarName,
         versionName: version.versionName,
       }),
       sidebarsTranslations,
-    });
-  });
+    }),
+  );
 }
 
 function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
@@ -193,9 +250,8 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
     },
   };
 
-  const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(
-    version,
-  );
+  const sidebarsTranslations: TranslationFileContent =
+    getSidebarsTranslations(version);
 
   // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
 
@@ -227,7 +283,7 @@ function translateVersion(
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
 ): TranslationFiles {
-  return flatten(versions.map(getVersionTranslationFiles));
+  return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],