@docusaurus/theme-classic 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

package/lib-next/validateThemeConfig.js

@@ -4,9 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
-const {Joi, URISchema} = require('@docusaurus/utils-validation');
-
+import {Joi, URISchema} from '@docusaurus/utils-validation';
 const DEFAULT_DOCS_CONFIG = {
   versionPersistence: 'localStorage',
 };
@@ -15,7 +13,6 @@ const DocsSchema = Joi.object({
     .equal('localStorage', 'none')
     .default(DEFAULT_DOCS_CONFIG.versionPersistence),
 }).default(DEFAULT_DOCS_CONFIG);
-
 const DEFAULT_COLOR_MODE_CONFIG = {
   defaultMode: 'light',
   disableSwitch: false,
@@ -27,7 +24,6 @@ const DEFAULT_COLOR_MODE_CONFIG = {
     lightIconStyle: {},
   },
 };
-
 const DEFAULT_CONFIG = {
   colorMode: DEFAULT_COLOR_MODE_CONFIG,
   docs: DEFAULT_DOCS_CONFIG,
@@ -40,19 +36,19 @@ const DEFAULT_CONFIG = {
     items: [],
   },
   hideableSidebar: false,
+  tableOfContents: {
+    minHeadingLevel: 2,
+    maxHeadingLevel: 3,
+  },
 };
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
-
 const NavbarItemPosition = Joi.string().equal('left', 'right').default('left');
-
 const NavbarItemBaseSchema = Joi.object({
   label: Joi.string(),
   className: Joi.string(),
-})
-  // We allow any unknown attributes on the links
+}) // We allow any unknown attributes on the links
   // (users may need additional attributes like target, aria-role, data-customAttribute...)
   .unknown();
-
 const DefaultNavbarItemSchema = NavbarItemBaseSchema.append({
   to: Joi.string(),
   href: URISchema,
@@ -68,18 +64,15 @@ const DefaultNavbarItemSchema = NavbarItemBaseSchema.append({
   .messages({
     'object.xor': 'One and only one between "to" and "href" should be provided',
   });
-
 const DocsVersionNavbarItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('docsVersion').required(),
   to: Joi.string(),
   docsPluginId: Joi.string(),
 });
-
 const DocItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('doc').required(),
   docId: Joi.string().required(),
   docsPluginId: Joi.string(),
-  activeSidebarClassName: Joi.string().default('navbar__link--active'),
 });
 
 const itemWithType = (type) => {
@@ -96,7 +89,7 @@ const itemWithType = (type) => {
 
 const DropdownSubitemSchema = Joi.object({
   position: Joi.forbidden(),
-}).when({
+}).when('.', {
   switch: [
     {
       is: itemWithType('docsVersion'),
@@ -126,11 +119,9 @@ const DropdownSubitemSchema = Joi.object({
     'any.unknown': 'Bad navbar item type {.type}',
   }),
 });
-
 const DropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   items: Joi.array().items(DropdownSubitemSchema).required(),
 });
-
 const DocsVersionDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('docsVersionDropdown').required(),
   docsPluginId: Joi.string(),
@@ -138,20 +129,17 @@ const DocsVersionDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
 });
-
 const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('localeDropdown').required(),
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
 });
-
 const SearchItemSchema = Joi.object({
   type: Joi.string().equal('search').required(),
 });
