@docusaurus/theme-classic 2.4.1 → 3.0.0-alpha.0

package/lib/theme/Admonition/Types.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import AdmonitionTypeNote from '@theme/Admonition/Type/Note';
+import AdmonitionTypeTip from '@theme/Admonition/Type/Tip';
+import AdmonitionTypeInfo from '@theme/Admonition/Type/Info';
+import AdmonitionTypeCaution from '@theme/Admonition/Type/Caution';
+import AdmonitionTypeDanger from '@theme/Admonition/Type/Danger';
+const admonitionTypes = {
+  note: AdmonitionTypeNote,
+  tip: AdmonitionTypeTip,
+  info: AdmonitionTypeInfo,
+  caution: AdmonitionTypeCaution,
+  danger: AdmonitionTypeDanger,
+};
+// Undocumented legacy admonition type aliases
+// Provide hardcoded/untranslated retrocompatible label
+// See also https://github.com/facebook/docusaurus/issues/7767
+const admonitionAliases = {
+  secondary: (props) => <AdmonitionTypeNote title="secondary" {...props} />,
+  important: (props) => <AdmonitionTypeInfo title="important" {...props} />,
+  success: (props) => <AdmonitionTypeTip title="success" {...props} />,
+  // TODO bad legacy mapping, warning is usually yellow, not red...
+  warning: (props) => <AdmonitionTypeDanger title="warning" {...props} />,
+};
+export default {
+  ...admonitionTypes,
+  ...admonitionAliases,
+};

package/lib/theme/Admonition/index.d.ts

@@ -6,4 +6,4 @@
  */
 /// <reference types="react" />
 import type { Props } from '@theme/Admonition';
-export default function Admonition(props: Props): JSX.Element;
+export default function Admonition(unprocessedProps: Props): JSX.Element;

package/lib/theme/Admonition/index.js

