@docusaurus/plugin-content-docs 0.0.0-4360 → 0.0.0-4361

package/lib/globalData.d.ts

@@ -4,6 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
+import type { Sidebars } from './sidebars/types';
+import type { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion, GlobalSidebar } from './types';
 export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
+export declare function toGlobalSidebars(sidebars: Sidebars, version: LoadedVersion): Record<string, GlobalSidebar>;
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

package/lib/globalData.js

@@ -6,7 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = exports.toGlobalDataDoc = void 0;
+exports.toGlobalDataVersion = exports.toGlobalSidebars = exports.toGlobalDataDoc = void 0;
+const lodash_1 = require("lodash");
+const utils_1 = require("@docusaurus/utils");
+const utils_2 = require("./sidebars/utils");
 function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
@@ -15,6 +18,24 @@ function toGlobalDataDoc(doc) {
     };
 }
 exports.toGlobalDataDoc = toGlobalDataDoc;
+function toGlobalSidebars(sidebars, version) {
+    const { getFirstLink } = (0, utils_2.createSidebarsUtils)(sidebars);
+    return (0, lodash_1.mapValues)(sidebars, (sidebar, sidebarId) => {
+        const firstLink = getFirstLink(sidebarId);
+        if (!firstLink) {
+            return {};
+        }
+        return {
+            link: {
+                path: firstLink.type === 'generated-index'
+                    ? (0, utils_1.normalizeUrl)([version.versionPath, firstLink.slug])
+                    : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
+                label: firstLink.label,
+            },
+        };
+    });
+}
+exports.toGlobalSidebars = toGlobalSidebars;
 function toGlobalDataVersion(version) {
     return {
         name: version.versionName,
@@ -23,6 +44,7 @@ function toGlobalDataVersion(version) {
         path: version.versionPath,
         mainDocId: version.mainDocId,
         docs: version.docs.map(toGlobalDataDoc),
+        sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }
 exports.toGlobalDataVersion = toGlobalDataVersion;

package/lib/sidebars/utils.d.ts

@@ -27,6 +27,15 @@ export declare type SidebarsUtils = {
     getDocNavigation: (unversionedId: string, versionedId: string) => SidebarNavigation;
     getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
     getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
+    getFirstLink: (sidebarId: string) => {
+        type: 'doc';
+        id: string;
+        label: string;
+    } | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+    } | undefined;
     checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
 export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;

package/lib/sidebars/utils.js

@@ -173,6 +173,42 @@ Available document ids are:
 - ${(0, lodash_1.uniq)(validDocIds).sort().join('\n- ')}`);
         }
     }
+    function getFirstLink(sidebar) {
+        var _a, _b, _c;
+        // eslint-disable-next-line no-restricted-syntax
+        for (const item of sidebar) {
+            if (item.type === 'doc') {
+                return {
+                    type: 'doc',
+                    id: item.id,
+                    label: (_a = item.label) !== null && _a !== void 0 ? _a : item.id,
+                };
+            }
+            else if (item.type === 'category') {
+                if (((_b = item.link) === null || _b === void 0 ? void 0 : _b.type) === 'doc') {
+                    return {
+                        type: 'doc',
+                        id: item.link.id,
+                        label: item.label,
+                    };
+                }
+                else if (((_c = item.link) === null || _c === void 0 ? void 0 : _c.type) === 'generated-index') {
+                    return {
+                        type: 'generated-index',
+                        slug: item.link.slug,
+                        label: item.label,
+                    };
+                }
+                else {
+                    const firstSubItem = getFirstLink(item.items);
+                    if (firstSubItem) {
+                        return firstSubItem;
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
     return {
         sidebars,
         getFirstDocIdOfFirstSidebar,
@@ -181,6 +217,7 @@ Available document ids are:
         getCategoryGeneratedIndexList,
         getCategoryGeneratedIndexNavigation,
         checkSidebarsDocIds,
+        getFirstLink: (id) => getFirstLink(sidebars[id]),
     };
 }
 exports.createSidebarsUtils = createSidebarsUtils;

package/lib/types.d.ts

@@ -180,6 +180,14 @@ export declare type GlobalVersion = {
     path: string;
     mainDocId: string;
     docs: GlobalDoc[];
+    sidebars?: Record<string, GlobalSidebar>;
+};
+export declare type GlobalSidebarLink = {
+    label: string;
+    path: string;
+};
+export declare type GlobalSidebar = {
+    link?: GlobalSidebarLink;
 };
 export declare type GlobalPluginData = {
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4360",
+  "version": "0.0.0-4361",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-docs.d.ts",
@@ -18,11 +18,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4360",
-    "@docusaurus/logger": "0.0.0-4360",
-    "@docusaurus/mdx-loader": "0.0.0-4360",
-    "@docusaurus/utils": "0.0.0-4360",
-    "@docusaurus/utils-validation": "0.0.0-4360",
+    "@docusaurus/core": "0.0.0-4361",
+    "@docusaurus/logger": "0.0.0-4361",
+    "@docusaurus/mdx-loader": "0.0.0-4361",
+    "@docusaurus/utils": "0.0.0-4361",
+    "@docusaurus/utils-validation": "0.0.0-4361",
     "combine-promises": "^1.1.0",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
@@ -38,8 +38,8 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4360",
-    "@docusaurus/types": "0.0.0-4360",
+    "@docusaurus/module-type-aliases": "0.0.0-4361",
+    "@docusaurus/types": "0.0.0-4361",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -53,5 +53,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "92744da65a37c440a0d3077b217f4e0033b664ce"
+  "gitHead": "1bf29811c8ead0651a1e56a5c8e15dd3232056e5"
 }

package/src/globalData.ts

@@ -5,11 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
 import type {
   DocMetadata,
   GlobalDoc,
   LoadedVersion,
   GlobalVersion,
+  GlobalSidebar,
 } from './types';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
@@ -20,6 +25,31 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<string, GlobalSidebar> {
+  const {getFirstLink} = createSidebarsUtils(sidebars);
+  return mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? normalizeUrl([version.versionPath, firstLink.slug])
+            : version.docs.find(
+                (doc) =>
+                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
+              )!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -28,5 +58,6 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     path: version.versionPath,
     mainDocId: version.mainDocId,
     docs: version.docs.map(toGlobalDataDoc),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

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

@@ -11,9 +11,10 @@ declare module '@docusaurus/plugin-content-docs' {
   export type VersionBanner = import('./types').VersionBanner;
   type GlobalDataVersion = import('./types').GlobalVersion;
   type GlobalDataDoc = import('./types').GlobalDoc;
+  type GlobalDataSidebar = import('./types').GlobalSidebar;
   type VersionTag = import('./types').VersionTag;
 
-  export type {GlobalDataVersion, GlobalDataDoc};
+  export type {GlobalDataVersion, GlobalDataDoc, GlobalDataSidebar};
 
   export type PropNavigationLink = {
     readonly title: string;

package/src/sidebars/utils.ts

@@ -136,6 +136,18 @@ export type SidebarsUtils = {
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  getFirstLink: (sidebarId: string) =>
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined;
 
   checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
@@ -264,6 +276,50 @@ Available document ids are:
     }
   }
 
+  function getFirstLink(sidebar: Sidebar):
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const item of sidebar) {
+      if (item.type === 'doc') {
+        return {
+          type: 'doc',
+          id: item.id,
+          label: item.label ?? item.id,
+        };
+      } else if (item.type === 'category') {
+        if (item.link?.type === 'doc') {
+          return {
+            type: 'doc',
+            id: item.link.id,
+            label: item.label,
+          };
+        } else if (item.link?.type === 'generated-index') {
+          return {
+            type: 'generated-index',
+            slug: item.link.slug,
+            label: item.label,
+          };
+        } else {
+          const firstSubItem = getFirstLink(item.items);
+          if (firstSubItem) {
+            return firstSubItem;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
   return {
     sidebars,
     getFirstDocIdOfFirstSidebar,
@@ -272,6 +328,7 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
+    getFirstLink: (id) => getFirstLink(sidebars[id]),
   };
 }
 

package/src/types.ts

@@ -216,6 +216,17 @@ export type GlobalVersion = {
   path: string;
   mainDocId: string; // home doc (if docs homepage configured), or first doc
   docs: GlobalDoc[];
+  sidebars?: Record<string, GlobalSidebar>;
+};
+
+export type GlobalSidebarLink = {
+  label: string;
+  path: string;
+};
+
+export type GlobalSidebar = {
+  link?: GlobalSidebarLink;
+  // ... we may add other things here later
 };
 
 export type GlobalPluginData = {