@docusaurus/plugin-content-docs 3.9.1 → 3.9.2

package/lib/frontMatter.js

@@ -24,6 +24,7 @@ exports.DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     slug: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_key: utils_validation_1.JoiFrontMatter.string(),
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
     sidebar_position: utils_validation_1.JoiFrontMatter.number(),
     sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),

package/lib/sidebars/generator.js

@@ -91,7 +91,7 @@ Available doc IDs:
      */
     function generateSidebar(fsModel) {
         function createDocItem(id, fullPath, fileName) {
-            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className, sidebar_custom_props: customProps, }, } = getDoc(id);
+            const { sidebarPosition: position, frontMatter: { sidebar_key: key, sidebar_label: label, sidebar_class_name: className, sidebar_custom_props: customProps, }, } = getDoc(id);
             return {
                 type: 'doc',
                 id,
@@ -99,6 +99,7 @@ Available doc IDs:
                 source: fileName,
                 // We don't want these fields to magically appear in the generated
                 // sidebar
+                ...(key !== undefined && { key }),
                 ...(label !== undefined && { label }),
                 ...(className !== undefined && { className }),
                 ...(customProps !== undefined && { customProps }),
@@ -139,6 +140,7 @@ Available doc IDs:
                 return {
                     id,
                     position: doc.sidebarPosition,
+                    key: doc.frontMatter.sidebar_key,
                     label: doc.frontMatter.sidebar_label ?? doc.title,
                     customProps: doc.frontMatter.sidebar_custom_props,
                     className: doc.frontMatter.sidebar_class_name,
@@ -156,6 +158,7 @@ Available doc IDs:
             const className = categoryMetadata?.className ?? categoryLinkedDoc?.className;
             const customProps = categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
             const { filename, numberPrefix } = numberPrefixParser(folderName);
+            const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
             return {
                 type: 'category',
                 label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
@@ -171,7 +174,7 @@ Available doc IDs:
                 ...(categoryMetadata?.description && {
                     description: categoryMetadata?.description,
                 }),
-                ...(categoryMetadata?.key && { key: categoryMetadata?.key }),
+                ...(key && { key }),
                 ...(link && { link }),
             };
         }

package/lib/translations.js

@@ -39,7 +39,10 @@ function ensureNoSidebarDuplicateEntries(translationEntries) {
             .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.
-    `);
+
+When using autogenerated sidebars, you can provide a unique translation key by adding:
+- the ${logger_1.default.code('key')} attribute to category item metadata (${logger_1.default.code('_category_.json')} / ${logger_1.default.code('_category_.yml')})
+- the ${logger_1.default.code('sidebar_key')} attribute to doc item metadata (front matter in ${logger_1.default.code('Category/index.mdx')})`);
     }
 }
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
@@ -51,7 +54,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             `sidebar.${sidebarName}.category.${categoryKey}`,
             {
                 message: category.label,
-                description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+                description: `The label for category '${category.label}' in sidebar '${sidebarName}'`,
             },
         ]);
         if (category.link?.type === 'generated-index') {
@@ -60,7 +63,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
                     `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}`,
+                        description: `The generated-index page title for category '${category.label}' in sidebar '${sidebarName}'`,
                     },
                 ]);
             }
@@ -69,7 +72,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
                     `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}`,
+                        description: `The generated-index page description for category '${category.label}' in sidebar '${sidebarName}'`,
                     },
                 ]);
             }
@@ -83,7 +86,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             `sidebar.${sidebarName}.link.${linkKey}`,
             {
                 message: link.label,
-                description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+                description: `The label for link '${link.label}' in sidebar '${sidebarName}', linking to '${link.href}'`,
             },
         ];
     });
@@ -96,7 +99,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             `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}`,
+                description: `The label for the doc item '${doc.label}' in sidebar '${sidebarName}', linking to the doc ${doc.id}`,
             },
         ];
     });

package/package.json

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

package/src/frontMatter.ts

@@ -30,6 +30,7 @@ export const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   description: Joi.string().allow(''),
   slug: Joi.string(),
