@docusaurus/theme-classic 0.0.0-5139 → 0.0.0-5143

package/lib/theme/{DocItemFooter → DocItem/Content}/index.d.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="react" />
-import type { Props } from '@theme/DocItem';
-export default function DocItemFooter(props: Props): JSX.Element | null;
+import type { Props } from '@theme/DocItem/Content';
+export default function DocItemContent({ children }: Props): JSX.Element;

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

@@ -0,0 +1,43 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle() {
+  const {metadata, frontMatter, contentTitle} = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+export default function DocItemContent({children}) {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/lib/theme/DocItem/Footer/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+export default function DocItemFooter(): JSX.Element | null;

package/lib/theme/{DocItemFooter → DocItem/Footer}/index.js

@@ -6,7 +6,7 @@
  */
 import React from 'react';
 import clsx from 'clsx';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
 import LastUpdated from '@theme/LastUpdated';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline from '@theme/TagsListInline';
@@ -46,9 +46,8 @@ function EditMetaRow({
     </div>
   );
 }
-export default function DocItemFooter(props) {
-  const {content: DocContent} = props;
-  const {metadata} = DocContent;
+export default function DocItemFooter() {
+  const {metadata} = useDoc();
   const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, lastUpdatedBy, tags} =
     metadata;
   const canDisplayTagsRow = tags.length > 0;

package/lib/theme/DocItem/Layout/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/DocItem/Layout';
+export default function DocItemLayout({ children }: Props): JSX.Element;

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

@@ -0,0 +1,58 @@
+/**
+ * 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 {useWindowSize, useDoc} from '@docusaurus/theme-common';
+import DocItemPaginator from '@theme/DocItem/Paginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocItemFooter from '@theme/DocItem/Footer';
+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 styles from './styles.module.css';
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const {frontMatter, toc} = useDoc();
+  const windowSize = useWindowSize();
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+  const desktop =
+    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+export default function DocItemLayout({children}) {
+  const docTOC = useDocTOC();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/lib/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/lib/theme/DocItem/Metadata/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+export default function DocItemMetadata(): JSX.Element;

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

@@ -0,0 +1,19 @@
+/**
+ * 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 {PageMetadata, useDoc} from '@docusaurus/theme-common';
+export default function DocItemMetadata() {
+  const {metadata, frontMatter, assets} = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/lib/theme/DocItem/Paginator/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator(): JSX.Element;

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

@@ -0,0 +1,17 @@
+/**
+ * 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 {useDoc} from '@docusaurus/theme-common';
+import DocPaginator from '@theme/DocPaginator';
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator() {
+  const {metadata} = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/lib/theme/DocItem/TOC/Desktop/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+export default function DocItemTOCDesktop(): JSX.Element;

package/lib/theme/DocItem/TOC/Desktop/index.js

@@ -0,0 +1,20 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import TOC from '@theme/TOC';
+export default function DocItemTOCDesktop() {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/lib/theme/DocItem/TOC/Mobile/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+export default function DocItemTOCMobile(): JSX.Element;

package/lib/theme/DocItem/TOC/Mobile/index.js

@@ -0,0 +1,22 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import TOCCollapsible from '@theme/TOCCollapsible';
+import styles from './styles.module.css';
+export default function DocItemTOCMobile() {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)}
+    />
+  );
+}

package/lib/theme/DocItem/{styles.module.css → TOC/Mobile/styles.module.css}

@@ -5,16 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer header + *,
-.docItemContainer article > *:first-child {
-  margin-top: 0;
-}
-
 @media (min-width: 997px) {
-  .docItemCol {
-    max-width: 75% !important;
-  }
-
   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
   .tocMobile {
     display: none;

package/lib/theme/DocItem/index.js

@@ -5,113 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import clsx from 'clsx';
-import {
-  PageMetadata,
-  HtmlClassNameProvider,
-  ThemeClassNames,
-  useWindowSize,
-} from '@docusaurus/theme-common';
-import DocPaginator from '@theme/DocPaginator';
-import DocVersionBanner from '@theme/DocVersionBanner';
-import DocVersionBadge from '@theme/DocVersionBadge';
-import DocItemFooter from '@theme/DocItemFooter';
-import TOC from '@theme/TOC';
-import TOCCollapsible from '@theme/TOCCollapsible';
-import Heading from '@theme/Heading';
-import DocBreadcrumbs from '@theme/DocBreadcrumbs';
-import MDXContent from '@theme/MDXContent';
-import styles from './styles.module.css';
-function DocItemMetadata(props) {
-  const {content: DocContent} = props;
-  const {metadata, frontMatter, assets} = DocContent;
-  const {keywords} = frontMatter;
-  const {description, title} = metadata;
-  const image = assets.image ?? frontMatter.image;
-  return <PageMetadata {...{title, description, keywords, image}} />;
-}
-function DocItemContent(props) {
-  const {content: DocContent} = props;
-  const {metadata, frontMatter} = DocContent;
-  const {
-    hide_title: hideTitle,
-    hide_table_of_contents: hideTableOfContents,
-    toc_min_heading_level: tocMinHeadingLevel,
-    toc_max_heading_level: tocMaxHeadingLevel,
-  } = frontMatter;
-  const {title} = metadata;
-  // We only add a title if:
-  // - user doesn't ask to hide it with front matter
-  // - the markdown content does not already contain a top-level h1 heading
-  const shouldAddTitle =
-    !hideTitle && typeof DocContent.contentTitle === 'undefined';
-  const windowSize = useWindowSize();
-  const canRenderTOC = !hideTableOfContents && DocContent.toc.length > 0;
-  const renderTocDesktop =
-    canRenderTOC && (windowSize === 'desktop' || windowSize === 'ssr');
-  return (
-    <div className="row">
-      <div className={clsx('col', !hideTableOfContents && styles.docItemCol)}>
-        <DocVersionBanner />
-        <div className={styles.docItemContainer}>
-          <article>
-            <DocBreadcrumbs />
-            <DocVersionBadge />
-
-            {canRenderTOC && (
-              <TOCCollapsible
-                toc={DocContent.toc}
-                minHeadingLevel={tocMinHeadingLevel}
-                maxHeadingLevel={tocMaxHeadingLevel}
-                className={clsx(
-                  ThemeClassNames.docs.docTocMobile,
-                  styles.tocMobile,
-                )}
-              />
-            )}
-
-            <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
-              {/*
-          Title can be declared inside md content or declared through
-          front matter and added manually. To make both cases consistent,
-          the added title is added under the same div.markdown block
-          See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
-          */}
-              {shouldAddTitle && (
-                <header>
-                  <Heading as="h1">{title}</Heading>
-                </header>
-              )}
-              <MDXContent>
-                <DocContent />
-              </MDXContent>
-            </div>
-
-            <DocItemFooter {...props} />
-          </article>
-
-          <DocPaginator previous={metadata.previous} next={metadata.next} />
-        </div>
-      </div>
-      {renderTocDesktop && (
-        <div className="col col--3">
-          <TOC
-            toc={DocContent.toc}
-            minHeadingLevel={tocMinHeadingLevel}
-            maxHeadingLevel={tocMaxHeadingLevel}
-            className={ThemeClassNames.docs.docTocDesktop}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
+import {HtmlClassNameProvider, DocProvider} from '@docusaurus/theme-common';
+import DocItemMetadata from '@theme/DocItem/Metadata';
+import DocItemLayout from '@theme/DocItem/Layout';
 export default function DocItem(props) {
   const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
+  const MDXComponent = props.content;
   return (
-    <HtmlClassNameProvider className={docHtmlClassName}>
-      <DocItemMetadata {...props} />
-      <DocItemContent {...props} />
-    </HtmlClassNameProvider>
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <MDXComponent />
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
   );
 }

package/lib/theme/Logo/index.js

@@ -23,12 +23,18 @@ export default function Logo(props) {
     light: useBaseUrl(logo.src),
     dark: useBaseUrl(logo.srcDark || logo.src),
   };
+  // If visible title is shown, fallback alt text should be
+  // an empty string to mark the logo as decorative.
+  const fallbackAlt = navbarTitle ? '' : title;
+  // Use logo alt text if provided (including empty string),
+  // and provide a sensible fallback otherwise.
+  const alt = logo.alt ?? fallbackAlt;
   const themedImage = (
     <ThemedImage
       sources={sources}
       height={logo.height}
       width={logo.width}
-      alt={logo.alt || navbarTitle || title}
+      alt={alt}
     />
   );
   return (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-5139",
+  "version": "0.0.0-5143",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,18 +20,18 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5139",
-    "@docusaurus/mdx-loader": "0.0.0-5139",
-    "@docusaurus/module-type-aliases": "0.0.0-5139",
-    "@docusaurus/plugin-content-blog": "0.0.0-5139",
-    "@docusaurus/plugin-content-docs": "0.0.0-5139",
-    "@docusaurus/plugin-content-pages": "0.0.0-5139",
-    "@docusaurus/theme-common": "0.0.0-5139",
-    "@docusaurus/theme-translations": "0.0.0-5139",
-    "@docusaurus/types": "0.0.0-5139",
-    "@docusaurus/utils": "0.0.0-5139",
-    "@docusaurus/utils-common": "0.0.0-5139",
-    "@docusaurus/utils-validation": "0.0.0-5139",
+    "@docusaurus/core": "0.0.0-5143",
+    "@docusaurus/mdx-loader": "0.0.0-5143",
+    "@docusaurus/module-type-aliases": "0.0.0-5143",
+    "@docusaurus/plugin-content-blog": "0.0.0-5143",
+    "@docusaurus/plugin-content-docs": "0.0.0-5143",
+    "@docusaurus/plugin-content-pages": "0.0.0-5143",
+    "@docusaurus/theme-common": "0.0.0-5143",
+    "@docusaurus/theme-translations": "0.0.0-5143",
+    "@docusaurus/types": "0.0.0-5143",
+    "@docusaurus/utils": "0.0.0-5143",
+    "@docusaurus/utils-common": "0.0.0-5143",
+    "@docusaurus/utils-validation": "0.0.0-5143",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
@@ -64,5 +64,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "4a9fdb882b4c4058ca2f91247a7ab83832356b32"
+  "gitHead": "bf3edad97a282dde2d811ea8a3bc336618af9848"
 }

package/src/theme/DocItem/Content/index.tsx

@@ -0,0 +1,47 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+import type {Props} from '@theme/DocItem/Content';
+
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle(): string | null {
+  const {metadata, frontMatter, contentTitle} = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+
+export default function DocItemContent({children}: Props): JSX.Element {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/src/theme/{DocItemFooter → DocItem/Footer}/index.tsx

@@ -7,13 +7,16 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  useDoc,
+  type DocContextValue,
+} from '@docusaurus/theme-common';
 import LastUpdated from '@theme/LastUpdated';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline, {
   type Props as TagsListInlineProps,
 } from '@theme/TagsListInline';
-import type {Props} from '@theme/DocItem';
 
 import styles from './styles.module.css';
 
@@ -32,7 +35,7 @@ function TagsRow(props: TagsListInlineProps) {
 }
 
 type EditMetaRowProps = Pick<
-  Props['content']['metadata'],
+  DocContextValue['metadata'],
   'editUrl' | 'lastUpdatedAt' | 'lastUpdatedBy' | 'formattedLastUpdatedAt'
 >;
 function EditMetaRow({
@@ -58,9 +61,8 @@ function EditMetaRow({
   );
 }
 
-export default function DocItemFooter(props: Props): JSX.Element | null {
-  const {content: DocContent} = props;
-  const {metadata} = DocContent;
+export default function DocItemFooter(): JSX.Element | null {
+  const {metadata} = useDoc();
   const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, lastUpdatedBy, tags} =
     metadata;
 

package/src/theme/DocItem/Layout/index.tsx

@@ -0,0 +1,67 @@
+/**
+ * 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 {useWindowSize, useDoc} from '@docusaurus/theme-common';
+import DocItemPaginator from '@theme/DocItem/Paginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocItemFooter from '@theme/DocItem/Footer';
+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 type {Props} from '@theme/DocItem/Layout';
+
+import styles from './styles.module.css';
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const {frontMatter, toc} = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({children}: Props): JSX.Element {
+  const docTOC = useDocTOC();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/src/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/src/theme/DocItem/Metadata/index.tsx

@@ -0,0 +1,21 @@
+/**
+ * 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 {PageMetadata, useDoc} from '@docusaurus/theme-common';
+
+export default function DocItemMetadata(): JSX.Element {
+  const {metadata, frontMatter, assets} = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/src/theme/DocItem/Paginator/index.tsx

@@ -0,0 +1,19 @@
+/**
+ * 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 {useDoc} from '@docusaurus/theme-common';
+import DocPaginator from '@theme/DocPaginator';
+
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator(): JSX.Element {
+  const {metadata} = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/src/theme/DocItem/TOC/Desktop/index.tsx

@@ -0,0 +1,23 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+
+import TOC from '@theme/TOC';
+
+export default function DocItemTOCDesktop(): JSX.Element {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/src/theme/DocItem/TOC/Mobile/index.tsx

@@ -0,0 +1,25 @@
+/**
+ * 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 {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import TOCCollapsible from '@theme/TOCCollapsible';
+
+import styles from './styles.module.css';
+
+export default function DocItemTOCMobile(): JSX.Element {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)}
+    />
+  );
+}

package/src/theme/DocItem/{styles.module.css → TOC/Mobile/styles.module.css}

@@ -5,16 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer header + *,
-.docItemContainer article > *:first-child {
-  margin-top: 0;
-}
-
 @media (min-width: 997px) {
-  .docItemCol {
-    max-width: 75% !important;
-  }
-
   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
   .tocMobile {
     display: none;

package/src/theme/DocItem/index.tsx

@@ -6,124 +6,22 @@
  */
 
 import React from 'react';
-import clsx from 'clsx';
-import {
-  PageMetadata,
-  HtmlClassNameProvider,
-  ThemeClassNames,
-  useWindowSize,
-} from '@docusaurus/theme-common';
-import DocPaginator from '@theme/DocPaginator';
-import DocVersionBanner from '@theme/DocVersionBanner';
-import DocVersionBadge from '@theme/DocVersionBadge';
-import DocItemFooter from '@theme/DocItemFooter';
-import TOC from '@theme/TOC';
-import TOCCollapsible from '@theme/TOCCollapsible';
-import Heading from '@theme/Heading';
-import DocBreadcrumbs from '@theme/DocBreadcrumbs';
-import MDXContent from '@theme/MDXContent';
+import {HtmlClassNameProvider, DocProvider} from '@docusaurus/theme-common';
+import DocItemMetadata from '@theme/DocItem/Metadata';
+import DocItemLayout from '@theme/DocItem/Layout';
 import type {Props} from '@theme/DocItem';
 
-import styles from './styles.module.css';
-
-function DocItemMetadata(props: Props): JSX.Element {
-  const {content: DocContent} = props;
-  const {metadata, frontMatter, assets} = DocContent;
-  const {keywords} = frontMatter;
-  const {description, title} = metadata;
-  const image = assets.image ?? frontMatter.image;
-
-  return <PageMetadata {...{title, description, keywords, image}} />;
-}
-
-function DocItemContent(props: Props): JSX.Element {
-  const {content: DocContent} = props;
-  const {metadata, frontMatter} = DocContent;
-  const {
-    hide_title: hideTitle,
-    hide_table_of_contents: hideTableOfContents,
-    toc_min_heading_level: tocMinHeadingLevel,
-    toc_max_heading_level: tocMaxHeadingLevel,
-  } = frontMatter;
-  const {title} = metadata;
-
-  // We only add a title if:
-  // - user doesn't ask to hide it with front matter
-  // - the markdown content does not already contain a top-level h1 heading
-  const shouldAddTitle =
-    !hideTitle && typeof DocContent.contentTitle === 'undefined';
-
-  const windowSize = useWindowSize();
-
-  const canRenderTOC = !hideTableOfContents && DocContent.toc.length > 0;
-
-  const renderTocDesktop =
-    canRenderTOC && (windowSize === 'desktop' || windowSize === 'ssr');
-
-  return (
-    <div className="row">
-      <div className={clsx('col', !hideTableOfContents && styles.docItemCol)}>
-        <DocVersionBanner />
-        <div className={styles.docItemContainer}>
-          <article>
-            <DocBreadcrumbs />
-            <DocVersionBadge />
-
-            {canRenderTOC && (
-              <TOCCollapsible
-                toc={DocContent.toc}
-                minHeadingLevel={tocMinHeadingLevel}
-                maxHeadingLevel={tocMaxHeadingLevel}
-                className={clsx(
-                  ThemeClassNames.docs.docTocMobile,
-                  styles.tocMobile,
-                )}
-              />
-            )}
-
-            <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
-              {/*
-                Title can be declared inside md content or declared through
-                front matter and added manually. To make both cases consistent,
-                the added title is added under the same div.markdown block
-                See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
-                */}
-              {shouldAddTitle && (
-                <header>
-                  <Heading as="h1">{title}</Heading>
-                </header>
-              )}
-              <MDXContent>
-                <DocContent />
-              </MDXContent>
-            </div>
-
-            <DocItemFooter {...props} />
-          </article>
-
-          <DocPaginator previous={metadata.previous} next={metadata.next} />
-        </div>
-      </div>
-      {renderTocDesktop && (
-        <div className="col col--3">
-          <TOC
-            toc={DocContent.toc}
-            minHeadingLevel={tocMinHeadingLevel}
-            maxHeadingLevel={tocMaxHeadingLevel}
-            className={ThemeClassNames.docs.docTocDesktop}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
-
 export default function DocItem(props: Props): JSX.Element {
   const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
+  const MDXComponent = props.content;
   return (
-    <HtmlClassNameProvider className={docHtmlClassName}>
-      <DocItemMetadata {...props} />
-      <DocItemContent {...props} />
-    </HtmlClassNameProvider>
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <MDXComponent />
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
   );
 }

package/src/theme/DocPaginator/index.tsx

@@ -12,7 +12,6 @@ import type {Props} from '@theme/DocPaginator';
 
 export default function DocPaginator(props: Props): JSX.Element {
   const {previous, next} = props;
-
   return (
     <nav
       className="pagination-nav docusaurus-mt-lg"

package/src/theme/Logo/index.tsx

@@ -27,12 +27,21 @@ export default function Logo(props: Props): JSX.Element {
     light: useBaseUrl(logo.src),
     dark: useBaseUrl(logo.srcDark || logo.src),
   };
+
+  // If visible title is shown, fallback alt text should be
+  // an empty string to mark the logo as decorative.
+  const fallbackAlt = navbarTitle ? '' : title;
+
+  // Use logo alt text if provided (including empty string),
+  // and provide a sensible fallback otherwise.
+  const alt = logo.alt ?? fallbackAlt;
+
   const themedImage = (
     <ThemedImage
       sources={sources}
       height={logo.height}
       width={logo.width}
-      alt={logo.alt || navbarTitle || title}
+      alt={alt}
     />
   );
 

package/src/theme-classic.d.ts

@@ -261,10 +261,40 @@ declare module '@theme/DocCardList' {
   export default function DocCardList(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocItemFooter' {
-  import type {Props} from '@theme/DocItem';
+declare module '@theme/DocItem/Layout' {
+  export interface Props {
+    readonly children: JSX.Element;
+  }
+
+  export default function DocItemLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocItem/Metadata' {
+  export default function DocItemMetadata(): JSX.Element;
+}
+
+declare module '@theme/DocItem/Content' {
+  export interface Props {
+    readonly children: JSX.Element;
+  }
+
+  export default function DocItemContent(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocItem/TOC/Mobile' {
+  export default function DocItemTOCMobile(): JSX.Element;
+}
+
+declare module '@theme/DocItem/TOC/Desktop' {
+  export default function DocItemTOCDesktop(): JSX.Element;
+}
+
+declare module '@theme/DocItem/Paginator' {
+  export default function DocItemPaginator(): JSX.Element;
+}
 
-  export default function DocItemFooter(props: Props): JSX.Element;
+declare module '@theme/DocItem/Footer' {
+  export default function DocItemFooter(): JSX.Element;
 }
 
 declare module '@theme/DocPage/Layout' {