-
 const NavbarItemSchema = Joi.object({
   position: NavbarItemPosition,
-}).when({
+}).when('.', {
   switch: [
     {
       is: itemWithType('docsVersion'),
@@ -179,7 +167,7 @@ const NavbarItemSchema = Joi.object({
     },
     {
       is: itemWithType(undefined),
-      then: Joi.object().when({
+      then: Joi.object().when('.', {
         // Dropdown item can be specified without type field
         is: Joi.object({
           items: Joi.array().required(),
@@ -193,7 +181,6 @@ const NavbarItemSchema = Joi.object({
     'any.unknown': 'Bad navbar item type {.type}',
   }),
 });
-
 const ColorModeSchema = Joi.object({
   defaultMode: Joi.string()
     .equal('dark', 'light')
@@ -216,9 +203,8 @@ const ColorModeSchema = Joi.object({
       DEFAULT_COLOR_MODE_CONFIG.switchConfig.lightIconStyle,
     ),
   }).default(DEFAULT_COLOR_MODE_CONFIG.switchConfig),
-}).default(DEFAULT_COLOR_MODE_CONFIG);
+}).default(DEFAULT_COLOR_MODE_CONFIG); // schema can probably be improved
 
-// schema can probably be improved
 const HtmlMetadataSchema = Joi.object({
   id: Joi.string(),
   name: Joi.string(),
@@ -226,7 +212,6 @@ const HtmlMetadataSchema = Joi.object({
   content: Joi.string(),
   itemprop: Joi.string(),
 }).unknown();
-
 const FooterLinkItemSchema = Joi.object({
   to: Joi.string(),
   href: URISchema,
@@ -236,23 +221,20 @@ const FooterLinkItemSchema = Joi.object({
   .xor('to', 'href', 'html')
   .with('to', 'label')
   .with('href', 'label')
-  .nand('html', 'label')
-  // We allow any unknown attributes on the links
+  .nand('html', 'label') // We allow any unknown attributes on the links
   // (users may need additional attributes like target, aria-role, data-customAttribute...)
   .unknown();
-
 const CustomCssSchema = Joi.alternatives()
   .try(Joi.array().items(Joi.string().required()), Joi.string().required())
   .optional();
-
 const ThemeConfigSchema = Joi.object({
   // TODO temporary (@alpha-58)
-  disableDarkMode: Joi.any().forbidden(false).messages({
+  disableDarkMode: Joi.any().forbidden().messages({
     'any.unknown':
       'disableDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.disableSwitch = true',
   }),
   // TODO temporary (@alpha-58)
-  defaultDarkMode: Joi.any().forbidden(false).messages({
+  defaultDarkMode: Joi.any().forbidden().messages({
     'any.unknown':
       'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
   }),
@@ -265,7 +247,7 @@ const ThemeConfigSchema = Joi.object({
     .default(DEFAULT_CONFIG.metadatas),
   announcementBar: Joi.object({
     id: Joi.string().default('announcement-bar'),
-    content: Joi.string(),
+    content: Joi.string().required(),
     backgroundColor: Joi.string(),
     textColor: Joi.string(),
     isCloseable: Joi.bool().default(true),
@@ -286,6 +268,8 @@ const ThemeConfigSchema = Joi.object({
       alt: Joi.string().allow(''),
       src: Joi.string().required(),
       srcDark: Joi.string(),
+      width: Joi.alternatives().try(Joi.string(), Joi.number()),
+      height: Joi.alternatives().try(Joi.string(), Joi.number()),
       href: Joi.string(),
       target: Joi.string(),
     }),
@@ -296,6 +280,9 @@ const ThemeConfigSchema = Joi.object({
       alt: Joi.string().allow(''),
       src: Joi.string(),
       srcDark: Joi.string(),
+      // TODO infer this from reading the image
+      width: Joi.alternatives().try(Joi.string(), Joi.number()),
+      height: Joi.alternatives().try(Joi.string(), Joi.number()),
       href: Joi.string(),
     }),
     copyright: Joi.string(),
@@ -329,9 +316,26 @@ const ThemeConfigSchema = Joi.object({
     'any.unknown':
       'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',
   }),
+  tableOfContents: Joi.object({
+    minHeadingLevel: Joi.number()
+      .default(DEFAULT_CONFIG.tableOfContents.minHeadingLevel)
+      .when('maxHeadingLevel', {
+        is: Joi.exist(),
+        then: Joi.number()
+          .integer()
+          .min(2)
+          .max(6)
+          .max(Joi.ref('maxHeadingLevel')),
+        otherwise: Joi.number().integer().min(2).max(6),
+      }),
+    maxHeadingLevel: Joi.number()
+      .integer()
+      .min(2)
+      .max(6)
+      .default(DEFAULT_CONFIG.tableOfContents.maxHeadingLevel),
+  }).default(DEFAULT_CONFIG.tableOfContents),
 });
-exports.ThemeConfigSchema = ThemeConfigSchema;
-
-exports.validateThemeConfig = ({validate, themeConfig}) => {
+export {ThemeConfigSchema};
+export function validateThemeConfig({validate, themeConfig}) {
   return validate(ThemeConfigSchema, themeConfig);
-};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "2.0.0-beta.8e9b829d9",
+  "version": "2.0.0-beta.9",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/types.d.ts",
@@ -23,42 +23,46 @@
     "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/theme-common": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/types": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/utils": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/utils-common": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/utils-validation": "2.0.0-beta.8e9b829d9",
+    "@docusaurus/core": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.9",
+    "@docusaurus/theme-common": "2.0.0-beta.9",
+    "@docusaurus/types": "2.0.0-beta.9",
+    "@docusaurus/utils": "2.0.0-beta.9",
+    "@docusaurus/utils-common": "2.0.0-beta.9",
+    "@docusaurus/utils-validation": "2.0.0-beta.9",
     "@mdx-js/mdx": "^1.6.21",
     "@mdx-js/react": "^1.6.21",
-    "chalk": "^4.1.1",
+    "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
     "fs-extra": "^10.0.0",
     "globby": "^11.0.2",
-    "infima": "0.2.0-alpha.29",
+    "infima": "0.2.0-alpha.34",
     "lodash": "^4.17.20",
-    "parse-numeric-range": "^1.2.0",
-    "postcss": "^8.2.15",
+    "parse-numeric-range": "^1.3.0",
+    "postcss": "^8.3.7",
     "prism-react-renderer": "^1.2.1",
     "prismjs": "^1.23.0",
     "prop-types": "^15.7.2",
     "react-router-dom": "^5.2.0",
-    "rtlcss": "^3.1.2"
+    "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.8e9b829d9",
-    "@types/parse-numeric-range": "^0.0.1"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.9",
+    "@types/mdx-js__react": "^1.5.4",
+    "@types/parse-numeric-range": "^0.0.1",
+    "@types/rtlcss": "^3.1.1",
+    "react-test-renderer": "^17.0.2",
+    "utility-types": "^3.10.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "cb79fda03ac12835068842a7e0a86f610974eae2"
+  "gitHead": "8a491fc29ad002f90e97f5b5fe4178ac8fa0c4d7"
 }

package/src/__tests__/validateThemeConfig.test.js

@@ -91,6 +91,10 @@ describe('themeConfig', () => {
         },
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
       },
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 5,
+      },
     };
     expect(testValidateThemeConfig(userConfig)).toEqual({
       ...DEFAULT_CONFIG,
@@ -108,7 +112,6 @@ describe('themeConfig', () => {
             position: 'left',
             docId: 'intro',
             label: 'Introduction',
-            activeSidebarClassName: 'custom-class',
           },
           // Regular link
           {
@@ -142,7 +145,6 @@ describe('themeConfig', () => {
             items: [
               {
                 type: 'doc',
-                activeSidebarClassName: 'custom-class',
                 docId: 'npm',
                 label: 'NPM',
               },
@@ -159,8 +161,7 @@ describe('themeConfig', () => {
             dropdownActiveClassDisabled: true,
             dropdownItemsBefore: [
               {
-                href:
-                  'https://www.npmjs.com/package/docusaurus?activeTab=versions',
+                href: 'https://www.npmjs.com/package/docusaurus?activeTab=versions',
                 label: 'Versions on npm',
                 className: 'npm-styled',
                 target: '_self',
@@ -344,6 +345,27 @@ describe('themeConfig', () => {
     });
   });
 
+  test('should allow width and height specification for logo ', () => {
+    const altTagConfig = {
+      navbar: {
+        logo: {
+          alt: '',
+          src: '/arbitrary-logo.png',
+          srcDark: '/arbitrary-dark-logo.png',
+          width: '20px',
+          height: '20%',
+        },
+      },
+    };
+    expect(testValidateThemeConfig(altTagConfig)).toEqual({
+      ...DEFAULT_CONFIG,
+      navbar: {
+        ...DEFAULT_CONFIG.navbar,
+        ...altTagConfig.navbar,
+      },
+    });
+  });
+
   test('should accept valid prism config', () => {
     const prismConfig = {
       prism: {
@@ -455,3 +477,131 @@ describe('themeConfig', () => {
     });
   });
 });
+
+describe('themeConfig tableOfContents', () => {
+  test('toc undefined', () => {
+    const tableOfContents = undefined;
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc empty', () => {
+    const tableOfContents = {};
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with min', () => {
+    const tableOfContents = {
+      minHeadingLevel: 3,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: 3,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with max', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 5,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: 5,
+      },
+    });
+  });
+
+  test('toc with min 2.5', () => {
+    const tableOfContents = {
+      minHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with max 2.5', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with min 1', () => {
+    const tableOfContents = {
+      minHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with min 7', () => {
+    const tableOfContents = {
+      minHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+
+  test('toc with max 1', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with max 7', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be less than or equal to 6"`,
+    );
+  });
+
+  test('toc with bad min 5 + max 3', () => {
+    const tableOfContents = {
+      minHeadingLevel: 5,
+      maxHeadingLevel: 3,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+});

package/src/index.ts

@@ -9,12 +9,11 @@ import {DocusaurusContext, Plugin} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
-import Module from 'module';
-import type {AcceptedPlugin, Result, Plugin as PostCssPlugin} from 'postcss';
+import {createRequire} from 'module';
+import type {AcceptedPlugin, Plugin as PostCssPlugin} from 'postcss';
 import rtlcss from 'rtlcss';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/utils';
 
-const createRequire = Module.createRequire || Module.createRequireFromPath;
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
@@ -25,7 +24,10 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 const ThemeStorageKey = 'theme';
-const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
+const noFlashColorMode = ({
+  defaultMode,
+  respectPrefersColorScheme,
+}: ThemeConfig['colorMode']) => {
   return `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
@@ -83,14 +85,14 @@ const AnnouncementBarInlineJavaScript = `
   document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
 })();`;
 
-function getInfimaCSSFile(direction) {
+function getInfimaCSSFile(direction: string) {
   return `infima/dist/css/default/default${
     direction === 'rtl' ? '-rtl' : ''
   }.css`;
 }
 
-type PluginOptions = {
-  customCss?: string;
+export type PluginOptions = {
+  customCss?: string | string[];
 };
 
 export default function docusaurusThemeClassic(
@@ -183,13 +185,13 @@ export default function docusaurusThemeClassic(
         const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
         const plugin: PostCssPlugin = {
           postcssPlugin: 'RtlCssPlugin',
-          prepare: (result: Result) => {
+          prepare: (result) => {
             const file = result.root?.source?.input?.file;
             // Skip Infima as we are using the its RTL version.
             if (file === resolvedInfimaFile) {
               return {};
             }
-            return rtlcss(result.root);
+            return rtlcss(result.root as unknown as rtlcss.ConfigOptions);
           },
         };
         postCssOptions.plugins.push(plugin);

package/src/theme/AnnouncementBar/index.tsx

@@ -9,32 +9,28 @@ import React from 'react';
 import clsx from 'clsx';
 import {useThemeConfig, useAnnouncementBar} from '@docusaurus/theme-common';
 import {translate} from '@docusaurus/Translate';
+import IconClose from '@theme/IconClose';
 
 import styles from './styles.module.css';
 
 function AnnouncementBar(): JSX.Element | null {
-  const {isClosed, close} = useAnnouncementBar();
+  const {isActive, close} = useAnnouncementBar();
   const {announcementBar} = useThemeConfig();
 
-  if (!announcementBar) {
+  if (!isActive) {
     return null;
   }
 
-  const {content, backgroundColor, textColor, isCloseable} = announcementBar;
-
-  if (!content || (isCloseable && isClosed)) {
-    return null;
-  }
+  const {content, backgroundColor, textColor, isCloseable} = announcementBar!;
 
   return (
     <div
       className={styles.announcementBar}
       style={{backgroundColor, color: textColor}}
       role="banner">
+      {isCloseable && <div className={styles.announcementBarPlaceholder} />}
       <div
-        className={clsx(styles.announcementBarContent, {
-          [styles.announcementBarCloseable]: isCloseable,
-        })}
+        className={styles.announcementBarContent}
         // Developer provided the HTML, so assume it's safe.
         // eslint-disable-next-line react/no-danger
         dangerouslySetInnerHTML={{__html: content}}
@@ -42,14 +38,14 @@ function AnnouncementBar(): JSX.Element | null {
       {isCloseable ? (
         <button
           type="button"
-          className={clsx(styles.announcementBarClose, 'clean-btn')}
+          className={clsx('clean-btn close', styles.announcementBarClose)}
           onClick={close}
           aria-label={translate({
             id: 'theme.AnnouncementBar.closeButtonAriaLabel',
             message: 'Close',
             description: 'The ARIA label for close button of announcement bar',
           })}>
-          <span aria-hidden="true">×</span>
+          <IconClose width={14} height={14} strokeWidth={3.1} />
         </button>
       ) : null}
     </div>