+  sidebar_key: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),

package/src/plugin-content-docs.d.ts

@@ -339,7 +339,15 @@ declare module '@docusaurus/plugin-content-docs' {
      * @see {@link DocMetadata.slug}
      */
     slug?: string;
-    /** Customizes the sidebar label for this doc. Will default to its title. */
+    /**
+     * Customizes the sidebar key for this doc,
+     * to uniquely identify it in translations.
+     */
+    sidebar_key?: string;
+    /**
+     * Customizes the sidebar label for this doc.
+     * Will default to its title.
+     */
     sidebar_label?: string;
     /**
      * Controls the position of a doc inside the generated sidebar slice when

package/src/sidebars/generator.ts

@@ -139,6 +139,7 @@ Available doc IDs:
       const {
         sidebarPosition: position,
         frontMatter: {
+          sidebar_key: key,
           sidebar_label: label,
           sidebar_class_name: className,
           sidebar_custom_props: customProps,
@@ -151,6 +152,7 @@ Available doc IDs:
         source: fileName,
         // We don't want these fields to magically appear in the generated
         // sidebar
+        ...(key !== undefined && {key}),
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
         ...(customProps !== undefined && {customProps}),
@@ -191,6 +193,7 @@ Available doc IDs:
       function getCategoryLinkedDocMetadata():
         | {
             id: string;
+            key?: string;
             position?: number;
             label?: string;
             customProps?: {[key: string]: unknown};
@@ -212,6 +215,7 @@ Available doc IDs:
         return {
           id,
           position: doc.sidebarPosition,
+          key: doc.frontMatter.sidebar_key,
           label: doc.frontMatter.sidebar_label ?? doc.title,
           customProps: doc.frontMatter.sidebar_custom_props,
           className: doc.frontMatter.sidebar_class_name,
@@ -236,6 +240,8 @@ Available doc IDs:
         categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
 
+      const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
+
       return {
         type: 'category',
         label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
@@ -252,7 +258,7 @@ Available doc IDs:
         ...(categoryMetadata?.description && {
           description: categoryMetadata?.description,
         }),
-        ...(categoryMetadata?.key && {key: categoryMetadata?.key}),
+        ...(key && {key}),
         ...(link && {link}),
       };
     }

package/src/translations.ts

@@ -71,7 +71,16 @@ function ensureNoSidebarDuplicateEntries(
 To avoid translation key conflicts, use the ${logger.code(
       'key',
     )} attribute on the sidebar items above to uniquely identify them.
-    `);
+
+When using autogenerated sidebars, you can provide a unique translation key by adding:
+- the ${logger.code('key')} attribute to category item metadata (${logger.code(
+      '_category_.json',
+    )} / ${logger.code('_category_.yml')})
+- the ${logger.code(
+      'sidebar_key',
+    )} attribute to doc item metadata (front matter in ${logger.code(
+      'Category/index.mdx',
+    )})`);
   }
 }
 
@@ -90,7 +99,7 @@ function getSidebarTranslationFileContent(
         `sidebar.${sidebarName}.category.${categoryKey}`,
         {
           message: category.label,
-          description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+          description: `The label for category '${category.label}' in sidebar '${sidebarName}'`,
         },
       ]);
 
@@ -100,7 +109,7 @@ function getSidebarTranslationFileContent(
             `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}`,
+              description: `The generated-index page title for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -109,7 +118,7 @@ function getSidebarTranslationFileContent(
             `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}`,
+              description: `The generated-index page description for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -126,7 +135,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.link.${linkKey}`,
       {
         message: link.label,
-        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+        description: `The label for link '${link.label}' in sidebar '${sidebarName}', linking to '${link.href}'`,
       },
     ];
   });
@@ -140,7 +149,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.doc.${docKey}`,
       {
         message: doc.label!,
-        description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${
+        description: `The label for the doc item '${doc.label!}' in sidebar '${sidebarName}', linking to the doc ${
           doc.id
         }`,
       },