@docusaurus/plugin-content-docs 0.0.0-4875 → 0.0.0-4876

package/lib/docs.js

@@ -70,11 +70,9 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env,
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
-    // ex: api/plugins/myDoc -> myDoc
-    // ex: myDoc -> myDoc
+    // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
-    // ex: api/plugins/myDoc -> api/plugins
-    // ex: myDoc -> .
+    // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
     const sourceDirName = path_1.default.dirname(source);
     const { filename: unprefixedFileName, numberPrefix } = parseNumberPrefixes
         ? options.numberPrefixParser(sourceFileNameWithoutExtension)
@@ -208,7 +206,7 @@ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
         return { ...doc, sidebar: navigation.sidebarName, previous, next };
     }
     const docsWithNavigation = docsBase.map(addNavData);
-    // sort to ensure consistent output for tests
+    // Sort to ensure consistent output for tests
     docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
     return docsWithNavigation;
 }
@@ -276,7 +274,7 @@ function getDocIds(doc) {
     return [doc.unversionedId, doc.id];
 }
 exports.getDocIds = getDocIds;
-// docs are indexed by both versioned and unversioned ids at the same time
+// Docs are indexed by both versioned and unversioned ids at the same time
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed
 // to "id")

package/lib/frontMatter.js

@@ -14,11 +14,13 @@ const utils_validation_1 = require("@docusaurus/utils-validation");
 // We use default values in code instead
 const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     id: utils_validation_1.JoiFrontMatter.string(),
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     title: utils_validation_1.JoiFrontMatter.string().allow(''),
     hide_title: utils_validation_1.JoiFrontMatter.boolean(),
     hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
     keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
     image: utils_validation_1.URISchema,
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     slug: utils_validation_1.JoiFrontMatter.string(),
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),

package/lib/routes.js

