@docusaurus/plugin-content-docs 3.8.1 → 3.9.0-canary-6403

package/src/index.ts

@@ -7,7 +7,6 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import logger from '@docusaurus/logger';
 import {
   normalizeUrl,
   docuHash,
@@ -63,6 +62,12 @@ async function createMdxLoaderDependencyFile({
   options: PluginOptions;
   versionsMetadata: VersionMetadata[];
 }): Promise<string | undefined> {
+  // Disabled for unit tests, the side effect produces infinite watch loops
+  // TODO find a better way :/
+  if (process.env.NODE_ENV === 'test') {
+    return undefined;
+  }
+
   const filePath = path.join(dataDir, '__mdx-loader-dependency.json');
   // the cache is invalidated whenever this file content changes
   const fileContent = {
@@ -158,18 +163,12 @@ export default async function pluginContentDocs(
             sourceFilePath,
             versionsMetadata,
           );
-          const permalink = resolveMarkdownLinkPathname(linkPathname, {
+          return resolveMarkdownLinkPathname(linkPathname, {
             sourceFilePath,
             sourceToPermalink: contentHelpers.sourceToPermalink,
             siteDir,
             contentPaths: version,
           });
-          if (permalink === null) {
-            logger.report(
-              siteConfig.onBrokenMarkdownLinks,
-            )`Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
-          }
-          return permalink;
         },
       },
     });

package/src/props.ts

@@ -38,28 +38,23 @@ export function toSidebarDocItemLinkProp({
     'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'
   >;
 }): PropSidebarItemLink {
-  const {
-    id,
-    title,
-    permalink,
-    frontMatter: {
-      sidebar_label: sidebarLabel,
-      sidebar_custom_props: customProps,
-    },
-    unlisted,
-  } = doc;
+  const {id, title, permalink, frontMatter, unlisted} = doc;
   return {
     type: 'link',
-    label: sidebarLabel ?? item.label ?? title,
+    ...(item.key && {key: item.key}),
     href: permalink,
-    className: item.className,
-    customProps: item.customProps ?? customProps,
+    // Front Matter data takes precedence over sidebars.json
+    label: frontMatter.sidebar_label ?? item.label ?? title,
+    className: frontMatter.sidebar_class_name ?? item.className,
+    customProps: frontMatter.sidebar_custom_props ?? item.customProps,
     docId: id,
     unlisted,
   };
 }
 
-export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
+export function toSidebarsProp(
+  loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>,
+): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
 
   function getDocById(docId: string): DocMetadata {

package/src/sidebars/generator.ts

@@ -252,6 +252,7 @@ Available doc IDs:
         ...(categoryMetadata?.description && {
           description: categoryMetadata?.description,
         }),
+        ...(categoryMetadata?.key && {key: categoryMetadata?.key}),
         ...(link && {link}),
       };
     }

package/src/sidebars/postProcessor.ts

@@ -77,10 +77,13 @@ function postProcessSidebarItem(
       ) {
         return null;
       }
+      const {label, className, customProps} = category;
       return {
         type: 'doc',
-        label: category.label,
         id: category.link.id,
+        label,
+        ...(className && {className}),
+        ...(customProps && {customProps}),
       };
     }
     // A non-collapsible category can't be collapsed!

package/src/sidebars/types.ts

@@ -19,6 +19,7 @@ import type {Slugger} from '@docusaurus/utils';
 type Expand<T extends {[x: string]: unknown}> = {[P in keyof T]: T[P]};
 
 export type SidebarItemBase = {
+  key?: string;
   className?: string;
   customProps?: {[key: string]: unknown};
 };
@@ -28,8 +29,9 @@ export type SidebarItemDoc = SidebarItemBase & {
   label?: string;
   id: string;
   /**
-   * This is an internal marker. Items with labels defined in the config needs
-   * to be translated with JSON
+   * This is an internal marker set during the sidebar normalization process.
+   * Docs with labels defined in the config need to be translated with JSON.
+   * Otherwise, it's preferable to translate the MDX doc title or front matter.
    */
   translatable?: true;
 };
@@ -215,6 +217,7 @@ export type PropSidebarBreadcrumbsItem =
   | PropSidebarItemCategory;
 
 export type CategoryMetadataFile = {
+  key?: string;
   label?: string;
   position?: number;
   description?: string;

package/src/sidebars/validation.ts

@@ -28,6 +28,7 @@ import type {
 // in normalization
 
 const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
+  key: Joi.string(),
   className: Joi.string(),
   customProps: Joi.object().unknown(),
 });
@@ -166,6 +167,7 @@ export function validateSidebars(sidebars: {
 }
 
 const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
+  key: Joi.string(),
   label: Joi.string(),
   description: Joi.string(),
   position: Joi.number(),

package/src/translations.ts

@@ -7,6 +7,7 @@
 
 import _ from 'lodash';
 import {mergeTranslations} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 import {CURRENT_VERSION_NAME} from './constants';
 import {
   collectSidebarCategories,
@@ -40,20 +41,53 @@ function getVersionFileName(versionName: string): string {
   return `version-${versionName}`;
 }
 
+type TranslationMessageEntry = [string, TranslationMessage];
+
+function ensureNoSidebarDuplicateEntries(
+  translationEntries: TranslationMessageEntry[],
+): void {
+  const grouped = _.groupBy(translationEntries, (entry) => entry[0]);
+  const duplicates = Object.entries(grouped).filter(
+    (entry) => entry[1].length > 1,
+  );
+
+  if (duplicates.length > 0) {
+    throw new Error(`Multiple docs sidebar items produce the same translation key.
+- ${duplicates
+      .map(([translationKey, entries]) => {
+        return `${logger.code(translationKey)}: ${logger.num(
+          entries.length,
+        )} duplicates found:\n  - ${entries
+          .map((duplicate) => {
+            const desc = duplicate[1].description;
+            return `${logger.name(duplicate[1].message)} ${
+              desc ? `(${logger.subdue(desc)})` : ''
+            }`;
+          })
+          .join('\n  - ')}`;
+      })
+      .join('\n\n- ')}
+
+To avoid translation key conflicts, use the ${logger.code(
+      'key',
+    )} attribute on the sidebar items above to uniquely identify them.
+    `);
+  }
+}
+
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
 ): TranslationFileContent {
-  type TranslationMessageEntry = [string, TranslationMessage];
-
   const categories = collectSidebarCategories(sidebar);
 
-  const categoryContent: TranslationFileContent = Object.fromEntries(
-    categories.flatMap((category) => {
+  const categoryEntries: TranslationMessageEntry[] = categories.flatMap(
+    (category) => {
       const entries: TranslationMessageEntry[] = [];
+      const categoryKey = category.key ?? category.label;
 
       entries.push([
-        `sidebar.${sidebarName}.category.${category.label}`,
+        `sidebar.${sidebarName}.category.${categoryKey}`,
         {
           message: category.label,
           description: `The label for category ${category.label} in sidebar ${sidebarName}`,
@@ -63,7 +97,7 @@ function getSidebarTranslationFileContent(
       if (category.link?.type === 'generated-index') {
         if (category.link.title) {
           entries.push([
-            `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`,
+            `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`,
             {
               message: category.link.title,
               description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
@@ -72,7 +106,7 @@ function getSidebarTranslationFileContent(
         }
         if (category.link.description) {
           entries.push([
-            `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`,
+            `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`,
             {
               message: category.link.description,
               description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
@@ -82,36 +116,40 @@ function getSidebarTranslationFileContent(
       }
 
       return entries;
-    }),
+    },
   );
 
   const links = collectSidebarLinks(sidebar);
-  const linksContent: TranslationFileContent = Object.fromEntries(
-    links.map((link) => [
-      `sidebar.${sidebarName}.link.${link.label}`,
+  const linksEntries: TranslationMessageEntry[] = links.map((link) => {
+    const linkKey = link.key ?? link.label;
+    return [
+      `sidebar.${sidebarName}.link.${linkKey}`,
       {
         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!}`,
+  const docLinksEntries: TranslationMessageEntry[] = docs.map((doc) => {
+    const docKey = doc.key ?? doc.label!;
+    return [
+      `sidebar.${sidebarName}.doc.${docKey}`,
       {
         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, docLinksContent]);
+  const allEntries = [...categoryEntries, ...linksEntries, ...docLinksEntries];
+  ensureNoSidebarDuplicateEntries(allEntries);
+  return Object.fromEntries(allEntries);
 }
 
 function translateSidebar({
@@ -150,27 +188,30 @@ function translateSidebar({
   return transformSidebarItems(sidebar, (item) => {
     if (item.type === 'category') {
       const link = transformSidebarCategoryLink(item);
+      const categoryKey = item.key ?? item.label;
       return {
         ...item,
         label:
-          sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]
+          sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}`]
             ?.message ?? item.label,
         ...(link && {link}),
       };
     }
     if (item.type === 'link') {
+      const linkKey = item.key ?? item.label;
       return {
         ...item,
         label:
-          sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
+          sidebarsTranslations[`sidebar.${sidebarName}.link.${linkKey}`]
             ?.message ?? item.label,
       };
     }
     if ((item.type === 'doc' || item.type === 'ref') && item.translatable) {
+      const docKey = item.key ?? item.label!;
       return {
         ...item,
         label:
-          sidebarsTranslations[`sidebar.${sidebarName}.doc.${item.label!}`]
+          sidebarsTranslations[`sidebar.${sidebarName}.doc.${docKey}`]
             ?.message ?? item.label,
       };
     }

package/src/versions/files.ts

@@ -7,7 +7,11 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import {getPluginI18nPath, DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import {
+  getPluginI18nPath,
+  getLocaleConfig,
+  DEFAULT_PLUGIN_ID,
+} from '@docusaurus/utils';
 import {
   VERSIONS_JSON_FILE,
   VERSIONED_DOCS_DIR,
@@ -186,11 +190,16 @@ export async function getVersionMetadataPaths({
   >
 > {
   const isCurrent = versionName === CURRENT_VERSION_NAME;
-  const contentPathLocalized = getDocsDirPathLocalized({
-    localizationDir: context.localizationDir,
-    pluginId: options.id,
-    versionName,
-  });
+
+  const shouldTranslate = getLocaleConfig(context.i18n).translate;
+  const contentPathLocalized = shouldTranslate
+    ? getDocsDirPathLocalized({
+        localizationDir: context.localizationDir,
+        pluginId: options.id,
+        versionName,
+      })
+    : undefined;
+
   const contentPath = isCurrent
     ? path.resolve(context.siteDir, options.path)
     : getVersionDocsDirPath(context.siteDir, options.id, versionName);

package/src/versions/loadVersion.ts

@@ -7,7 +7,7 @@
 
 import path from 'path';
 import _ from 'lodash';
-import {createSlugger} from '@docusaurus/utils';
+import {aliasedSitePathToRelativePath, createSlugger} from '@docusaurus/utils';
 import {getTagsFile} from '@docusaurus/utils-validation';
 import logger from '@docusaurus/logger';
 import {
@@ -29,102 +29,157 @@ import type {
 import type {DocFile} from '../types';
 import type {LoadContext} from '@docusaurus/types';
 
-export async function loadVersion({
-  context,
-  options,
-  versionMetadata,
-  env,
-}: {
+type LoadVersionParams = {
   context: LoadContext;
   options: PluginOptions;
   versionMetadata: VersionMetadata;
   env: DocEnv;
-}): Promise<LoadedVersion> {
-  const {siteDir} = context;
-
-  async function loadVersionDocsBase(
-    tagsFile: TagsFile | null,
-  ): Promise<DocMetadataBase[]> {
-    const docFiles = await readVersionDocs(versionMetadata, options);
-    if (docFiles.length === 0) {
-      throw new Error(
-        `Docs version "${
-          versionMetadata.versionName
-        }" has no docs! At least one doc should exist at "${path.relative(
-          siteDir,
-          versionMetadata.contentPath,
-        )}".`,
-      );
-    }
-    function processVersionDoc(docFile: DocFile) {
-      return processDocMetadata({
-        docFile,
-        versionMetadata,
-        context,
-        options,
-        env,
-        tagsFile,
-      });
-    }
-    return Promise.all(docFiles.map(processVersionDoc));
+};
+
+function ensureNoDuplicateDocId(docs: DocMetadataBase[]): void {
+  const duplicatesById = _.chain(docs)
+    .sort((d1, d2) => {
+      // Need to sort because Globby order is non-deterministic
+      // TODO maybe we should create a deterministic glob utils?
+      //  see https://github.com/sindresorhus/globby/issues/131
+      return d1.source.localeCompare(d2.source);
+    })
+    .groupBy((d) => d.id)
+    .pickBy((group) => group.length > 1)
+    .value();
+
+  const duplicateIdEntries = Object.entries(duplicatesById);
+
+  if (duplicateIdEntries.length) {
+    const idMessages = duplicateIdEntries
+      .map(([id, duplicateDocs]) => {
+        return logger.interpolate`- code=${id} found in number=${
+          duplicateDocs.length
+        } docs:
+  - ${duplicateDocs
+    .map((d) => aliasedSitePathToRelativePath(d.source))
+    .join('\n  - ')}`;
+      })
+      .join('\n\n');
+
+    const message = `The docs plugin found docs sharing the same id:
+\n${idMessages}\n
+Docs should have distinct ids.
+In case of conflict, you can rename the docs file, or use the ${logger.code(
+      'id',
+    )} front matter to assign an explicit distinct id to each doc.
+    `;
+
+    throw new Error(message);
   }
+}
 
-  async function doLoadVersion(): Promise<LoadedVersion> {
-    const tagsFile = await getTagsFile({
-      contentPaths: versionMetadata,
-      tags: options.tags,
+async function loadVersionDocsBase({
+  tagsFile,
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams & {
+  tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase[]> {
+  const docFiles = await readVersionDocs(versionMetadata, options);
+  if (docFiles.length === 0) {
+    throw new Error(
+      `Docs version "${
+        versionMetadata.versionName
+      }" has no docs! At least one doc should exist at "${path.relative(
+        context.siteDir,
+        versionMetadata.contentPath,
+      )}".`,
+    );
+  }
+  function processVersionDoc(docFile: DocFile) {
+    return processDocMetadata({
+      docFile,
+      versionMetadata,
+      context,
+      options,
+      env,
+      tagsFile,
     });
+  }
+  const docs = await Promise.all(docFiles.map(processVersionDoc));
+  ensureNoDuplicateDocId(docs);
+  return docs;
+}
 
-    const docsBase: DocMetadataBase[] = await loadVersionDocsBase(tagsFile);
+async function doLoadVersion({
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams): Promise<LoadedVersion> {
+  const tagsFile = await getTagsFile({
+    contentPaths: versionMetadata,
+    tags: options.tags,
+  });
 
-    // TODO we only ever need draftIds in further code, not full draft items
-    // To simplify and prevent mistakes, avoid exposing draft
-    // replace draft=>draftIds in content loaded
-    const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
+  const docsBase: DocMetadataBase[] = await loadVersionDocsBase({
+    tagsFile,
+    context,
+    options,
+    versionMetadata,
+    env,
+  });
 
-    const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
-      sidebarItemsGenerator: options.sidebarItemsGenerator,
-      numberPrefixParser: options.numberPrefixParser,
-      docs,
-      drafts,
-      version: versionMetadata,
-      sidebarOptions: {
-        sidebarCollapsed: options.sidebarCollapsed,
-        sidebarCollapsible: options.sidebarCollapsible,
-      },
-      categoryLabelSlugger: createSlugger(),
-    });
+  // TODO we only ever need draftIds in further code, not full draft items
+  // To simplify and prevent mistakes, avoid exposing draft
+  // replace draft=>draftIds in content loaded
+  const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
 
-    const sidebarsUtils = createSidebarsUtils(sidebars);
+  const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
+    sidebarItemsGenerator: options.sidebarItemsGenerator,
+    numberPrefixParser: options.numberPrefixParser,
+    docs,
+    drafts,
+    version: versionMetadata,
+    sidebarOptions: {
+      sidebarCollapsed: options.sidebarCollapsed,
+      sidebarCollapsible: options.sidebarCollapsible,
+    },
+    categoryLabelSlugger: createSlugger(),
+  });
 
-    const docsById = createDocsByIdIndex(docs);
-    const allDocIds = Object.keys(docsById);
+  const sidebarsUtils = createSidebarsUtils(sidebars);
 
-    sidebarsUtils.checkLegacyVersionedSidebarNames({
-      sidebarFilePath: versionMetadata.sidebarFilePath as string,
-      versionMetadata,
-    });
-    sidebarsUtils.checkSidebarsDocIds({
-      allDocIds,
-      sidebarFilePath: versionMetadata.sidebarFilePath as string,
-      versionMetadata,
-    });
+  const docsById = createDocsByIdIndex(docs);
+  const allDocIds = Object.keys(docsById);
 
-    return {
-      ...versionMetadata,
-      docs: addDocNavigation({
-        docs,
-        sidebarsUtils,
-      }),
-      drafts,
-      sidebars,
-    };
-  }
+  sidebarsUtils.checkLegacyVersionedSidebarNames({
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+  sidebarsUtils.checkSidebarsDocIds({
+    allDocIds,
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+
+  return {
+    ...versionMetadata,
+    docs: addDocNavigation({
+      docs,
+      sidebarsUtils,
+    }),
+    drafts,
+    sidebars,
+  };
+}
 
+export async function loadVersion(
+  params: LoadVersionParams,
+): Promise<LoadedVersion> {
   try {
-    return await doLoadVersion();
+    return await doLoadVersion(params);
   } catch (err) {
-    logger.error`Loading of version failed for version name=${versionMetadata.versionName}`;
+    // TODO use error cause (but need to refactor many tests)
+    logger.error`Loading of version failed for version name=${params.versionMetadata.versionName}`;
     throw err;
   }
 }

package/src/versions/version.ts

@@ -50,33 +50,47 @@ function getVersionEditUrls({
     return {editUrl: undefined, editUrlLocalized: undefined};
   }
 
-  const editDirPath = options.editCurrentVersion ? options.path : contentPath;
-  const editDirPathLocalized = options.editCurrentVersion
-    ? getDocsDirPathLocalized({
-        localizationDir: context.localizationDir,
-        versionName: CURRENT_VERSION_NAME,
-        pluginId: options.id,
-      })
-    : contentPathLocalized;
+  // Intermediate var just to please TS not narrowing to "string"
+  const editUrlOption = options.editUrl;
 
-  const versionPathSegment = posixPath(
-    path.relative(context.siteDir, path.resolve(context.siteDir, editDirPath)),
-  );
-  const versionPathSegmentLocalized = posixPath(
-    path.relative(
-      context.siteDir,
-      path.resolve(context.siteDir, editDirPathLocalized),
-    ),
-  );
+  const getEditUrl = () => {
+    const editDirPath = options.editCurrentVersion ? options.path : contentPath;
+
+    return normalizeUrl([
+      editUrlOption,
+      posixPath(
+        path.relative(
+          context.siteDir,
+          path.resolve(context.siteDir, editDirPath),
+        ),
+      ),
+    ]);
+  };
 
-  const editUrl = normalizeUrl([options.editUrl, versionPathSegment]);
+  const getEditUrlLocalized = () => {
+    if (!contentPathLocalized) {
+      return undefined;
+    }
+    const editDirPathLocalized = options.editCurrentVersion
+      ? getDocsDirPathLocalized({
+          localizationDir: context.localizationDir,
+          versionName: CURRENT_VERSION_NAME,
+          pluginId: options.id,
+        })
+      : contentPathLocalized;
 
-  const editUrlLocalized = normalizeUrl([
-    options.editUrl,
-    versionPathSegmentLocalized,
-  ]);
+    return normalizeUrl([
+      editUrlOption,
+      posixPath(
+        path.relative(
+          context.siteDir,
+          path.resolve(context.siteDir, editDirPathLocalized),
+        ),
+      ),
+    ]);
+  };
 
-  return {editUrl, editUrlLocalized};
+  return {editUrl: getEditUrl(), editUrlLocalized: getEditUrlLocalized()};
 }
 
 /**