@docusaurus/plugin-content-docs 0.0.0-4439 → 0.0.0-4445

package/lib/docFrontMatter.js

@@ -24,6 +24,7 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
     sidebar_position: utils_validation_1.JoiFrontMatter.number(),
     sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
     tags: utils_validation_1.FrontMatterTagsSchema,
     pagination_label: utils_validation_1.JoiFrontMatter.string(),
     custom_edit_url: utils_validation_1.URISchema.allow('', null),

package/lib/docs.js

@@ -181,7 +181,7 @@ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
     sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
     // Add sidebar/next/previous to the docs
     function addNavData(doc) {
-        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id);
+        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id, doc.frontMatter.displayed_sidebar);
         const toNavigationLinkByDocId = (docId, type) => {
             if (!docId) {
                 return undefined;

package/lib/sidebars/utils.d.ts

@@ -24,7 +24,7 @@ export declare type SidebarsUtils = {
     sidebars: Sidebars;
     getFirstDocIdOfFirstSidebar: () => string | undefined;
     getSidebarNameByDocId: (docId: string) => string | undefined;
-    getDocNavigation: (unversionedId: string, versionedId: string) => SidebarNavigation;
+    getDocNavigation: (unversionedId: string, versionedId: string, displayedSidebar: string | null | undefined) => SidebarNavigation;
     getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
     getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
     getFirstLink: (sidebarId: string) => {

package/lib/sidebars/utils.js

@@ -104,15 +104,20 @@ function createSidebarsUtils(sidebars) {
             next: undefined,
         };
     }
-    function getDocNavigation(unversionedId, versionedId) {
+    function getDocNavigation(unversionedId, versionedId, displayedSidebar) {
         // TODO legacy id retro-compatibility!
         let docId = unversionedId;
-        let sidebarName = getSidebarNameByDocId(docId);
-        if (!sidebarName) {
+        let sidebarName = displayedSidebar === undefined
+            ? getSidebarNameByDocId(docId)
+            : displayedSidebar;
+        if (sidebarName === undefined) {
             docId = versionedId;
             sidebarName = getSidebarNameByDocId(docId);
         }
         if (sidebarName) {
+            if (!sidebarNameToNavigationItems[sidebarName]) {
+                throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
+            }
             const navigationItems = sidebarNameToNavigationItems[sidebarName];
             const currentItemIndex = navigationItems.findIndex((item) => {
                 if (item.type === 'doc') {
@@ -123,6 +128,9 @@ function createSidebarsUtils(sidebars) {
                 }
                 return false;
             });
+            if (currentItemIndex === -1) {
+                return { sidebarName, next: undefined, previous: undefined };
+            }
             const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
             return { sidebarName, previous, next };
         }

package/lib/sidebars/validation.js

@@ -9,6 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateCategoryMetadataFile = exports.validateSidebars = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("./utils");
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type in normalization
 const sidebarItemBaseSchema = utils_validation_1.Joi.object({
     className: utils_validation_1.Joi.string(),
     customProps: utils_validation_1.Joi.object().unknown(),

package/lib/types.d.ts

@@ -51,6 +51,7 @@ export declare type DocFrontMatter = {
     sidebar_label?: string;
     sidebar_position?: number;
     sidebar_class_name?: string;
+    displayed_sidebar?: string | null;
     pagination_label?: string;
     custom_edit_url?: string | null;
     parse_number_prefixes?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4439",
+  "version": "0.0.0-4445",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -22,11 +22,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4439",
-    "@docusaurus/logger": "0.0.0-4439",
-    "@docusaurus/mdx-loader": "0.0.0-4439",
-    "@docusaurus/utils": "0.0.0-4439",
-    "@docusaurus/utils-validation": "0.0.0-4439",
+    "@docusaurus/core": "0.0.0-4445",
+    "@docusaurus/logger": "0.0.0-4445",
+    "@docusaurus/mdx-loader": "0.0.0-4445",
+    "@docusaurus/utils": "0.0.0-4445",
+    "@docusaurus/utils-validation": "0.0.0-4445",
     "combine-promises": "^1.1.0",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
@@ -42,8 +42,8 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4439",
-    "@docusaurus/types": "0.0.0-4439",
+    "@docusaurus/module-type-aliases": "0.0.0-4445",
+    "@docusaurus/types": "0.0.0-4445",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "b7f060678d66a34460788300fc57ade9558e3807"
+  "gitHead": "58486dd4a53a96914969980a79545119b51247ea"
 }

package/src/docFrontMatter.ts

@@ -30,6 +30,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),
+  displayed_sidebar: Joi.string().allow(null),
   tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),

package/src/docs.ts

@@ -295,6 +295,7 @@ export function addDocNavigation(
     const navigation = sidebarsUtils.getDocNavigation(
       doc.unversionedId,
       doc.id,
+      doc.frontMatter.displayed_sidebar,
     );
 
     const toNavigationLinkByDocId = (

package/src/sidebars/utils.ts

@@ -131,6 +131,7 @@ export type SidebarsUtils = {
   getDocNavigation: (
     unversionedId: string,
     versionedId: string,
+    displayedSidebar: string | null | undefined,
   ) => SidebarNavigation;
   getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
   getCategoryGeneratedIndexNavigation: (
@@ -182,16 +183,25 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
   function getDocNavigation(
     unversionedId: string,
     versionedId: string,
+    displayedSidebar: string | null | undefined,
   ): SidebarNavigation {
     // TODO legacy id retro-compatibility!
     let docId = unversionedId;
-    let sidebarName = getSidebarNameByDocId(docId);
-    if (!sidebarName) {
+    let sidebarName =
+      displayedSidebar === undefined
+        ? getSidebarNameByDocId(docId)
+        : displayedSidebar;
+    if (sidebarName === undefined) {
       docId = versionedId;
       sidebarName = getSidebarNameByDocId(docId);
     }
 
     if (sidebarName) {
+      if (!sidebarNameToNavigationItems[sidebarName]) {
+        throw new Error(
+          `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
+        );
+      }
       const navigationItems = sidebarNameToNavigationItems[sidebarName];
       const currentItemIndex = navigationItems.findIndex((item) => {
         if (item.type === 'doc') {
@@ -202,6 +212,9 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
         }
         return false;
       });
+      if (currentItemIndex === -1) {
+        return {sidebarName, next: undefined, previous: undefined};
+      }
 
       const {previous, next} = getElementsAround(
         navigationItems,

package/src/sidebars/validation.ts

@@ -22,6 +22,9 @@ import type {
 import {isCategoriesShorthand} from './utils';
 import type {CategoryMetadataFile} from './generator';
 
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type in normalization
+
 const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
   className: Joi.string(),
   customProps: Joi.object().unknown(),

package/src/types.ts

@@ -66,6 +66,7 @@ export type DocFrontMatter = {
   sidebar_label?: string;
   sidebar_position?: number;
   sidebar_class_name?: string;
+  displayed_sidebar?: string | null;
   pagination_label?: string;
   custom_edit_url?: string | null;
   parse_number_prefixes?: boolean;