@@ -75,11 +75,9 @@ async function createVersionRoutes({ loadedVersion, actions, docItemComponent, d
         }
         actions.addRoute({
             path: version.path,
-            // allow matching /docs/* as well
+            // Allow matching /docs/* since this is the wrapping route
             exact: false,
-            // main docs component (DocPage)
             component: docLayoutComponent,
-            // sub-routes for each doc
             routes: await createVersionSubRoutes(),
             modules: {
                 versionMetadata: aliasedSource(versionMetadataPropPath),

package/lib/sidebars/generator.js

@@ -41,9 +41,9 @@ Available doc IDs:
             return (
             // Doc at the root of the autogenerated sidebar dir
             doc.sourceDirName === autogenDir ||
-                // autogen dir is . and doc is in subfolder
+                // Autogen dir is . and doc is in subfolder
                 autogenDir === '.' ||
-                // autogen dir is not . and doc is in subfolder
+                // Autogen dir is not . and doc is in subfolder
                 // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
                 doc.sourceDirName.startsWith((0, utils_1.addTrailingSlash)(autogenDir)));
         }

package/lib/sidebars/postProcessor.js

@@ -12,7 +12,7 @@ const utils_1 = require("@docusaurus/utils");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function normalizeCategoryLink(category, params) {
     if (category.link?.type === 'generated-index') {
-        // default slug logic can be improved
+        // Default slug logic can be improved
         const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
         const slug = category.link.slug ?? getDefaultSlug();
         const permalink = (0, utils_1.normalizeUrl)([params.version.path, slug]);

package/lib/sidebars/types.d.ts

@@ -150,7 +150,7 @@ export declare type SidebarItemsGeneratorArgs = {
     /** The default category index matcher which you can override. */
     isCategoryIndex: CategoryIndexMatcher;
     /**
-     * key is the path relative to the doc content directory, value is the
+     * Key is the path relative to the doc content directory, value is the
      * category metadata file's content.
      */
     categoriesMetadata: {

package/lib/translations.js

@@ -30,49 +30,6 @@ function getNormalizedSidebarName({ versionName, sidebarName, }) {
     const [, ...rest] = sidebarName.split('/');
     return rest.join('/');
 }
-/*
-// Do we need to translate doc metadata?
-// It seems translating front matter 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, sidebarName) {
     const categories = (0, utils_1.collectSidebarCategories)(sidebar);
     const categoryContent = Object.fromEntries(categories.flatMap((category) => {
@@ -179,16 +136,10 @@ function getVersionTranslationFiles(version) {
         },
     };
     const sidebarsTranslations = getSidebarsTranslations(version);
-    // const docsTranslations: TranslationFileContent =
-    //   getDocsTranslations(version);
     return [
         {
             path: getVersionFileName(version.versionName),
-            content: (0, utils_2.mergeTranslations)([
-                versionTranslations,
-                sidebarsTranslations,
-                // docsTranslations,
-            ]),
+            content: (0, utils_2.mergeTranslations)([versionTranslations, sidebarsTranslations]),
         },
     ];
 }
@@ -198,7 +149,6 @@ function translateVersion(version, translationFiles) {
         ...version,
         label: versionTranslations['version.label']?.message ?? version.label,
         sidebars: translateSidebars(version, versionTranslations),
-        // docs: translateDocs(version.docs, versionTranslations),
     };
 }
 function getVersionsTranslationFiles(versions) {

package/lib/types.d.ts

@@ -19,7 +19,7 @@ export declare type SourceToPermalink = {
     [source: string]: string;
 };
 export declare type VersionTag = Tag & {
-    /** all doc ids having this tag. */
+    /** All doc ids having this tag. */
     docIds: string[];
 };
 export declare type VersionTags = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4875",
+  "version": "0.0.0-4876",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -24,11 +24,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4875",
-    "@docusaurus/logger": "0.0.0-4875",
-    "@docusaurus/mdx-loader": "0.0.0-4875",
-    "@docusaurus/utils": "0.0.0-4875",
-    "@docusaurus/utils-validation": "0.0.0-4875",
+    "@docusaurus/core": "0.0.0-4876",
+    "@docusaurus/logger": "0.0.0-4876",
+    "@docusaurus/mdx-loader": "0.0.0-4876",
+    "@docusaurus/utils": "0.0.0-4876",
+    "@docusaurus/utils-validation": "0.0.0-4876",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.1",
     "import-fresh": "^3.3.0",
@@ -40,8 +40,8 @@
     "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4875",
-    "@docusaurus/types": "0.0.0-4875",
+    "@docusaurus/module-type-aliases": "0.0.0-4876",
+    "@docusaurus/types": "0.0.0-4876",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ee48d072632c7eb6d03da4acf5800f8d42eee680"
+  "gitHead": "ed43a09bc7cd70a5035d8ec19eb53393fd83dc4f"
 }

package/src/docs.ts

@@ -156,15 +156,13 @@ function doProcessDocMetadata({
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
-  // ex: api/plugins/myDoc -> myDoc
-  // ex: myDoc -> myDoc
+  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
     path.extname(source),
   );
 
-  // ex: api/plugins/myDoc -> api/plugins
-  // ex: myDoc -> .
+  // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
   const sourceDirName = path.dirname(source);
 
   const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
@@ -347,7 +345,7 @@ export function addDocNavigation(
   }
 
   const docsWithNavigation = docsBase.map(addNavData);
-  // sort to ensure consistent output for tests
+  // Sort to ensure consistent output for tests
   docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
   return docsWithNavigation;
 }
@@ -434,7 +432,7 @@ export function getDocIds(doc: DocMetadataBase): [string, string] {
   return [doc.unversionedId, doc.id];
 }
 
-// docs are indexed by both versioned and unversioned ids at the same time
+// Docs are indexed by both versioned and unversioned ids at the same time
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed
 // to "id")

package/src/frontMatter.ts

@@ -20,12 +20,14 @@ import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   id: Joi.string(),
-  title: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  title: Joi.string().allow(''),
   hide_title: Joi.boolean(),
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
   image: URISchema,
-  description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),

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

@@ -19,7 +19,7 @@ declare module '@docusaurus/plugin-content-docs' {
    * Custom callback for parsing number prefixes from file/folder names.
    */
   export type NumberPrefixParser = (filename: string) => {
-    /** file name without number prefix, without any other modification. */
+    /** File name without number prefix, without any other modification. */
     filename: string;
     /** The number prefix. Can be float, integer, negative, or anything. */
     numberPrefix?: number;
@@ -621,9 +621,9 @@ declare module '@docusaurus/plugin-content-docs/client' {
     breadcrumbs: boolean;
   };
   export type DocVersionSuggestions = {
-    /** suggest the latest version */
+    /** Suggest the latest version */
     latestVersionSuggestion: GlobalVersion;
-    /** suggest the same doc, in latest version (if exist) */
+    /** Suggest the same doc, in latest version (if one exists) */
     latestDocSuggestion?: GlobalDoc;
   };
 

package/src/routes.ts

@@ -139,11 +139,9 @@ export async function createVersionRoutes({
 
     actions.addRoute({
       path: version.path,
-      // allow matching /docs/* as well
+      // Allow matching /docs/* since this is the wrapping route
       exact: false,
-      // main docs component (DocPage)
       component: docLayoutComponent,
-      // sub-routes for each doc
       routes: await createVersionSubRoutes(),
       modules: {
         versionMetadata: aliasedSource(versionMetadataPropPath),

package/src/sidebars/generator.ts

@@ -76,9 +76,9 @@ Available doc IDs:
       return (
         // Doc at the root of the autogenerated sidebar dir
         doc.sourceDirName === autogenDir ||
-        // autogen dir is . and doc is in subfolder
+        // Autogen dir is . and doc is in subfolder
         autogenDir === '.' ||
-        // autogen dir is not . and doc is in subfolder
+        // Autogen dir is not . and doc is in subfolder
         // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
         doc.sourceDirName.startsWith(addTrailingSlash(autogenDir))
       );

package/src/sidebars/postProcessor.ts

@@ -22,7 +22,7 @@ function normalizeCategoryLink(
   params: SidebarProcessorParams,
 ): SidebarItemCategoryLink | undefined {
   if (category.link?.type === 'generated-index') {
-    // default slug logic can be improved
+    // Default slug logic can be improved
     const getDefaultSlug = () =>
       `/category/${params.categoryLabelSlugger.slug(category.label)}`;
     const slug = category.link.slug ?? getDefaultSlug();

package/src/sidebars/types.ts

@@ -180,7 +180,6 @@ export type PropSidebarItemCategory = Expand<
   }
 >;
 
-// we may want to use a union type in props instead of this generic link?
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
@@ -245,7 +244,7 @@ export type SidebarItemsGeneratorArgs = {
   /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
   /**
-   * key is the path relative to the doc content directory, value is the
+   * Key is the path relative to the doc content directory, value is the
    * category metadata file's content.
    */
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile};

package/src/translations.ts

@@ -53,50 +53,6 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadata?
-// It seems translating front matter 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,
@@ -252,17 +208,10 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
   const sidebarsTranslations: TranslationFileContent =
     getSidebarsTranslations(version);
 
-  // const docsTranslations: TranslationFileContent =
-  //   getDocsTranslations(version);
-
   return [
     {
       path: getVersionFileName(version.versionName),
-      content: mergeTranslations([
-        versionTranslations,
-        sidebarsTranslations,
-        // docsTranslations,
-      ]),
+      content: mergeTranslations([versionTranslations, sidebarsTranslations]),
     },
   ];
 }
@@ -276,7 +225,6 @@ function translateVersion(
     ...version,
     label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
-    // docs: translateDocs(version.docs, versionTranslations),
   };
 }
 

package/src/types.ts

@@ -30,7 +30,7 @@ export type SourceToPermalink = {
 };
 
 export type VersionTag = Tag & {
-  /** all doc ids having this tag. */
+  /** All doc ids having this tag. */
   docIds: string[];
 };
 export type VersionTags = {