@docusaurus/theme-classic 0.0.0-4875 → 0.0.0-4879

package/lib/getSwizzleConfig.js

@@ -33,7 +33,7 @@ function getSwizzleConfig() {
       DocSidebar: {
         actions: {
           eject: 'unsafe',
-          // too much technical code in sidebar, not very safe atm
+          // Too much technical code in sidebar, not very safe atm
           wrap: 'safe'
         },
         description: 'The sidebar component on docs pages'
@@ -226,7 +226,7 @@ function getSwizzleConfig() {
       'prism-include-languages': {
         actions: {
           eject: 'safe',
-          wrap: 'forbidden' // not a component!
+          wrap: 'forbidden' // Not a component!
 
         },
         description: 'The Prism languages to include for code block syntax highlighting. Meant to be ejected.'

package/lib/theme-classic.d.ts

@@ -1022,8 +1022,8 @@ declare module '@theme/TOCItems' {
 declare module '@theme/TOC' {
   import type {TOCItem} from '@docusaurus/types';
 
-  // minHeadingLevel only exists as a per-doc option, and won't have a default
-  // set by Joi. See TOC, TOCInline, TOCCollapsible for examples
+  // `minHeadingLevel` only comes from doc/post front matter, and won't have a
+  // default set by Joi. See TOC, TOCInline, TOCCollapsible for examples.
   export interface Props {
     readonly toc: readonly TOCItem[];
     readonly minHeadingLevel?: number;

package/lib/validateThemeConfig.js

@@ -98,7 +98,7 @@ const HtmlNavbarItemSchema = _utilsValidation.Joi.object({
 });
 
 const itemWithType = type => {
-  // because equal(undefined) is not supported :/
+  // Because equal(undefined) is not supported :/
   const typeSchema = type ? _utilsValidation.Joi.string().required().equal(type) : _utilsValidation.Joi.string().forbidden();
   return _utilsValidation.Joi.object({
     type: typeSchema
@@ -204,8 +204,7 @@ const ColorModeSchema = _utilsValidation.Joi.object({
   switchConfig: _utilsValidation.Joi.any().forbidden().messages({
     'any.unknown': 'colorMode.switchConfig is deprecated. If you want to customize the icons for light and dark mode, swizzle IconLightMode, IconDarkMode, or ColorModeToggle instead.'
   })
-}).default(DEFAULT_COLOR_MODE_CONFIG); // schema can probably be improved
-
+}).default(DEFAULT_COLOR_MODE_CONFIG);
 
 const HtmlMetadataSchema = _utilsValidation.Joi.object({
   id: _utilsValidation.Joi.string(),

package/lib-next/theme/DocSidebarItem/Category.js

@@ -92,8 +92,8 @@ export default function DocSidebarItemCategory({
   const isActive = isActiveSidebarItem(item, activePath);
   const isCurrentPage = isSamePath(href, activePath);
   const {collapsed, setCollapsed} = useCollapsible({
-    // active categories are always initialized as expanded
-    // the default (item.collapsed) is only used for non-active categories
+    // Active categories are always initialized as expanded. The default
+    // (`item.collapsed`) is only used for non-active categories.
     initialState: () => {
       if (!collapsible) {
         return false;

package/lib-next/theme/DocSidebarItems/index.js

@@ -14,12 +14,7 @@ function DocSidebarItems({items, ...props}) {
   return (
     <DocSidebarItemsExpandedStateProvider>
       {items.map((item, index) => (
-        <DocSidebarItem
-          key={index} // sidebar is static, the index does not change
-          item={item}
-          index={index}
-          {...props}
-        />
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
       ))}
     </DocSidebarItemsExpandedStateProvider>
   );

package/lib-next/theme/DocVersionBanner/index.js

@@ -101,8 +101,8 @@ function DocVersionBannerEnabled({className, versionMetadata}) {
 
   const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
   const {latestDocSuggestion, latestVersionSuggestion} =
-    useDocVersionSuggestions(pluginId); // try to link to same doc in latest version (not always possible)
-  // fallback to main doc of latest version
+    useDocVersionSuggestions(pluginId); // Try to link to same doc in latest version (not always possible), falling
+  // back to main doc of latest version
 
   const latestVersionSuggestedDoc =
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);

package/lib-next/theme/Heading/index.js

@@ -9,14 +9,13 @@ import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import styles from './styles.module.css';
-
-function AnchorHeading({as: As, id, ...props}) {
+export default function Heading({as: As, id, ...props}) {
   const {
     navbar: {hideOnScroll},
-  } = useThemeConfig();
+  } = useThemeConfig(); // H1 headings do not need an id because they don't appear in the TOC.
 
-  if (!id) {
-    return <As {...props} />;
+  if (As === 'h1' || !id) {
+    return <As {...props} id={undefined} />;
   }
 
   return (
@@ -43,18 +42,3 @@ function AnchorHeading({as: As, id, ...props}) {
     </As>
   );
 }
-
-export default function Heading({as, ...props}) {
-  if (as === 'h1') {
-    return (
-      <h1
-        {...props}
-        id={undefined} // h1 headings do not need an id because they don't appear in the TOC
-      >
-        {props.children}
-      </h1>
-    );
-  }
-
-  return <AnchorHeading as={as} {...props} />;
-}

package/lib-next/theme/Layout/index.js

@@ -24,7 +24,7 @@ export default function Layout(props) {
     children,
     noFooter,
     wrapperClassName,
-    // not really layout-related, but kept for convenience/retro-compatibility
+    // Not really layout-related, but kept for convenience/retro-compatibility
     title,
     description,
   } = props;

package/lib-next/theme/SiteMetadata/index.js

@@ -101,15 +101,16 @@ export default function SiteMetadata() {
 
       <SearchMetadata tag={DEFAULT_SEARCH_TAG} locale={currentLocale} />
 
-      <Head // it's important to have an additional <Head> element here,
-      // as it allows react-helmet to override values set in previous <Head>
-      // ie we can override default metadata such as "twitter:card"
-      // In same Head, the same meta would appear twice instead of overriding
-      // See react-helmet doc
-      >
+      {/*
+       It's important to have an additional <Head> element here, as it allows
+       react-helmet to override default metadata values set in previous <Head>
+       like "twitter:card". In same Head, the same meta would appear twice
+       instead of overriding.
+      */}
+      <Head>
         {/* Yes, "metadatum" is the grammatically correct term */}
         {metadata.map((metadatum, i) => (
-          <meta key={`metadata_${i}`} {...metadatum} />
+          <meta key={i} {...metadatum} />
         ))}
       </Head>
     </>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-4875",
+  "version": "0.0.0-4879",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -21,15 +21,15 @@
     "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4875",
-    "@docusaurus/plugin-content-blog": "0.0.0-4875",
-    "@docusaurus/plugin-content-docs": "0.0.0-4875",
-    "@docusaurus/plugin-content-pages": "0.0.0-4875",
-    "@docusaurus/theme-common": "0.0.0-4875",
-    "@docusaurus/theme-translations": "0.0.0-4875",
-    "@docusaurus/utils": "0.0.0-4875",
-    "@docusaurus/utils-common": "0.0.0-4875",
-    "@docusaurus/utils-validation": "0.0.0-4875",
+    "@docusaurus/core": "0.0.0-4879",
+    "@docusaurus/plugin-content-blog": "0.0.0-4879",
+    "@docusaurus/plugin-content-docs": "0.0.0-4879",
+    "@docusaurus/plugin-content-pages": "0.0.0-4879",
+    "@docusaurus/theme-common": "0.0.0-4879",
+    "@docusaurus/theme-translations": "0.0.0-4879",
+    "@docusaurus/utils": "0.0.0-4879",
+    "@docusaurus/utils-common": "0.0.0-4879",
+    "@docusaurus/utils-validation": "0.0.0-4879",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
@@ -45,13 +45,13 @@
     "@babel/cli": "^7.17.6",
     "@babel/core": "^7.17.9",
     "@babel/preset-typescript": "^7.16.7",
-    "@docusaurus/module-type-aliases": "0.0.0-4875",
-    "@docusaurus/types": "0.0.0-4875",
+    "@docusaurus/module-type-aliases": "0.0.0-4879",
+    "@docusaurus/types": "0.0.0-4879",
     "@types/mdx-js__react": "^1.5.5",
     "@types/prismjs": "^1.26.0",
-    "@types/rtlcss": "^3.1.3",
+    "@types/rtlcss": "^3.1.4",
     "cross-env": "^7.0.3",
-    "fs-extra": "^10.0.1",
+    "fs-extra": "^10.1.0",
     "react-test-renderer": "^17.0.2",
     "utility-types": "^3.10.0"
   },
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ee48d072632c7eb6d03da4acf5800f8d42eee680"
+  "gitHead": "0ebf7473396171d10b7c91bc3f33cdf16863ee5c"
 }

package/src/getSwizzleConfig.ts

@@ -30,7 +30,7 @@ export default function getSwizzleConfig(): SwizzleConfig {
       },
       DocSidebar: {
         actions: {
-          eject: 'unsafe', // too much technical code in sidebar, not very safe atm
+          eject: 'unsafe', // Too much technical code in sidebar, not very safe atm
           wrap: 'safe',
         },
         description: 'The sidebar component on docs pages',
@@ -234,7 +234,7 @@ export default function getSwizzleConfig(): SwizzleConfig {
       'prism-include-languages': {
         actions: {
           eject: 'safe',
-          wrap: 'forbidden', // not a component!
+          wrap: 'forbidden', // Not a component!
         },
         description:
           'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',

package/src/theme/DocSidebarItem/Category.tsx

@@ -111,8 +111,8 @@ export default function DocSidebarItemCategory({
   const isCurrentPage = isSamePath(href, activePath);
 
   const {collapsed, setCollapsed} = useCollapsible({
-    // active categories are always initialized as expanded
-    // the default (item.collapsed) is only used for non-active categories
+    // Active categories are always initialized as expanded. The default
+    // (`item.collapsed`) is only used for non-active categories.
     initialState: () => {
       if (!collapsible) {
         return false;

package/src/theme/DocSidebarItems/index.tsx

@@ -17,12 +17,7 @@ function DocSidebarItems({items, ...props}: Props): JSX.Element {
   return (
     <DocSidebarItemsExpandedStateProvider>
       {items.map((item, index) => (
-        <DocSidebarItem
-          key={index} // sidebar is static, the index does not change
-          item={item}
-          index={index}
-          {...props}
-        />
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
       ))}
     </DocSidebarItemsExpandedStateProvider>
   );

package/src/theme/DocVersionBanner/index.tsx

@@ -136,8 +136,8 @@ function DocVersionBannerEnabled({
   const {latestDocSuggestion, latestVersionSuggestion} =
     useDocVersionSuggestions(pluginId);
 
-  // try to link to same doc in latest version (not always possible)
-  // fallback to main doc of latest version
+  // Try to link to same doc in latest version (not always possible), falling
+  // back to main doc of latest version
   const latestVersionSuggestedDoc =
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
 

package/src/theme/Heading/index.tsx

@@ -13,13 +13,13 @@ import {useThemeConfig} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
 
-function AnchorHeading({as: As, id, ...props}: Props) {
+export default function Heading({as: As, id, ...props}: Props): JSX.Element {
   const {
     navbar: {hideOnScroll},
   } = useThemeConfig();
-
-  if (!id) {
-    return <As {...props} />;
+  // H1 headings do not need an id because they don't appear in the TOC.
+  if (As === 'h1' || !id) {
+    return <As {...props} id={undefined} />;
   }
 
   return (
@@ -46,17 +46,3 @@ function AnchorHeading({as: As, id, ...props}: Props) {
     </As>
   );
 }
-
-export default function Heading({as, ...props}: Props): JSX.Element {
-  if (as === 'h1') {
-    return (
-      <h1
-        {...props}
-        id={undefined} // h1 headings do not need an id because they don't appear in the TOC
-      >
-        {props.children}
-      </h1>
-    );
-  }
-  return <AnchorHeading as={as} {...props} />;
-}

package/src/theme/Layout/index.tsx

@@ -27,7 +27,7 @@ export default function Layout(props: Props): JSX.Element {
     children,
     noFooter,
     wrapperClassName,
-    // not really layout-related, but kept for convenience/retro-compatibility
+    // Not really layout-related, but kept for convenience/retro-compatibility
     title,
     description,
   } = props;

package/src/theme/SiteMetadata/index.tsx

@@ -109,16 +109,16 @@ export default function SiteMetadata(): JSX.Element {
 
       <SearchMetadata tag={DEFAULT_SEARCH_TAG} locale={currentLocale} />
 
-      <Head
-      // it's important to have an additional <Head> element here,
-      // as it allows react-helmet to override values set in previous <Head>
-      // ie we can override default metadata such as "twitter:card"
-      // In same Head, the same meta would appear twice instead of overriding
-      // See react-helmet doc
-      >
+      {/*
+        It's important to have an additional <Head> element here, as it allows
+        react-helmet to override default metadata values set in previous <Head>
+        like "twitter:card". In same Head, the same meta would appear twice
+        instead of overriding.
+      */}
+      <Head>
         {/* Yes, "metadatum" is the grammatically correct term */}
         {metadata.map((metadatum, i) => (
-          <meta key={`metadata_${i}`} {...metadatum} />
+          <meta key={i} {...metadatum} />
         ))}
       </Head>
     </>

package/src/theme-classic.d.ts

@@ -1022,8 +1022,8 @@ declare module '@theme/TOCItems' {
 declare module '@theme/TOC' {
   import type {TOCItem} from '@docusaurus/types';
 
-  // minHeadingLevel only exists as a per-doc option, and won't have a default
-  // set by Joi. See TOC, TOCInline, TOCCollapsible for examples
+  // `minHeadingLevel` only comes from doc/post front matter, and won't have a
+  // default set by Joi. See TOC, TOCInline, TOCCollapsible for examples.
   export interface Props {
     readonly toc: readonly TOCItem[];
     readonly minHeadingLevel?: number;

package/src/validateThemeConfig.ts

@@ -100,7 +100,7 @@ const HtmlNavbarItemSchema = Joi.object({
 });
 
 const itemWithType = (type: string | undefined) => {
-  // because equal(undefined) is not supported :/
+  // Because equal(undefined) is not supported :/
   const typeSchema = type
     ? Joi.string().required().equal(type)
     : Joi.string().forbidden();
@@ -241,7 +241,6 @@ const ColorModeSchema = Joi.object({
   }),
 }).default(DEFAULT_COLOR_MODE_CONFIG);
 
-// schema can probably be improved
 const HtmlMetadataSchema = Joi.object({
   id: Joi.string(),
   name: Joi.string(),