refactor(docs): theme-common shouldn't depend on docs content (#10316)

.github/workflows/tests-e2e.yml

@@ -102,19 +102,11 @@ jobs:
         working-directory: ../test-website
         env:
           YARN_ENABLE_IMMUTABLE_INSTALLS: false # Yarn berry should create the lockfile, despite CI env
-      - name: Install missing dependencies
-        if: matrix.variant == '-st' && matrix.nodeLinker == 'pnp'
-        run: |
-          # These dependencies are referenced in the init project, not by our packages
-          yarn add @docusaurus/theme-classic @docusaurus/types @types/node
-          yarn config set packageExtensions --json '{ "unified@^9.2.2": { "dependencies": { "@types/unist": "^2.0.6" } } }'
-        working-directory: ../test-website
       - name: Start test-website project
         run: yarn start --no-open
         working-directory: ../test-website
         env:
           E2E_TEST: true
-
       - name: TypeCheck website
         # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
         if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'

packages/docusaurus-plugin-content-blog/package.json

@@ -52,7 +52,8 @@
   },
   "peerDependencies": {
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "@docusaurus/plugin-content-docs": "*"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-docs/package.json

@@ -39,6 +39,7 @@
     "@docusaurus/logger": "3.4.0",
     "@docusaurus/mdx-loader": "3.4.0",
     "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/theme-common": "3.4.0",
     "@docusaurus/types": "3.4.0",
     "@docusaurus/utils": "3.4.0",
     "@docusaurus/utils-common": "3.4.0",

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts

@@ -18,7 +18,7 @@ import type {
   GlobalVersion,
   ActivePlugin,
   GlobalDoc,
-} from '@docusaurus/plugin-content-docs/client';
+} from '../index';
 
 describe('docsClientUtils', () => {
   it('getActivePlugin', () => {

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsUtils.test.tsx

@@ -18,8 +18,8 @@ import {
   useSidebarBreadcrumbs,
   isVisibleSidebarItem,
 } from '../docsUtils';
-import {DocsSidebarProvider} from '../../contexts/docsSidebar';
+import {DocsSidebarProvider} from '../docsSidebar';
-import {DocsVersionProvider} from '../../contexts/docsVersion';
+import {DocsVersionProvider} from '../docsVersion';
 import type {
   PropSidebar,
   PropSidebarItem,

packages/docusaurus-plugin-content-docs/src/client/doc.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useMemo, type ReactNode, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropDocContent} from '@docusaurus/plugin-content-docs';
 
 /**

packages/docusaurus-plugin-content-docs/src/client/docSidebarItemsExpandedState.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {type ReactNode, useMemo, useState, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 
 type ContextValue = {
   /**

packages/docusaurus-plugin-content-docs/src/client/docsPreferredVersion.tsx

@@ -20,13 +20,13 @@ import {
   type GlobalVersion,
 } from '@docusaurus/plugin-content-docs/client';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
+import {useThemeConfig, type ThemeConfig} from '@docusaurus/theme-common';
 import {
-  useThemeConfig,
+  ReactContextError,
-  type DocsVersionPersistence,
+  createStorageSlot,
-} from '../utils/useThemeConfig';
+} from '@docusaurus/theme-common/internal';
-import {isDocsPluginEnabled} from '../utils/docsUtils';
+
-import {ReactContextError} from '../utils/reactUtils';
+type DocsVersionPersistence = ThemeConfig['docs']['versionPersistence'];
-import {createStorageSlot} from '../utils/storageUtils';
 
 const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
 
@@ -177,15 +177,12 @@ export function DocsPreferredVersionContextProvider({
 }: {
   children: ReactNode;
 }): JSX.Element {
-  if (isDocsPluginEnabled) {
   return (
     <DocsPreferredVersionContextProviderUnsafe>
       {children}
     </DocsPreferredVersionContextProviderUnsafe>
   );
 }
-  return <>{children}</>;
-}
 
 function useDocsPreferredVersionContext(): ContextValue {
   const value = useContext(Context);

packages/docusaurus-plugin-content-docs/src/client/docsSearch.test.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {docVersionSearchTag} from '../searchUtils';
+import {getDocsVersionSearchTag} from './docsSearch';
 
-describe('docVersionSearchTag', () => {
+describe('getDocsVersionSearchTag', () => {
   it('works', () => {
-    expect(docVersionSearchTag('foo', 'bar')).toBe('docs-foo-bar');
+    expect(getDocsVersionSearchTag('foo', 'bar')).toBe('docs-foo-bar');
   });
 });

packages/docusaurus-plugin-content-docs/src/client/docsSearch.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {useDocsPreferredVersionByPluginId} from './docsPreferredVersion';
+
+/** The search tag to append as each doc's metadata. */
+export function getDocsVersionSearchTag(
+  pluginId: string,
+  versionName: string,
+): string {
+  return `docs-${pluginId}-${versionName}`;
+}
+
+/**
+ * Gets the relevant docs tags to search.
+ * This is the logic that powers the contextual search feature.
+ *
+ * If user is browsing Android 1.4 docs, he'll get presented with:
+ * - Android '1.4' docs
+ * - iOS 'preferred | latest' docs
+ *
+ * The result is generic and not coupled to Algolia/DocSearch on purpose.
+ */
+export function useDocsContextualSearchTags(): string[] {
+  const allDocsData = useAllDocsData();
+  const activePluginAndVersion = useActivePluginAndVersion();
+  const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+
+  // This can't use more specialized hooks because we are mapping over all
+  // plugin instances.
+  function getDocPluginTags(pluginId: string) {
+    const activeVersion =
+      activePluginAndVersion?.activePlugin.pluginId === pluginId
+        ? activePluginAndVersion.activeVersion
+        : undefined;
+
+    const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+
+    const latestVersion = allDocsData[pluginId]!.versions.find(
+      (v) => v.isLast,
+    )!;
+
+    const version = activeVersion ?? preferredVersion ?? latestVersion;
+
+    return getDocsVersionSearchTag(pluginId, version.name);
+  }
+
+  return [...Object.keys(allDocsData).map(getDocPluginTags)];
+}

packages/docusaurus-plugin-content-docs/src/client/docsSidebar.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useMemo, useContext, type ReactNode} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropSidebar} from '@docusaurus/plugin-content-docs';
 
 // Using a Symbol because null is a valid context value (a doc with no sidebar)

packages/docusaurus-plugin-content-docs/src/client/docsUtils.tsx

@@ -9,7 +9,6 @@ import {useMemo} from 'react';
 import {matchPath, useLocation} from '@docusaurus/router';
 import renderRoutes from '@docusaurus/renderRoutes';
 import {
-  useAllDocsData,
   useActivePlugin,
   useActiveDocContext,
   useLatestVersion,
@@ -17,12 +16,13 @@ import {
   type GlobalSidebar,
   type GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
+import {isSamePath} from '@docusaurus/theme-common/internal';
+import {uniq} from '@docusaurus/theme-common';
 import type {Props as DocRootProps} from '@theme/DocRoot';
-import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
+import {useDocsPreferredVersion} from './docsPreferredVersion';
-import {useDocsVersion} from '../contexts/docsVersion';
+import {useDocsVersion} from './docsVersion';
-import {useDocsSidebar} from '../contexts/docsSidebar';
+import {useDocsSidebar} from './docsSidebar';
-import {uniq} from './jsUtils';
+
-import {isSamePath} from './routesUtils';
 import type {
   PropSidebar,
   PropSidebarItem,
@@ -31,9 +31,6 @@ import type {
   PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
 
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;
-
 /**
  * A null-safe way to access a doc's data by ID in the active version.
  */

packages/docusaurus-plugin-content-docs/src/client/docsVersion.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {type ReactNode, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
 
 const Context = React.createContext<PropVersionMetadata | null>(null);

packages/docusaurus-plugin-content-docs/src/client/index.ts

@@ -20,6 +20,45 @@ import {
 } from './docsClientUtils';
 import type {UseDataOptions} from '@docusaurus/types';
 
+export {
+  useDocById,
+  findSidebarCategory,
+  findFirstSidebarItemLink,
+  isActiveSidebarItem,
+  isVisibleSidebarItem,
+  useVisibleSidebarItems,
+  useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRootMetadata,
+  useCurrentSidebarCategory,
+  filterDocCardListItems,
+} from './docsUtils';
+
+export {useDocsPreferredVersion} from './docsPreferredVersion';
+
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './docSidebarItemsExpandedState';
+
+export {DocsVersionProvider, useDocsVersion} from './docsVersion';
+
+export {DocsSidebarProvider, useDocsSidebar} from './docsSidebar';
+
+export {DocProvider, useDoc, type DocContextValue} from './doc';
+
+export {
+  useDocsPreferredVersionByPluginId,
+  DocsPreferredVersionContextProvider,
+} from './docsPreferredVersion';
+
+export {
+  useDocsContextualSearchTags,
+  getDocsVersionSearchTag,
+} from './docsSearch';
+
 export type ActivePlugin = {
   pluginId: string;
   pluginData: GlobalPluginData;

packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/index.tsx

@@ -8,10 +8,8 @@
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {
+import {useSidebarBreadcrumbs} from '@docusaurus/plugin-content-docs/client';
-  useSidebarBreadcrumbs,
+import {useHomePageRoute} from '@docusaurus/theme-common/internal';
-  useHomePageRoute,
-} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import HomeBreadcrumbItem from '@theme/DocBreadcrumbs/Items/Home';

packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx

@@ -9,9 +9,9 @@ import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import {
-  findFirstSidebarItemLink,
   useDocById,
-} from '@docusaurus/theme-common/internal';
+  findFirstSidebarItemLink,
+} from '@docusaurus/plugin-content-docs/client';
 import {usePluralForm} from '@docusaurus/theme-common';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';

packages/docusaurus-theme-classic/src/theme/DocCardList/index.tsx

@@ -10,7 +10,7 @@ import clsx from 'clsx';
 import {
   useCurrentSidebarCategory,
   filterDocCardListItems,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/plugin-content-docs/client';
 import DocCard from '@theme/DocCard';
 import type {Props} from '@theme/DocCardList';
 

packages/docusaurus-theme-classic/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -6,10 +6,8 @@
  */
 
 import React from 'react';
-import {
+import {PageMetadata} from '@docusaurus/theme-common';
-  PageMetadata,
+import {useCurrentSidebarCategory} from '@docusaurus/plugin-content-docs/client';
-  useCurrentSidebarCategory,
-} from '@docusaurus/theme-common';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DocCardList from '@theme/DocCardList';
 import DocPaginator from '@theme/DocPaginator';

packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import Heading from '@theme/Heading';
 import MDXContent from '@theme/MDXContent';
 import type {Props} from '@theme/DocItem/Content';

packages/docusaurus-theme-classic/src/theme/DocItem/Footer/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import TagsListInline from '@theme/TagsListInline';
 
 import EditMetaRow from '@theme/EditMetaRow';

packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {useWindowSize} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import DocItemPaginator from '@theme/DocItem/Paginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';

packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {PageMetadata} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 export default function DocItemMetadata(): JSX.Element {
   const {metadata, frontMatter, assets} = useDoc();

packages/docusaurus-theme-classic/src/theme/DocItem/Paginator/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import DocPaginator from '@theme/DocPaginator';
 
 /**

packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Desktop/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 import TOC from '@theme/TOC';
 

packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Mobile/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 import TOCCollapsible from '@theme/TOCCollapsible';
 

packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {HtmlClassNameProvider} from '@docusaurus/theme-common';
-import {DocProvider} from '@docusaurus/theme-common/internal';
+import {DocProvider} from '@docusaurus/plugin-content-docs/client';
 import DocItemMetadata from '@theme/DocItem/Metadata';
 import DocItemLayout from '@theme/DocItem/Layout';
 import type {Props} from '@theme/DocItem';

packages/docusaurus-theme-classic/src/theme/DocRoot/Layout/Main/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useDocsSidebar} from '@docusaurus/theme-common/internal';
+import {useDocsSidebar} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/DocRoot/Layout/Main';
 
 import styles from './styles.module.css';

packages/docusaurus-theme-classic/src/theme/DocRoot/Layout/Sidebar/index.tsx

@@ -8,7 +8,7 @@
 import React, {type ReactNode, useState, useCallback} from 'react';
 import clsx from 'clsx';
 import {prefersReducedMotion, ThemeClassNames} from '@docusaurus/theme-common';
-import {useDocsSidebar} from '@docusaurus/theme-common/internal';
+import {useDocsSidebar} from '@docusaurus/plugin-content-docs/client';
 import {useLocation} from '@docusaurus/router';
 import DocSidebar from '@theme/DocSidebar';
 import ExpandButton from '@theme/DocRoot/Layout/Sidebar/ExpandButton';

packages/docusaurus-theme-classic/src/theme/DocRoot/Layout/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useState} from 'react';
-import {useDocsSidebar} from '@docusaurus/theme-common/internal';
+import {useDocsSidebar} from '@docusaurus/plugin-content-docs/client';
 import BackToTopButton from '@theme/BackToTopButton';
 import DocRootLayoutSidebar from '@theme/DocRoot/Layout/Sidebar';
 import DocRootLayoutMain from '@theme/DocRoot/Layout/Main';

packages/docusaurus-theme-classic/src/theme/DocRoot/index.tsx

@@ -11,7 +11,7 @@ import {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
 import {
   DocsSidebarProvider,
   useDocRootMetadata,
-} from '@docusaurus/theme-common/internal';
+} from '@docusaurus/plugin-content-docs/client';
 import DocRootLayout from '@theme/DocRoot/Layout';
 import NotFoundContent from '@theme/NotFound/Content';
 import type {Props} from '@theme/DocRoot';

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

@@ -14,12 +14,12 @@ import {
   Collapsible,
   useCollapsible,
 } from '@docusaurus/theme-common';
+import {isSamePath} from '@docusaurus/theme-common/internal';
 import {
   isActiveSidebarItem,
   findFirstSidebarItemLink,
   useDocSidebarItemsExpandedState,
-  isSamePath,
+} from '@docusaurus/plugin-content-docs/client';
-} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import useIsBrowser from '@docusaurus/useIsBrowser';

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {isActiveSidebarItem} from '@docusaurus/theme-common/internal';
+import {isActiveSidebarItem} from '@docusaurus/plugin-content-docs/client';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import IconExternalLink from '@theme/Icon/ExternalLink';

packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx

@@ -9,7 +9,7 @@ import React, {memo} from 'react';
 import {
   DocSidebarItemsExpandedStateProvider,
   useVisibleSidebarItems,
-} from '@docusaurus/theme-common/internal';
+} from '@docusaurus/plugin-content-docs/client';
 import DocSidebarItem from '@theme/DocSidebarItem';
 
 import type {Props} from '@theme/DocSidebarItems';

packages/docusaurus-theme-classic/src/theme/DocVersionBadge/index.tsx

@@ -9,7 +9,7 @@ import React from 'react';
 import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDocsVersion} from '@docusaurus/theme-common/internal';
+import {useDocsVersion} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/DocVersionBadge';
 
 export default function DocVersionBadge({

packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx

@@ -19,7 +19,7 @@ import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
   useDocsPreferredVersion,
   useDocsVersion,
-} from '@docusaurus/theme-common/internal';
+} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/DocVersionBanner';
 import type {
   VersionBanner,

packages/docusaurus-theme-classic/src/theme/DocVersionRoot/index.tsx

@@ -8,9 +8,9 @@
 import React from 'react';
 import {HtmlClassNameProvider, PageMetadata} from '@docusaurus/theme-common';
 import {
-  docVersionSearchTag,
+  getDocsVersionSearchTag,
   DocsVersionProvider,
-} from '@docusaurus/theme-common/internal';
+} from '@docusaurus/plugin-content-docs/client';
 import renderRoutes from '@docusaurus/renderRoutes';
 import SearchMetadata from '@theme/SearchMetadata';
 
@@ -22,7 +22,7 @@ function DocVersionRootMetadata(props: Props): JSX.Element {
     <>
       <SearchMetadata
         version={version.version}
-        tag={docVersionSearchTag(version.pluginId, version.version)}
+        tag={getDocsVersionSearchTag(version.pluginId, version.version)}
       />
       <PageMetadata>
         {version.noIndex && <meta name="robots" content="noindex, nofollow" />}

packages/docusaurus-theme-classic/src/theme/Layout/Provider/index.tsx

@@ -10,11 +10,11 @@ import {composeProviders} from '@docusaurus/theme-common';
 import {
   ColorModeProvider,
   AnnouncementBarProvider,
-  DocsPreferredVersionContextProvider,
   ScrollControllerProvider,
   NavbarProvider,
   PluginHtmlClassNameProvider,
 } from '@docusaurus/theme-common/internal';
+import {DocsPreferredVersionContextProvider} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/Layout/Provider';
 
 const Provider = composeProviders([

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx

@@ -6,8 +6,10 @@
  */
 
 import React from 'react';
-import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
+import {
-import {useLayoutDoc} from '@docusaurus/theme-common/internal';
+  useActiveDocContext,
+  useLayoutDoc,
+} from '@docusaurus/plugin-content-docs/client';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocNavbarItem';
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx

@@ -6,8 +6,10 @@
  */
 
 import React from 'react';
-import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
+import {
-import {useLayoutDocsSidebar} from '@docusaurus/theme-common/internal';
+  useActiveDocContext,
+  useLayoutDocsSidebar,
+} from '@docusaurus/plugin-content-docs/client';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocSidebarNavbarItem';
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

@@ -9,9 +9,9 @@ import React from 'react';
 import {
   useVersions,
   useActiveDocContext,
+  useDocsVersionCandidates,
+  useDocsPreferredVersion,
 } from '@docusaurus/plugin-content-docs/client';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
-import {useDocsVersionCandidates} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
 import {useLocation} from '@docusaurus/router';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionNavbarItem.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useDocsVersionCandidates} from '@docusaurus/theme-common/internal';
+import {useDocsVersionCandidates} from '@docusaurus/plugin-content-docs/client';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocsVersionNavbarItem';
 import type {GlobalVersion} from '@docusaurus/plugin-content-docs/client';

packages/docusaurus-theme-common/package.json

@@ -32,8 +32,6 @@
   "dependencies": {
     "@docusaurus/mdx-loader": "3.4.0",
     "@docusaurus/module-type-aliases": "3.4.0",
-    "@docusaurus/plugin-content-docs": "3.4.0",
-    "@docusaurus/plugin-content-pages": "3.4.0",
     "@docusaurus/utils": "3.4.0",
     "@docusaurus/utils-common": "3.4.0",
     "@types/history": "^4.7.11",
@@ -54,7 +52,8 @@
   },
   "peerDependencies": {
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "@docusaurus/plugin-content-docs": "*"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-theme-common/src/index.ts

@@ -5,6 +5,29 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// TODO Docusaurus v4: remove these workarounds as a breaking change
+//  and remove docs plugin peerDeps in theme-common/package.json
+//  This is public API surface that we need to keep for v3
+//  See https://github.com/facebook/docusaurus/pull/10316
+export function useCurrentSidebarCategory(...args: unknown[]): unknown {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require('@docusaurus/plugin-content-docs/client').useCurrentSidebarCategory(
+    ...args,
+  );
+}
+export function filterDocCardListItems(...args: unknown[]): unknown {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require('@docusaurus/plugin-content-docs/client').filterDocCardListItems(
+    ...args,
+  );
+}
+export function useDocsPreferredVersion(...args: unknown[]): unknown {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require('@docusaurus/plugin-content-docs/client').useDocsPreferredVersion(
+    ...args,
+  );
+}
+
 /*
  * APIs to document
  */
@@ -32,13 +55,6 @@ export {
   listStorageKeys,
 } from './utils/storageUtils';
 
-export {useContextualSearchFilters} from './utils/searchUtils';
-
-export {
-  useCurrentSidebarCategory,
-  filterDocCardListItems,
-} from './utils/docsUtils';
-
 export {usePluralForm} from './utils/usePluralForm';
 
 export {useCollapsible, Collapsible} from './components/Collapsible';
@@ -89,8 +105,6 @@ export {duplicates, uniq, groupBy} from './utils/jsUtils';
 
 export {usePrismTheme} from './hooks/usePrismTheme';
 
-export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';
-
 export {processAdmonitionProps} from './utils/admonitionUtils';
 
 export {

packages/docusaurus-theme-common/src/internal.ts

@@ -18,20 +18,6 @@
 // eslint-disable-next-line no-restricted-syntax
 export * from './index';
 
-export {
-  DocSidebarItemsExpandedStateProvider,
-  useDocSidebarItemsExpandedState,
-} from './contexts/docSidebarItemsExpandedState';
-export {DocsVersionProvider, useDocsVersion} from './contexts/docsVersion';
-export {DocsSidebarProvider, useDocsSidebar} from './contexts/docsSidebar';
-
-export {DocProvider, useDoc, type DocContextValue} from './contexts/doc';
-
-export {
-  useDocsPreferredVersionByPluginId,
-  DocsPreferredVersionContextProvider,
-} from './contexts/docsPreferredVersion';
-
 export {
   AnnouncementBarProvider,
   useAnnouncementBar,
@@ -54,22 +40,7 @@ export {
   containsLineNumbers,
 } from './utils/codeBlockUtils';
 
-export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+export {DEFAULT_SEARCH_TAG} from './utils/searchUtils';
-
-export {
-  isDocsPluginEnabled,
-  useDocById,
-  findSidebarCategory,
-  findFirstSidebarItemLink,
-  isActiveSidebarItem,
-  isVisibleSidebarItem,
-  useVisibleSidebarItems,
-  useSidebarBreadcrumbs,
-  useDocsVersionCandidates,
-  useLayoutDoc,
-  useLayoutDocsSidebar,
-  useDocRootMetadata,
-} from './utils/docsUtils';
 
 export {useTitleFormatter} from './utils/generalUtils';
 

packages/docusaurus-theme-common/src/types.d.ts

@@ -6,4 +6,3 @@
  */
 
 /// <reference types="@docusaurus/module-type-aliases" />
-/// <reference types="@docusaurus/plugin-content-docs" />

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

@@ -5,62 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  useAllDocsData,
-  useActivePluginAndVersion,
-} from '@docusaurus/plugin-content-docs/client';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useDocsPreferredVersionByPluginId} from '../contexts/docsPreferredVersion';
-
 export const DEFAULT_SEARCH_TAG = 'default';
-
-/** The search tag to append as each doc's metadata. */
-export function docVersionSearchTag(
-  pluginId: string,
-  versionName: string,
-): string {
-  return `docs-${pluginId}-${versionName}`;
-}
-
-/**
- * Gets the relevant context information for contextual search.
- *
- * The value is generic and not coupled to Algolia/DocSearch, since we may want
- * to support multiple search engines, or allowing users to use their own search
- * engine solution.
- */
-export function useContextualSearchFilters(): {locale: string; tags: string[]} {
-  const {i18n} = useDocusaurusContext();
-  const allDocsData = useAllDocsData();
-  const activePluginAndVersion = useActivePluginAndVersion();
-  const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
-
-  // This can't use more specialized hooks because we are mapping over all
-  // plugin instances.
-  function getDocPluginTags(pluginId: string) {
-    const activeVersion =
-      activePluginAndVersion?.activePlugin.pluginId === pluginId
-        ? activePluginAndVersion.activeVersion
-        : undefined;
-
-    const preferredVersion = docsPreferredVersionByPluginId[pluginId];
-
-    const latestVersion = allDocsData[pluginId]!.versions.find(
-      (v) => v.isLast,
-    )!;
-
-    const version = activeVersion ?? preferredVersion ?? latestVersion;
-
-    return docVersionSearchTag(pluginId, version.name);
-  }
-
-  const tags = [
-    DEFAULT_SEARCH_TAG,
-    ...Object.keys(allDocsData).map(getDocPluginTags),
-  ];
-
-  return {
-    locale: i18n.currentLocale,
-    tags,
-  };
-}

packages/docusaurus-theme-search-algolia/src/client/useAlgoliaContextualFacetFilters.ts

@@ -5,11 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useContextualSearchFilters} from '@docusaurus/theme-common';
+import {DEFAULT_SEARCH_TAG} from '@docusaurus/theme-common/internal';
+import {useDocsContextualSearchTags} from '@docusaurus/plugin-content-docs/client';
+import useDocusaurusContext from '@docusaurus/core/src/client/exports/useDocusaurusContext';
 
-// Translate search-engine agnostic search filters to Algolia search filters
+function useSearchTags() {
+  // only docs have custom search tags per version
+  const docsTags = useDocsContextualSearchTags();
+  return [DEFAULT_SEARCH_TAG, ...docsTags];
+}
+
+// Translate search-engine agnostic search tags to Algolia search filters
 export function useAlgoliaContextualFacetFilters(): [string, string[]] {
-  const {locale, tags} = useContextualSearchFilters();
+  const locale = useDocusaurusContext().i18n.currentLocale;
+  const tags = useSearchTags();
 
   // Seems safe to convert locale->language, see AlgoliaSearchMetadata comment
   const languageFilter = `language:${locale}`;

website/src/components/Versions.tsx

@@ -12,8 +12,10 @@ import React, {
   useRef,
   type ReactNode,
 } from 'react';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {
-import {useVersions} from '@docusaurus/plugin-content-docs/client';
+  useVersions,
+  useDocsPreferredVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import Translate from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import CodeBlock from '@theme/CodeBlock';

website/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useLayoutDoc} from '@docusaurus/theme-common/internal';
+import {useLayoutDoc} from '@docusaurus/plugin-content-docs/client';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import DocCategoryGeneratedIndexPage from '@theme-original/DocCategoryGeneratedIndexPage';