refactor(theme-classic): move all sidebar-related config under themeConfig.docs.sidebar (#7277)

packages/docusaurus-theme-classic/src/__tests__/__snapshots__/translations.test.ts.snap

@@ -133,7 +133,6 @@ exports[`translateThemeConfig returns translated themeConfig 1`] = `
     ],
     "style": "light",
   },
-  "hideableSidebar": true,
   "navbar": {
     "hideOnScroll": false,
     "items": [

packages/docusaurus-theme-classic/src/__tests__/translations.test.ts

@@ -16,7 +16,6 @@ const ThemeConfigSample: ThemeConfig = {
   docs: {
     versionPersistence: 'none',
   },
-  hideableSidebar: true,
   navbar: {
     title: 'navbar title',
     style: 'dark',

packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.ts

@@ -37,6 +37,13 @@ describe('themeConfig', () => {
         defaultLanguage: 'javascript',
         additionalLanguages: ['kotlin', 'java'],
       },
+      docs: {
+        versionPersistence: 'localStorage',
+        sidebar: {
+          hideable: true,
+          autoCollapseCategories: false,
+        },
+      },
       announcementBar: {
         id: 'supports',
         content: 'pls support',
@@ -101,6 +108,19 @@ describe('themeConfig', () => {
     });
   });
 
+  it('rejects outdated sidebar options', () => {
+    expect(() =>
+      testValidateThemeConfig({hideableSidebar: true}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable."`,
+    );
+    expect(() =>
+      testValidateThemeConfig({autoCollapseSidebarCategories: true}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories."`,
+    );
+  });
+
   it('allows possible types of navbar items', () => {
     const config = {
       navbar: {

packages/docusaurus-theme-classic/src/theme/DocSidebar/Desktop/index.tsx

@@ -18,7 +18,9 @@ import styles from './styles.module.css';
 function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
   const {
     navbar: {hideOnScroll},
-    hideableSidebar,
+    docs: {
+      sidebar: {hideable},
+    },
   } = useThemeConfig();
 
   return (
@@ -30,7 +32,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
       )}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <Content path={path} sidebar={sidebar} />
-      {hideableSidebar && <CollapseButton onClick={onCollapse} />}
+      {hideable && <CollapseButton onClick={onCollapse} />}
     </div>
   );
 }

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx

@@ -127,23 +127,21 @@ export default function DocSidebarItemCategory({
     setExpandedItem(toCollapsed ? null : index);
     setCollapsed(toCollapsed);
   }
-  const {autoCollapseSidebarCategories} = useThemeConfig();
+  const {
+    docs: {
+      sidebar: {autoCollapseCategories},
+    },
+  } = useThemeConfig();
   useEffect(() => {
     if (
       collapsible &&
       expandedItem &&
       expandedItem !== index &&
-      autoCollapseSidebarCategories
+      autoCollapseCategories
     ) {
       setCollapsed(true);
     }
-  }, [
-    collapsible,
-    expandedItem,
-    index,
-    setCollapsed,
-    autoCollapseSidebarCategories,
-  ]);
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
 
   return (
     <li

packages/docusaurus-theme-classic/src/validateThemeConfig.ts

@@ -14,11 +14,21 @@ import type {
 
 const DEFAULT_DOCS_CONFIG = {
   versionPersistence: 'localStorage',
+  sidebar: {
+    hideable: false,
+    autoCollapseCategories: false,
+  },
 };
 const DocsSchema = Joi.object({
   versionPersistence: Joi.string()
     .equal('localStorage', 'none')
     .default(DEFAULT_DOCS_CONFIG.versionPersistence),
+  sidebar: Joi.object({
+    hideable: Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.hideable),
+    autoCollapseCategories: Joi.bool().default(
+      DEFAULT_DOCS_CONFIG.sidebar.autoCollapseCategories,
+    ),
+  }).default(DEFAULT_DOCS_CONFIG.sidebar),
 }).default(DEFAULT_DOCS_CONFIG);
 
 const DEFAULT_COLOR_MODE_CONFIG = {
@@ -39,8 +49,6 @@ export const DEFAULT_CONFIG = {
     hideOnScroll: false,
     items: [],
   },
-  hideableSidebar: false,
-  autoCollapseSidebarCategories: false,
   tableOfContents: {
     minHeadingLevel: 2,
     maxHeadingLevel: 3,
@@ -381,10 +389,14 @@ export const ThemeConfigSchema = Joi.object({
   })
     .default(DEFAULT_CONFIG.prism)
     .unknown(),
-  hideableSidebar: Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
-  autoCollapseSidebarCategories: Joi.bool().default(
-    DEFAULT_CONFIG.autoCollapseSidebarCategories,
-  ),
+  hideableSidebar: Joi.forbidden().messages({
+    'any.unknown':
+      'themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable.',
+  }),
+  autoCollapseSidebarCategories: Joi.forbidden().messages({
+    'any.unknown':
+      'themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories.',
+  }),
   sidebarCollapsible: Joi.forbidden().messages({
     'any.unknown':
       'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',

packages/docusaurus-theme-common/src/utils/useThemeConfig.ts

@@ -104,6 +104,10 @@ export type TableOfContents = {
 export type ThemeConfig = {
   docs: {
     versionPersistence: DocsVersionPersistence;
+    sidebar: {
+      hideable: boolean;
+      autoCollapseCategories: boolean;
+    };
   };
 
   // TODO we should complete this theme config type over time
@@ -116,11 +120,8 @@ export type ThemeConfig = {
   announcementBar?: AnnouncementBarConfig;
   prism: PrismConfig;
   footer?: Footer;
-  hideableSidebar: boolean;
-  autoCollapseSidebarCategories: boolean;
   image?: string;
   metadata: Array<{[key: string]: string}>;
-  sidebarCollapsible: boolean;
   tableOfContents: TableOfContents;
 };
 

website/docs/api/docusaurus.config.js.md

@@ -286,8 +286,12 @@ Example:
 ```js title="docusaurus.config.js"
 module.exports = {
   themeConfig: {
-    hideableSidebar: false,
-    autoCollapseSidebarCategories: false,
+    docs: {
+      sidebar: {
+        hideable: false,
+        autoCollapseCategories: false,
+      },
+    },
     colorMode: {
       defaultMode: 'light',
       disableSwitch: false,

website/docs/guides/docs/sidebar/index.md

@@ -121,13 +121,17 @@ type SidebarsFile = {
 
 ### Hideable sidebar {#hideable-sidebar}
 
-By enabling the `themeConfig.hideableSidebar` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
+By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
 
 ```js title="docusaurus.config.js"
 module.exports = {
   themeConfig: {
     // highlight-start
-    hideableSidebar: true,
+    docs: {
+      sidebar: {
+        hideable: true,
+      },
+    },
     // highlight-end
   },
 };
@@ -135,13 +139,18 @@ module.exports = {
 
 ### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}
 
-The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
+The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
 
 ```js title="docusaurus.config.js"
 module.exports = {
   themeConfig: {
-    // highlight-next-line
-    autoCollapseSidebarCategories: true,
+    // highlight-start
+    docs: {
+      sidebar: {
+        autoCollapseCategories: true,
+      },
+    },
+    // highlight-end
   },
 };
 ```

website/docusaurus.config.js

@@ -357,8 +357,12 @@ const config = {
       liveCodeBlock: {
         playgroundPosition: 'bottom',
       },
-      hideableSidebar: true,
-      autoCollapseSidebarCategories: true,
+      docs: {
+        sidebar: {
+          hideable: true,
+          autoCollapseCategories: true,
+        },
+      },
       colorMode: {
         defaultMode: 'light',
         disableSwitch: false,