@docusaurus/plugin-content-docs 3.9.1 → 3.9.2-alpha.0-canary-6548

package/lib/client/docsUtils.js

@@ -148,11 +148,18 @@ function getSidebarBreadcrumbs({ sidebarItems, pathname, onlyCategories = false,
     const breadcrumbs = [];
     function extract(items) {
         for (const item of items) {
-            if ((item.type === 'category' &&
-                (isSamePath(item.href, pathname) || extract(item.items))) ||
-                (item.type === 'link' && isSamePath(item.href, pathname))) {
-                const filtered = onlyCategories && item.type !== 'category';
-                if (!filtered) {
+            // Extract category item
+            if (item.type === 'category') {
+                if (isSamePath(item.href, pathname) || extract(item.items)) {
+                    breadcrumbs.unshift(item);
+                    return true;
+                }
+            }
+            // Extract doc item
+            else if (item.type === 'link' &&
+                item.docId &&
+                isSamePath(item.href, pathname)) {
+                if (!onlyCategories) {
                     breadcrumbs.unshift(item);
                 }
                 return true;

package/lib/docs.js

@@ -38,7 +38,7 @@ async function readVersionDocs(versionMetadata, options) {
 }
 async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, tagsFile, }) {
     const { source, content, contentPath, filePath } = docFile;
-    const { siteDir, siteConfig: { markdown: { parseFrontMatter }, }, } = context;
+    const { siteDir, siteConfig: { markdown: { parseFrontMatter }, future: { experimental_vcs: vcs }, }, } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = await (0, utils_1.parseMarkdownFile)({
         filePath,
         fileContent: content,
@@ -50,7 +50,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true, last_update: lastUpdateFrontMatter, } = frontMatter;
-    const lastUpdate = await (0, utils_1.readLastUpdateData)(filePath, options, lastUpdateFrontMatter);
+    const lastUpdate = await (0, utils_1.readLastUpdateData)(filePath, options, lastUpdateFrontMatter, vcs);
     // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
     // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .

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/index.js

@@ -75,7 +75,7 @@ async function pluginContentDocs(context, options) {
                         versionsMetadata,
                     }),
                 ].filter((d) => typeof d === 'string'),
-                useCrossCompilerCache: siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+                useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
                 admonitions: options.admonitions,
                 remarkPlugins,
                 rehypePlugins,

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}`,
             },
         ];
     });
@@ -110,8 +113,9 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
             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;
+            const categoryKey = category.key ?? category.label;
+            const title = sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`]?.message ?? category.link.title;
+            const description = sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`]?.message ?? category.link.description;
             return {
                 ...category.link,
                 title,
@@ -175,12 +179,51 @@ function getVersionTranslationFiles(version) {
         },
     ];
 }
+// TODO Docusaurus v4 or later
+//  this temporarily works, but it is not an ideal solution
+//  The docs navigation can be computed and shouldn't be part of LoadedVersion
+//  We need to derive the navigation from already translated content
+//  See https://github.com/facebook/docusaurus/pull/11794
+function translateDocNavigation(docs, translatedSidebars) {
+    // Build a map of permalink -> translated label for generated-index categories
+    const translatedLabelByPermalink = new Map();
+    for (const sidebar of Object.values(translatedSidebars)) {
+        for (const category of (0, utils_2.collectSidebarCategories)(sidebar)) {
+            if (category.link?.type === 'generated-index') {
+                translatedLabelByPermalink.set(category.link.permalink, category.label);
+            }
+        }
+    }
+    if (translatedLabelByPermalink.size === 0) {
+        return docs;
+    }
+    return docs.map((doc) => {
+        const previous = doc.previous && translatedLabelByPermalink.has(doc.previous.permalink)
+            ? {
+                ...doc.previous,
+                title: translatedLabelByPermalink.get(doc.previous.permalink),
+            }
+            : doc.previous;
+        const next = doc.next && translatedLabelByPermalink.has(doc.next.permalink)
+            ? {
+                ...doc.next,
+                title: translatedLabelByPermalink.get(doc.next.permalink),
+            }
+            : doc.next;
+        if (previous === doc.previous && next === doc.next) {
+            return doc;
+        }
+        return { ...doc, previous, next };
+    });
+}
 function translateVersion(version, translationFiles) {
     const versionTranslations = translationFiles[getVersionFileName(version.versionName)].content;
+    const translatedSidebars = translateSidebars(version, versionTranslations);
     return {
         ...version,
         label: versionTranslations['version.label']?.message ?? version.label,
-        sidebars: translateSidebars(version, versionTranslations),
+        sidebars: translatedSidebars,
+        docs: translateDocNavigation(version.docs, translatedSidebars),
     };
 }
 function getVersionsTranslationFiles(versions) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.9.1",
+  "version": "3.9.2-alpha.0-canary-6548",
   "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-alpha.0-canary-6548",
+    "@docusaurus/logger": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/mdx-loader": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/module-type-aliases": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/theme-common": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/types": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/utils": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/utils-common": "3.9.2-alpha.0-canary-6548",
+    "@docusaurus/utils-validation": "3.9.2-alpha.0-canary-6548",
     "@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": "7694572787296be09b95c6ff0a541ae19185a9f5"
 }

package/src/client/docsUtils.tsx

@@ -234,15 +234,22 @@ function getSidebarBreadcrumbs({
 }): PropSidebarBreadcrumbsItem[] {
   const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
 
-  function extract(items: PropSidebarItem[]) {
+  function extract(items: PropSidebarItem[]): boolean {
     for (const item of items) {
-      if (
-        (item.type === 'category' &&
-          (isSamePath(item.href, pathname) || extract(item.items))) ||
-        (item.type === 'link' && isSamePath(item.href, pathname))
+      // Extract category item
+      if (item.type === 'category') {
+        if (isSamePath(item.href, pathname) || extract(item.items)) {
+          breadcrumbs.unshift(item);
+          return true;
+        }
+      }
+      // Extract doc item
+      else if (
+        item.type === 'link' &&
+        item.docId &&
+        isSamePath(item.href, pathname)
       ) {
-        const filtered = onlyCategories && item.type !== 'category';
-        if (!filtered) {
+        if (!onlyCategories) {
           breadcrumbs.unshift(item);
         }
         return true;

package/src/docs.ts

@@ -97,6 +97,7 @@ async function doProcessDocMetadata({
     siteDir,
     siteConfig: {
       markdown: {parseFrontMatter},
+      future: {experimental_vcs: vcs},
     },
   } = context;
 
@@ -125,6 +126,7 @@ async function doProcessDocMetadata({
     filePath,
     options,
     lastUpdateFrontMatter,
+    vcs,
   );
 
   // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc

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/index.ts

@@ -131,8 +131,7 @@ export default async function pluginContentDocs(
           }),
         ].filter((d): d is string => typeof d === 'string'),
 
-        useCrossCompilerCache:
-          siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+        useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
         admonitions: options.admonitions,
         remarkPlugins,
         rehypePlugins,

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
         }`,
       },
@@ -168,13 +177,14 @@ function translateSidebar({
       return undefined;
     }
     if (category.link.type === 'generated-index') {
+      const categoryKey = category.key ?? category.label;
       const title =
         sidebarsTranslations[
-          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`
+          `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`
         ]?.message ?? category.link.title;
       const description =
         sidebarsTranslations[
-          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`
+          `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`
         ]?.message ?? category.link.description;
       return {
         ...category.link,
@@ -259,16 +269,64 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
     },
   ];
 }
+
+// TODO Docusaurus v4 or later
+//  this temporarily works, but it is not an ideal solution
+//  The docs navigation can be computed and shouldn't be part of LoadedVersion
+//  We need to derive the navigation from already translated content
+//  See https://github.com/facebook/docusaurus/pull/11794
+function translateDocNavigation(
+  docs: LoadedVersion['docs'],
+  translatedSidebars: Sidebars,
+): LoadedVersion['docs'] {
+  // Build a map of permalink -> translated label for generated-index categories
+  const translatedLabelByPermalink = new Map<string, string>();
+  for (const sidebar of Object.values(translatedSidebars)) {
+    for (const category of collectSidebarCategories(sidebar)) {
+      if (category.link?.type === 'generated-index') {
+        translatedLabelByPermalink.set(category.link.permalink, category.label);
+      }
+    }
+  }
+
+  if (translatedLabelByPermalink.size === 0) {
+    return docs;
+  }
+
+  return docs.map((doc) => {
+    const previous =
+      doc.previous && translatedLabelByPermalink.has(doc.previous.permalink)
+        ? {
+            ...doc.previous,
+            title: translatedLabelByPermalink.get(doc.previous.permalink)!,
+          }
+        : doc.previous;
+    const next =
+      doc.next && translatedLabelByPermalink.has(doc.next.permalink)
+        ? {
+            ...doc.next,
+            title: translatedLabelByPermalink.get(doc.next.permalink)!,
+          }
+        : doc.next;
+    if (previous === doc.previous && next === doc.next) {
+      return doc;
+    }
+    return {...doc, previous, next};
+  });
+}
+
 function translateVersion(
   version: LoadedVersion,
   translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion {
   const versionTranslations =
     translationFiles[getVersionFileName(version.versionName)]!.content;
+  const translatedSidebars = translateSidebars(version, versionTranslations);
   return {
     ...version,
     label: versionTranslations['version.label']?.message ?? version.label,
-    sidebars: translateSidebars(version, versionTranslations),
+    sidebars: translatedSidebars,
+    docs: translateDocNavigation(version.docs, translatedSidebars),
   };
 }