@docusaurus/plugin-content-docs 3.8.1-canary-6358 → 3.8.1-canary-6360

package/lib/props.d.ts

@@ -11,7 +11,7 @@ export declare function toSidebarDocItemLinkProp({ item, doc, }: {
     item: SidebarItemDoc;
     doc: Pick<DocMetadata, 'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'>;
 }): PropSidebarItemLink;
-export declare function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars;
+export declare function toSidebarsProp(loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>): PropSidebars;
 export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;
 export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {
     allTagsPath: string;

package/lib/props.js

@@ -18,6 +18,7 @@ function toSidebarDocItemLinkProp({ item, doc, }) {
     const { id, title, permalink, frontMatter, unlisted } = doc;
     return {
         type: 'link',
+        ...(item.key && { key: item.key }),
         href: permalink,
         // Front Matter data takes precedence over sidebars.json
         label: frontMatter.sidebar_label ?? item.label ?? title,

package/lib/sidebars/generator.js

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

package/lib/sidebars/types.d.ts

@@ -13,6 +13,7 @@ type Expand<T extends {
     [P in keyof T]: T[P];
 };
 export type SidebarItemBase = {
+    key?: string;
     className?: string;
     customProps?: {
         [key: string]: unknown;
@@ -23,8 +24,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;
 };
@@ -136,6 +138,7 @@ export type PropSidebars = {
 };
 export type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCategory;
 export type CategoryMetadataFile = {
+    key?: string;
     label?: string;
     position?: number;
     description?: string;

package/lib/sidebars/validation.js

@@ -13,6 +13,7 @@ const utils_validation_1 = require("@docusaurus/utils-validation");
 // Config types are exposed to users for typechecking and we use the same type
 // in normalization
 const sidebarItemBaseSchema = utils_validation_1.Joi.object({
+    key: utils_validation_1.Joi.string(),
     className: utils_validation_1.Joi.string(),
     customProps: utils_validation_1.Joi.object().unknown(),
 });
@@ -132,6 +133,7 @@ function validateSidebars(sidebars) {
     });
 }
 const categoryMetadataFileSchema = utils_validation_1.Joi.object({
+    key: utils_validation_1.Joi.string(),
     label: utils_validation_1.Joi.string(),
     description: utils_validation_1.Joi.string(),
     position: utils_validation_1.Joi.number(),

package/lib/translations.js

@@ -11,6 +11,7 @@ exports.translateLoadedContent = translateLoadedContent;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const constants_1 = require("./constants");
 const utils_2 = require("./sidebars/utils");
 function getVersionFileName(versionName) {
@@ -21,12 +22,33 @@ function getVersionFileName(versionName) {
     // but it's for consistency with site/versioned_docs
     return `version-${versionName}`;
 }
+function ensureNoSidebarDuplicateEntries(translationEntries) {
+    const grouped = lodash_1.default.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_1.default.code(translationKey)}: ${logger_1.default.num(entries.length)} duplicates found:\n  - ${entries
+                .map((duplicate) => {
+                const desc = duplicate[1].description;
+                return `${logger_1.default.name(duplicate[1].message)} ${desc ? `(${logger_1.default.subdue(desc)})` : ''}`;
+            })
+                .join('\n  - ')}`;
+        })
+            .join('\n\n- ')}
+
+To avoid translation key conflicts, use the ${logger_1.default.code('key')} attribute on the sidebar items above to uniquely identify them.
+    `);
+    }
+}
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
     const categories = (0, utils_2.collectSidebarCategories)(sidebar);
-    const categoryContent = Object.fromEntries(categories.flatMap((category) => {
+    const categoryEntries = categories.flatMap((category) => {
         const entries = [];
+        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}`,
@@ -35,7 +57,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
         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}`,
@@ -44,7 +66,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             }
             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}`,
@@ -53,26 +75,34 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             }
         }
         return entries;
-    }));
+    });
     const links = (0, utils_2.collectSidebarLinks)(sidebar);
-    const linksContent = 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 linksEntries = 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 = (0, utils_2.collectSidebarDocItems)(sidebar)
         .concat((0, utils_2.collectSidebarRefs)(sidebar))
         .filter((item) => item.translatable);
-    const docLinksContent = 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 (0, utils_1.mergeTranslations)([categoryContent, linksContent, docLinksContent]);
+    const docLinksEntries = 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}`,
+            },
+        ];
+    });
+    const allEntries = [...categoryEntries, ...linksEntries, ...docLinksEntries];
+    ensureNoSidebarDuplicateEntries(allEntries);
+    return Object.fromEntries(allEntries);
 }
 function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     function transformSidebarCategoryLink(category) {
@@ -93,24 +123,27 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     return (0, utils_2.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}`]
+                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}`]
+                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}`]
+                label: sidebarsTranslations[`sidebar.${sidebarName}.doc.${docKey}`]
                     ?.message ?? item.label,
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.8.1-canary-6358",
+  "version": "3.8.1-canary-6360",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,15 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.8.1-canary-6358",
-    "@docusaurus/logger": "3.8.1-canary-6358",
-    "@docusaurus/mdx-loader": "3.8.1-canary-6358",
-    "@docusaurus/module-type-aliases": "3.8.1-canary-6358",
-    "@docusaurus/theme-common": "3.8.1-canary-6358",
-    "@docusaurus/types": "3.8.1-canary-6358",
-    "@docusaurus/utils": "3.8.1-canary-6358",
-    "@docusaurus/utils-common": "3.8.1-canary-6358",
-    "@docusaurus/utils-validation": "3.8.1-canary-6358",
+    "@docusaurus/core": "3.8.1-canary-6360",
+    "@docusaurus/logger": "3.8.1-canary-6360",
+    "@docusaurus/mdx-loader": "3.8.1-canary-6360",
+    "@docusaurus/module-type-aliases": "3.8.1-canary-6360",
+    "@docusaurus/theme-common": "3.8.1-canary-6360",
+    "@docusaurus/types": "3.8.1-canary-6360",
+    "@docusaurus/utils": "3.8.1-canary-6360",
+    "@docusaurus/utils-common": "3.8.1-canary-6360",
+    "@docusaurus/utils-validation": "3.8.1-canary-6360",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "ffdb9f98cdff46de047de752705edb093a81e042"
+  "gitHead": "39d2663556664be19f2a18c24ceae1e532ab58df"
 }

package/src/props.ts

@@ -41,6 +41,7 @@ export function toSidebarDocItemLinkProp({
   const {id, title, permalink, frontMatter, unlisted} = doc;
   return {
     type: 'link',
+    ...(item.key && {key: item.key}),
     href: permalink,
     // Front Matter data takes precedence over sidebars.json
     label: frontMatter.sidebar_label ?? item.label ?? title,
@@ -51,7 +52,9 @@ export function toSidebarDocItemLinkProp({
   };
 }
 
-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/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,
       };
     }