@docusaurus/plugin-content-docs 0.0.0-4619 → 0.0.0-4622

package/lib/sidebars/normalization.js

@@ -10,6 +10,7 @@ exports.normalizeSidebars = exports.normalizeItem = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("./utils");
 const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 function normalizeCategoriesShorthand(sidebar) {
     return Object.entries(sidebar).map(([label, items]) => ({
         type: 'category',
@@ -23,38 +24,32 @@ function normalizeCategoriesShorthand(sidebar) {
  */
 function normalizeItem(item) {
     if (typeof item === 'string') {
-        return [
-            {
-                type: 'doc',
-                id: item,
-            },
-        ];
+        return [{ type: 'doc', id: item }];
     }
     if ((0, utils_1.isCategoriesShorthand)(item)) {
-        return normalizeCategoriesShorthand(item).flatMap((subItem) => normalizeItem(subItem));
+        // This will never throw anyways
+        return normalizeSidebar(item, 'sidebar items slice');
     }
     if (item.type === 'category') {
-        if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
-            throw new Error(`Invalid category ${JSON.stringify(item)}: items must be an array of sidebar items or a category shorthand`);
-        }
         const normalizedCategory = {
             ...item,
-            items: Array.isArray(item.items)
-                ? item.items.flatMap((subItem) => normalizeItem(subItem))
-                : normalizeCategoriesShorthand(item.items).flatMap((subItem) => normalizeItem(subItem)),
+            items: normalizeSidebar(item.items, logger_1.default.interpolate `code=${'items'} of the category name=${item.label}`),
         };
         return [normalizedCategory];
     }
     return [item];
 }
 exports.normalizeItem = normalizeItem;
-function normalizeSidebar(sidebar) {
+function normalizeSidebar(sidebar, place) {
+    if (!Array.isArray(sidebar) && !(0, utils_1.isCategoriesShorthand)(sidebar)) {
+        throw new Error(logger_1.default.interpolate `Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
+    }
     const normalizedSidebar = Array.isArray(sidebar)
         ? sidebar
         : normalizeCategoriesShorthand(sidebar);
     return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
 }
 function normalizeSidebars(sidebars) {
-    return lodash_1.default.mapValues(sidebars, normalizeSidebar);
+    return lodash_1.default.mapValues(sidebars, (sidebar, id) => normalizeSidebar(sidebar, logger_1.default.interpolate `sidebar name=${id}`));
 }
 exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/utils.js

@@ -11,7 +11,7 @@ const tslib_1 = require("tslib");
 const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 function isCategoriesShorthand(item) {
-    return typeof item !== 'string' && !item.type;
+    return typeof item === 'object' && !item.type;
 }
 exports.isCategoriesShorthand = isCategoriesShorthand;
 function transformSidebarItems(sidebar, updateFn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4619",
+  "version": "0.0.0-4622",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4619",
-    "@docusaurus/logger": "0.0.0-4619",
-    "@docusaurus/mdx-loader": "0.0.0-4619",
-    "@docusaurus/utils": "0.0.0-4619",
-    "@docusaurus/utils-validation": "0.0.0-4619",
+    "@docusaurus/core": "0.0.0-4622",
+    "@docusaurus/logger": "0.0.0-4622",
+    "@docusaurus/mdx-loader": "0.0.0-4622",
+    "@docusaurus/utils": "0.0.0-4622",
+    "@docusaurus/utils-validation": "0.0.0-4622",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.0",
     "import-fresh": "^3.3.0",
@@ -39,8 +39,8 @@
     "webpack": "^5.69.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4619",
-    "@docusaurus/types": "0.0.0-4619",
+    "@docusaurus/module-type-aliases": "0.0.0-4622",
+    "@docusaurus/types": "0.0.0-4622",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -56,5 +56,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ec771a43284544899f7dd4ef59a8b794c51f2399"
+  "gitHead": "88fa597b10a32d3f2e3cff963af8337e66f89a13"
 }

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

@@ -8,6 +8,10 @@
 declare module '@docusaurus/plugin-content-docs' {
   import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
 
+  export interface Assets {
+    image?: string;
+  }
+
   export type NumberPrefixParser = (filename: string) => {
     filename: string;
     numberPrefix?: number;
@@ -159,6 +163,7 @@ declare module '@theme/DocItem' {
   import type {
     PropNavigationLink,
     PropVersionMetadata,
+    Assets,
   } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
@@ -204,6 +209,7 @@ declare module '@theme/DocItem' {
       readonly metadata: Metadata;
       readonly toc: readonly TOCItem[];
       readonly contentTitle: string | undefined;
+      readonly assets: Assets;
       (): JSX.Element;
     };
   }

package/src/sidebars/normalization.ts

@@ -18,6 +18,7 @@ import type {
 } from './types';
 import {isCategoriesShorthand} from './utils';
 import _ from 'lodash';
+import logger from '@docusaurus/logger';
 
 function normalizeCategoriesShorthand(
   sidebar: SidebarCategoriesShorthand,
@@ -37,40 +38,37 @@ export function normalizeItem(
   item: SidebarItemConfig,
 ): NormalizedSidebarItem[] {
   if (typeof item === 'string') {
-    return [
-      {
-        type: 'doc',
-        id: item,
-      },
-    ];
+    return [{type: 'doc', id: item}];
   }
   if (isCategoriesShorthand(item)) {
-    return normalizeCategoriesShorthand(item).flatMap((subItem) =>
-      normalizeItem(subItem),
-    );
+    // This will never throw anyways
+    return normalizeSidebar(item, 'sidebar items slice');
   }
   if (item.type === 'category') {
-    if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
-      throw new Error(
-        `Invalid category ${JSON.stringify(
-          item,
-        )}: items must be an array of sidebar items or a category shorthand`,
-      );
-    }
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,
-      items: Array.isArray(item.items)
-        ? item.items.flatMap((subItem) => normalizeItem(subItem))
-        : normalizeCategoriesShorthand(item.items).flatMap((subItem) =>
-            normalizeItem(subItem),
-          ),
+      items: normalizeSidebar(
+        item.items,
+        logger.interpolate`code=${'items'} of the category name=${item.label}`,
+      ),
     };
     return [normalizedCategory];
   }
   return [item];
 }
 
-function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar {
+function normalizeSidebar(
+  sidebar: SidebarConfig,
+  place: string,
+): NormalizedSidebar {
+  if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) {
+    throw new Error(
+      logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
+        sidebar,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+    );
+  }
+
   const normalizedSidebar = Array.isArray(sidebar)
     ? sidebar
     : normalizeCategoriesShorthand(sidebar);
@@ -81,5 +79,7 @@ function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar {
 export function normalizeSidebars(
   sidebars: SidebarsConfig,
 ): NormalizedSidebars {
-  return _.mapValues(sidebars, normalizeSidebar);
+  return _.mapValues(sidebars, (sidebar, id) =>
+    normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`),
+  );
 }

package/src/sidebars/utils.ts

@@ -26,7 +26,7 @@ import type {DocMetadataBase, DocNavLink} from '../types';
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
 ): item is SidebarCategoriesShorthand {
-  return typeof item !== 'string' && !item.type;
+  return typeof item === 'object' && !item.type;
 }
 
 export function transformSidebarItems(