@@ -5,179 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import clsx from 'clsx';
-import {ThemeClassNames} from '@docusaurus/theme-common';
-import Translate from '@docusaurus/Translate';
-import styles from './styles.module.css';
-function NoteIcon() {
-  return (
-    <svg viewBox="0 0 14 16">
-      <path
-        fillRule="evenodd"
-        d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"
-      />
-    </svg>
-  );
-}
-function TipIcon() {
-  return (
-    <svg viewBox="0 0 12 16">
-      <path
-        fillRule="evenodd"
-        d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"
-      />
-    </svg>
-  );
-}
-function DangerIcon() {
-  return (
-    <svg viewBox="0 0 12 16">
-      <path
-        fillRule="evenodd"
-        d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"
-      />
-    </svg>
-  );
-}
-function InfoIcon() {
-  return (
-    <svg viewBox="0 0 14 16">
-      <path
-        fillRule="evenodd"
-        d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"
-      />
-    </svg>
-  );
-}
-function CautionIcon() {
-  return (
-    <svg viewBox="0 0 16 16">
-      <path
-        fillRule="evenodd"
-        d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"
-      />
-    </svg>
-  );
-}
-// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
-const AdmonitionConfigs = {
-  note: {
-    infimaClassName: 'secondary',
-    iconComponent: NoteIcon,
-    label: (
-      <Translate
-        id="theme.admonition.note"
-        description="The default label used for the Note admonition (:::note)">
-        note
-      </Translate>
-    ),
-  },
-  tip: {
-    infimaClassName: 'success',
-    iconComponent: TipIcon,
-    label: (
-      <Translate
-        id="theme.admonition.tip"
-        description="The default label used for the Tip admonition (:::tip)">
-        tip
-      </Translate>
-    ),
-  },
-  danger: {
-    infimaClassName: 'danger',
-    iconComponent: DangerIcon,
-    label: (
-      <Translate
-        id="theme.admonition.danger"
-        description="The default label used for the Danger admonition (:::danger)">
-        danger
-      </Translate>
-    ),
-  },
-  info: {
-    infimaClassName: 'info',
-    iconComponent: InfoIcon,
-    label: (
-      <Translate
-        id="theme.admonition.info"
-        description="The default label used for the Info admonition (:::info)">
-        info
-      </Translate>
-    ),
-  },
-  caution: {
-    infimaClassName: 'warning',
-    iconComponent: CautionIcon,
-    label: (
-      <Translate
-        id="theme.admonition.caution"
-        description="The default label used for the Caution admonition (:::caution)">
-        caution
-      </Translate>
-    ),
-  },
-};
-// Legacy aliases, undocumented but kept for retro-compatibility
-const aliases = {
-  secondary: 'note',
-  important: 'info',
-  success: 'tip',
-  warning: 'danger',
-};
-function getAdmonitionConfig(unsafeType) {
-  const type = aliases[unsafeType] ?? unsafeType;
-  const config = AdmonitionConfigs[type];
-  if (config) {
-    return config;
+import {processAdmonitionProps} from '@docusaurus/theme-common';
+import AdmonitionTypes from '@theme/Admonition/Types';
+function getAdmonitionTypeComponent(type) {
+  const component = AdmonitionTypes[type];
+  if (component) {
+    return component;
   }
   console.warn(
-    `No admonition config found for admonition type "${type}". Using Info as fallback.`,
+    `No admonition component found for admonition type "${type}". Using Info as fallback.`,
   );
-  return AdmonitionConfigs.info;
+  return AdmonitionTypes.info;
 }
-// Workaround because it's difficult in MDX v1 to provide a MDX title as props
-// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
-function extractMDXAdmonitionTitle(children) {
-  const items = React.Children.toArray(children);
-  const mdxAdmonitionTitle = items.find(
-    (item) =>
-      React.isValidElement(item) &&
-      item.props?.mdxType === 'mdxAdmonitionTitle',
-  );
-  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
-  return {
-    mdxAdmonitionTitle,
-    rest,
-  };
-}
-function processAdmonitionProps(props) {
-  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
-  return {
-    ...props,
-    title: props.title ?? mdxAdmonitionTitle,
-    children: rest,
-  };
-}
-export default function Admonition(props) {
-  const {children, type, title, icon: iconProp} = processAdmonitionProps(props);
-  const typeConfig = getAdmonitionConfig(type);
-  const titleLabel = title ?? typeConfig.label;
-  const {iconComponent: IconComponent} = typeConfig;
-  const icon = iconProp ?? <IconComponent />;
-  return (
-    <div
-      className={clsx(
-        ThemeClassNames.common.admonition,
-        ThemeClassNames.common.admonitionType(props.type),
-        'alert',
-        `alert--${typeConfig.infimaClassName}`,
-        styles.admonition,
-      )}>
-      <div className={styles.admonitionHeading}>
-        <span className={styles.admonitionIcon}>{icon}</span>
-        {titleLabel}
-      </div>
-      <div className={styles.admonitionContent}>{children}</div>
-    </div>
-  );
+export default function Admonition(unprocessedProps) {
+  const props = processAdmonitionProps(unprocessedProps);
+  const AdmonitionTypeComponent = getAdmonitionTypeComponent(props.type);
+  return <AdmonitionTypeComponent {...props} />;
 }

package/lib/theme/BlogArchivePage/index.js

@@ -9,10 +9,13 @@ import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import {PageMetadata} from '@docusaurus/theme-common';
 import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
 function Year({year, posts}) {
   return (
     <>
-      <h3>{year}</h3>
+      <Heading as="h3" id={year}>
+        {year}
+      </Heading>
       <ul>
         {posts.map((post) => (
           <li key={post.metadata.date}>
@@ -69,7 +72,9 @@ export default function BlogArchive({archive}) {
       <Layout>
         <header className="hero hero--primary">
           <div className="container">
-            <h1 className="hero__title">{title}</h1>
+            <Heading as="h1" className="hero__title">
+              {title}
+            </Heading>
             <p className="hero__subtitle">{description}</p>
           </div>
         </header>

package/lib/theme/BlogPostPage/index.js

@@ -13,9 +13,10 @@ import BlogPostItem from '@theme/BlogPostItem';
 import BlogPostPaginator from '@theme/BlogPostPaginator';
 import BlogPostPageMetadata from '@theme/BlogPostPage/Metadata';
 import TOC from '@theme/TOC';
+import Unlisted from '@theme/Unlisted';
 function BlogPostPageContent({sidebar, children}) {
   const {metadata, toc} = useBlogPost();
-  const {nextItem, prevItem, frontMatter} = metadata;
+  const {nextItem, prevItem, frontMatter, unlisted} = metadata;
   const {
     hide_table_of_contents: hideTableOfContents,
     toc_min_heading_level: tocMinHeadingLevel,
@@ -33,6 +34,7 @@ function BlogPostPageContent({sidebar, children}) {
           />
         ) : undefined
       }>
+      {unlisted && <Unlisted />}
       <BlogPostItem>{children}</BlogPostItem>
 
       {(nextItem || prevItem) && (

package/lib/theme/BlogSidebar/Desktop/index.js

@@ -8,8 +8,10 @@ import React from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
+import {useVisibleBlogSidebarItems} from '@docusaurus/theme-common/internal';
 import styles from './styles.module.css';
 export default function BlogSidebarDesktop({sidebar}) {
+  const items = useVisibleBlogSidebarItems(sidebar.items);
   return (
     <aside className="col col--3">
       <nav
@@ -23,7 +25,7 @@ export default function BlogSidebarDesktop({sidebar}) {
           {sidebar.title}
         </div>
         <ul className={clsx(styles.sidebarItemList, 'clean-list')}>
-          {sidebar.items.map((item) => (
+          {items.map((item) => (
             <li key={item.permalink} className={styles.sidebarItem}>
               <Link
                 isNavLink

package/lib/theme/BlogSidebar/Mobile/index.js

@@ -6,11 +6,13 @@
  */
 import React from 'react';
 import Link from '@docusaurus/Link';
+import {useVisibleBlogSidebarItems} from '@docusaurus/theme-common/internal';
 import {NavbarSecondaryMenuFiller} from '@docusaurus/theme-common';
 function BlogSidebarMobileSecondaryMenu({sidebar}) {
+  const items = useVisibleBlogSidebarItems(sidebar.items);
   return (
     <ul className="menu__list">
-      {sidebar.items.map((item) => (
+      {items.map((item) => (
         <li key={item.permalink} className="menu__list-item">
           <Link
             isNavLink

package/lib/theme/BlogTagsListPage/index.js

@@ -15,6 +15,7 @@ import {
 import BlogLayout from '@theme/BlogLayout';
 import TagsListByLetter from '@theme/TagsListByLetter';
 import SearchMetadata from '@theme/SearchMetadata';
+import Heading from '@theme/Heading';
 export default function BlogTagsListPage({tags, sidebar}) {
   const title = translateTagsPageTitle();
   return (
@@ -26,7 +27,7 @@ export default function BlogTagsListPage({tags, sidebar}) {
       <PageMetadata title={title} />
       <SearchMetadata tag="blog_tags_list" />
       <BlogLayout sidebar={sidebar}>
-        <h1>{title}</h1>
+        <Heading as="h1">{title}</Heading>
         <TagsListByLetter tags={tags} />
       </BlogLayout>
     </HtmlClassNameProvider>

package/lib/theme/BlogTagsPostsPage/index.js

@@ -18,6 +18,8 @@ import BlogLayout from '@theme/BlogLayout';
 import BlogListPaginator from '@theme/BlogListPaginator';
 import SearchMetadata from '@theme/SearchMetadata';
 import BlogPostItems from '@theme/BlogPostItems';
+import Unlisted from '@theme/Unlisted';
+import Heading from '@theme/Heading';
 // Very simple pluralization: probably good enough for now
 function useBlogPostsPlural() {
   const {selectMessage} = usePluralForm();
@@ -59,9 +61,9 @@ function BlogTagsPostsPageContent({tag, items, sidebar, listMetadata}) {
   const title = useBlogTagsPostsPageTitle(tag);
   return (
     <BlogLayout sidebar={sidebar}>
+      {tag.unlisted && <Unlisted />}
       <header className="margin-bottom--xl">
-        <h1>{title}</h1>
-
+        <Heading as="h1">{title}</Heading>
         <Link href={tag.allTagsPath}>
           <Translate
             id="theme.tags.tagsPageLink"

package/lib/theme/DocBreadcrumbs/index.js

@@ -79,13 +79,17 @@ export default function DocBreadcrumbs() {
         {homePageRoute && <HomeBreadcrumbItem />}
         {breadcrumbs.map((item, idx) => {
           const isLast = idx === breadcrumbs.length - 1;
+          const href =
+            item.type === 'category' && item.linkUnlisted
+              ? undefined
+              : item.href;
           return (
             <BreadcrumbsItem
               key={idx}
               active={isLast}
               index={idx}
-              addMicrodata={!!item.href}>
-              <BreadcrumbsItemLink href={item.href} isLast={isLast}>
+              addMicrodata={!!href}>
+              <BreadcrumbsItemLink href={href} isLast={isLast}>
                 {item.label}
               </BreadcrumbsItemLink>
             </BreadcrumbsItem>

package/lib/theme/DocCard/index.js

@@ -8,11 +8,12 @@ import React from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import {
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocById,
 } from '@docusaurus/theme-common/internal';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 function CardContainer({href, children}) {
   return (
@@ -26,9 +27,12 @@ function CardContainer({href, children}) {
 function CardLayout({href, icon, title, description}) {
   return (
     <CardContainer href={href}>
-      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+      <Heading
+        as="h2"
+        className={clsx('text--truncate', styles.cardTitle)}
+        title={title}>
         {icon} {title}
-      </h2>
+      </Heading>
       {description && (
         <p
           className={clsx('text--truncate', styles.cardDescription)}
@@ -40,7 +44,7 @@ function CardLayout({href, icon, title, description}) {
   );
 }
 function CardCategory({item}) {
-  const href = findFirstCategoryLink(item);
+  const href = findFirstSidebarItemLink(item);
   // Unexpected: categories that don't have a link have been filtered upfront
   if (!href) {
     return null;

package/lib/theme/DocItem/Layout/index.js

@@ -16,6 +16,7 @@ import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
 import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
 import DocItemContent from '@theme/DocItem/Content';
 import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import Unlisted from '@theme/Unlisted';
 import styles from './styles.module.css';
 /**
  * Decide if the toc should be rendered, on mobile or desktop viewports
@@ -38,9 +39,13 @@ function useDocTOC() {
 }
 export default function DocItemLayout({children}) {
   const docTOC = useDocTOC();
+  const {
+    metadata: {unlisted},
+  } = useDoc();
   return (
     <div className="row">
       <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        {unlisted && <Unlisted />}
         <DocVersionBanner />
         <div className={styles.docItemContainer}>
           <article>

package/lib/theme/{DocPage → DocRoot}/Layout/Main/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/DocPage/Layout/Main';
-export default function DocPageLayoutMain({ hiddenSidebarContainer, children, }: Props): JSX.Element;
+import type { Props } from '@theme/DocRoot/Layout/Main';
+export default function DocRootLayoutMain({ hiddenSidebarContainer, children, }: Props): JSX.Element;

package/lib/theme/{DocPage → DocRoot}/Layout/Main/index.js

@@ -8,7 +8,7 @@ import React from 'react';
 import clsx from 'clsx';
 import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 import styles from './styles.module.css';
-export default function DocPageLayoutMain({hiddenSidebarContainer, children}) {
+export default function DocRootLayoutMain({hiddenSidebarContainer, children}) {
   const sidebar = useDocsSidebar();
   return (
     <main

package/lib/theme/{DocPage → DocRoot}/Layout/Sidebar/ExpandButton/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/DocPage/Layout/Sidebar/ExpandButton';
-export default function DocPageLayoutSidebarExpandButton({ toggleSidebar, }: Props): JSX.Element;
+import type { Props } from '@theme/DocRoot/Layout/Sidebar/ExpandButton';
+export default function DocRootLayoutSidebarExpandButton({ toggleSidebar, }: Props): JSX.Element;

package/lib/theme/{DocPage → DocRoot}/Layout/Sidebar/ExpandButton/index.js

@@ -8,7 +8,7 @@ import React from 'react';
 import {translate} from '@docusaurus/Translate';
 import IconArrow from '@theme/Icon/Arrow';
 import styles from './styles.module.css';
-export default function DocPageLayoutSidebarExpandButton({toggleSidebar}) {
+export default function DocRootLayoutSidebarExpandButton({toggleSidebar}) {
   return (
     <div
       className={styles.expandButton}

package/lib/theme/{DocPage → DocRoot}/Layout/Sidebar/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/DocPage/Layout/Sidebar';
-export default function DocPageLayoutSidebar({ sidebar, hiddenSidebarContainer, setHiddenSidebarContainer, }: Props): JSX.Element;
+import type { Props } from '@theme/DocRoot/Layout/Sidebar';
+export default function DocRootLayoutSidebar({ sidebar, hiddenSidebarContainer, setHiddenSidebarContainer, }: Props): JSX.Element;

package/lib/theme/{DocPage → DocRoot}/Layout/Sidebar/index.js

@@ -10,7 +10,7 @@ import {prefersReducedMotion, ThemeClassNames} from '@docusaurus/theme-common';
 import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 import {useLocation} from '@docusaurus/router';
 import DocSidebar from '@theme/DocSidebar';
-import ExpandButton from '@theme/DocPage/Layout/Sidebar/ExpandButton';
+import ExpandButton from '@theme/DocRoot/Layout/Sidebar/ExpandButton';
 import styles from './styles.module.css';
 // Reset sidebar state when sidebar changes
 // Use React key to unmount/remount the children
@@ -23,7 +23,7 @@ function ResetOnSidebarChange({children}) {
     </React.Fragment>
   );
 }
-export default function DocPageLayoutSidebar({
+export default function DocRootLayoutSidebar({
   sidebar,
   hiddenSidebarContainer,
   setHiddenSidebarContainer,

package/lib/theme/{DocPage → DocRoot}/Layout/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/DocPage/Layout';
-export default function DocPageLayout({ children }: Props): JSX.Element;
+import type { Props } from '@theme/DocRoot/Layout';
+export default function DocRootLayout({ children }: Props): JSX.Element;

package/lib/theme/{DocPage → DocRoot}/Layout/index.js

@@ -6,29 +6,28 @@
  */
 import React, {useState} from 'react';
 import {useDocsSidebar} from '@docusaurus/theme-common/internal';
-import Layout from '@theme/Layout';
 import BackToTopButton from '@theme/BackToTopButton';
-import DocPageLayoutSidebar from '@theme/DocPage/Layout/Sidebar';
-import DocPageLayoutMain from '@theme/DocPage/Layout/Main';
+import DocRootLayoutSidebar from '@theme/DocRoot/Layout/Sidebar';
+import DocRootLayoutMain from '@theme/DocRoot/Layout/Main';
 import styles from './styles.module.css';
-export default function DocPageLayout({children}) {
+export default function DocRootLayout({children}) {
   const sidebar = useDocsSidebar();
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   return (
-    <Layout wrapperClassName={styles.docsWrapper}>
+    <div className={styles.docsWrapper}>
       <BackToTopButton />
-      <div className={styles.docPage}>
+      <div className={styles.docRoot}>
         {sidebar && (
-          <DocPageLayoutSidebar
+          <DocRootLayoutSidebar
             sidebar={sidebar.items}
             hiddenSidebarContainer={hiddenSidebarContainer}
             setHiddenSidebarContainer={setHiddenSidebarContainer}
           />
         )}
-        <DocPageLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
+        <DocRootLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
           {children}
-        </DocPageLayoutMain>
+        </DocRootLayoutMain>
       </div>
-    </Layout>
+    </div>
   );
 }

package/lib/theme/{DocPage → DocRoot}/Layout/styles.module.css

@@ -5,10 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docPage {
+.docRoot {
   display: flex;
   width: 100%;
-  flex: 1 0;
 }
 
 .docsWrapper {

package/lib/theme/{DocPage → DocRoot}/index.d.ts

@@ -6,5 +6,5 @@
  */
 /// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="react" />
-import type { Props } from '@theme/DocPage';
-export default function DocPage(props: Props): JSX.Element;
+import type { Props } from '@theme/DocRoot';
+export default function DocRoot(props: Props): JSX.Element;

package/lib/theme/DocRoot/index.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  DocsSidebarProvider,
+  useDocRootMetadata,
+} from '@docusaurus/theme-common/internal';
+import DocRootLayout from '@theme/DocRoot/Layout';
+import NotFoundContent from '@theme/NotFound/Content';
+export default function DocRoot(props) {
+  const currentDocRouteMetadata = useDocRootMetadata(props);
+  if (!currentDocRouteMetadata) {
+    // We only render the not found content to avoid a double layout
+    // see https://github.com/facebook/docusaurus/pull/7966#pullrequestreview-1077276692
+    return <NotFoundContent />;
+  }
+  const {docElement, sidebarName, sidebarItems} = currentDocRouteMetadata;
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.page.docsDocPage)}>
+      <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
+        <DocRootLayout>{docElement}</DocRootLayout>
+      </DocsSidebarProvider>
+    </HtmlClassNameProvider>
+  );
+}

package/lib/theme/DocSidebarItem/Category/index.js

@@ -15,7 +15,7 @@ import {
 } from '@docusaurus/theme-common';
 import {
   isActiveSidebarItem,
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocSidebarItemsExpandedState,
   isSamePath,
 } from '@docusaurus/theme-common/internal';
@@ -45,7 +45,7 @@ function useAutoExpandActiveCategory({isActive, collapsed, updateCollapsed}) {
 function useCategoryHrefWithSSRFallback(item) {
   const isBrowser = useIsBrowser();
   return useMemo(() => {
-    if (item.href) {
+    if (item.href && !item.linkUnlisted) {
       return item.href;
     }
     // In these cases, it's not necessary to render a fallback
@@ -53,7 +53,7 @@ function useCategoryHrefWithSSRFallback(item) {
     if (isBrowser || !item.collapsible) {
       return undefined;
     }
-    return findFirstCategoryLink(item);
+    return findFirstSidebarItemLink(item);
   }, [item, isBrowser]);
 }
 function CollapseButton({categoryLabel, onClick}) {

package/lib/theme/DocSidebarItems/index.js

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, {memo} from 'react';
-import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common/internal';
+import {
+  DocSidebarItemsExpandedStateProvider,
+  useVisibleSidebarItems,
+} from '@docusaurus/theme-common/internal';
 import DocSidebarItem from '@theme/DocSidebarItem';
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
 function DocSidebarItems({items, ...props}) {
+  const visibleItems = useVisibleSidebarItems(items, props.activePath);
   return (
     <DocSidebarItemsExpandedStateProvider>
-      {items.map((item, index) => (
+      {visibleItems.map((item, index) => (
         <DocSidebarItem key={index} item={item} index={index} {...props} />
       ))}
     </DocSidebarItemsExpandedStateProvider>