@docusaurus/plugin-content-docs 2.0.0-beta.ff31de0ff → 2.0.1

package/src/sidebars/validation.ts

@@ -0,0 +1,179 @@
+/**
+ * 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,
+  SidebarItemBase,
+  SidebarItemAutogenerated,
+  SidebarItemDoc,
+  SidebarItemHtml,
+  SidebarItemLink,
+  SidebarItemCategoryConfig,
+  SidebarItemCategoryLink,
+  SidebarItemCategoryLinkDoc,
+  SidebarItemCategoryLinkGeneratedIndex,
+  NormalizedSidebars,
+  NormalizedSidebarItem,
+  NormalizedSidebarItemCategory,
+  CategoryMetadataFile,
+} from './types';
+
+// 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
+
+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(),
+  translatable: Joi.boolean(),
+});
+
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean(),
+});
+
+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>()
+  .allow(null)
+  .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(),
+          // 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(),
+          keywords: [Joi.string(), Joi.array().items(Joi.string())],
+        }),
+      },
+      {
+        is: Joi.required(),
+        then: Joi.forbidden().messages({
+          'any.unknown': 'Unknown sidebar category link type "{.type}".',
+        }),
+      },
+    ],
+  });
+
+const sidebarItemCategorySchema =
+  sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
+    type: 'category',
+    label: Joi.string()
+      .required()
+      .messages({'any.unknown': '"label" must be a string'}),
+    items: Joi.array()
+      .required()
+      .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',
+    }),
+    collapsible: Joi.boolean().messages({
+      'any.unknown': '"collapsible" must be a boolean',
+    }),
+  });
+
+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 NormalizedSidebarItem {
+  // TODO: remove once with proper Joi support
+  // Because we can't use Joi to validate nested items (see above), we do it
+  // manually
+  Joi.assert(item, sidebarItemSchema);
+
+  if ((item as NormalizedSidebarItem).type === 'category') {
+    (item as NormalizedSidebarItemCategory).items.forEach(validateSidebarItem);
+  }
+}
+
+export function validateSidebars(sidebars: {
+  [sidebarId: string]: unknown;
+}): asserts sidebars is NormalizedSidebars {
+  Object.values(sidebars as NormalizedSidebars).forEach((sidebar) => {
+    sidebar.forEach(validateSidebarItem);
+  });
+}
+
+const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
+  label: Joi.string(),
+  position: Joi.number(),
+  collapsed: Joi.boolean(),
+  collapsible: Joi.boolean(),
+  className: Joi.string(),
+  link: sidebarItemCategoryLinkSchema,
+  customProps: Joi.object().unknown(),
+});
+
+export function validateCategoryMetadataFile(
+  unsafeContent: unknown,
+): CategoryMetadataFile {
+  const {error, value} = categoryMetadataFileSchema.validate(unsafeContent);
+  if (error) {
+    throw error;
+  }
+  return value;
+}

package/src/slug.ts

@@ -15,50 +15,69 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import {NumberPrefixParser} from './types';
+import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
+import type {
+  NumberPrefixParser,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,
-  frontmatterSlug,
-  dirName,
+  frontMatterSlug,
+  source,
+  sourceDirName,
   stripDirNumberPrefixes = true,
   numberPrefixParser = DefaultNumberPrefixParser,
 }: {
   baseID: string;
-  frontmatterSlug?: string;
-  dirName: string;
+  frontMatterSlug?: string;
+  source: DocMetadataBase['source'];
+  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 folder=${dirName}
-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:
+  function computeSlug(): string {
+    if (frontMatterSlug?.startsWith('/')) {
+      return frontMatterSlug;
+    }
+    const dirNameSlug = getDirNameSlug();
+    if (
+      !frontMatterSlug &&
+      isCategoryIndex(toCategoryIndexMatcherParam({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 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
 ---
 `,
-    );
+      );
+    }
+    return slug;
   }
 
-  return slug;
+  return ensureValidSlug(computeSlug());
 }

package/src/tags.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 _ from 'lodash';
+import {groupTaggedItems} from '@docusaurus/utils';
+import type {VersionTags} from './types';
+import type {DocMetadata} from '@docusaurus/plugin-content-docs';
+
+export function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return _.mapValues(groups, (group) => ({
+    label: group.tag.label,
+    docIds: group.items.map((item) => item.id),
+    permalink: group.tag.permalink,
+  }));
+}

package/src/translations.ts

@@ -5,36 +5,39 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
-  Sidebar,
-  LoadedContent,
-  Sidebars,
-  SidebarItem,
-} from './types';
-
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import _ from 'lodash';
+import {mergeTranslations} from '@docusaurus/utils';
+import {CURRENT_VERSION_NAME} from './constants';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
-import {
+  collectSidebarDocItems,
+  collectSidebarRefs,
+} from './sidebars/utils';
+import type {
+  LoadedVersion,
+  LoadedContent,
+} from '@docusaurus/plugin-content-docs';
+import type {
+  Sidebar,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+  Sidebars,
+} from './sidebars/types';
+import type {
   TranslationFileContent,
   TranslationFile,
-  TranslationFiles,
+  TranslationMessage,
 } from '@docusaurus/types';
-import {mergeTranslations} from '@docusaurus/utils';
-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"
@@ -54,72 +57,78 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadatas?
-// It seems translating frontmatter 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,
 ): 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?.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)
-    .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}`,
+      },
+    ]),
+  );
+
+  const docs = collectSidebarDocItems(sidebar)
+    .concat(collectSidebarRefs(sidebar))
+    .filter((item) => item.translatable);
+  const docLinksContent: TranslationFileContent = Object.fromEntries(
+    docs.map((doc) => [
+      `sidebar.${sidebarName}.doc.${doc.label!}`,
+      {
+        message: doc.label!,
+        description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${
+          doc.id
+        }`,
+      },
+    ]),
+  );
 
-  return mergeTranslations([categoryContent, linksContent]);
+  return mergeTranslations([categoryContent, linksContent, docLinksContent]);
 }
 
 function translateSidebar({
@@ -131,29 +140,59 @@ 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,
+      };
+    }
+    if ((item.type === 'doc' || item.type === 'ref') && item.translatable) {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.doc.${item.label!}`]
+            ?.message ?? item.label,
+      };
+    }
+    return item;
+  });
 }
 
 function getSidebarsTranslations(
@@ -173,79 +212,71 @@ 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 {
+function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
   const versionTranslations: TranslationFileContent = {
     'version.label': {
-      message: version.versionLabel,
+      message: version.label,
       description: `The label for version ${version.versionName}`,
     },
   };
 
-  const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(
-    version,
-  );
-
-  // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
+  const sidebarsTranslations: TranslationFileContent =
+    getSidebarsTranslations(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 {
-  return flatten(versions.map(getVersionTranslationFiles));
+): 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,
   );