refactor: new @docusaurus/plugin-content-docs/client interface (#6287)

jest.config.js

@@ -44,5 +44,9 @@ module.exports = {
     // TODO maybe use "projects" + multiple configs if we plan to add tests to another theme?
     '@theme/(.*)': '@docusaurus/theme-classic/src/theme/$1',
     '@site/(.*)': 'website/$1',
+
+    // TODO why Jest can't figure node package entry points?
+    '@docusaurus/plugin-content-docs/client':
+      '@docusaurus/plugin-content-docs/lib/client/index.js',
   },
 };

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

@@ -3,6 +3,10 @@
   "version": "2.0.0-beta.14",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
+  "exports": {
+    "./client": "./lib/client/index.js",
+    ".": "./lib/index.js"
+  },
   "types": "src/plugin-content-docs.d.ts",
   "scripts": {
     "build": "tsc",

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

@@ -11,7 +11,7 @@ import useGlobalData, {
   usePluginData,
 } from '@docusaurus/useGlobalData';
 
-import type {GlobalPluginData, GlobalVersion} from '../../types';
+import type {GlobalPluginData, GlobalVersion} from '../types';
 import {
   getActivePlugin,
   getLatestVersion,
@@ -22,7 +22,7 @@ import {
   type ActiveDocContext,
   type DocVersionSuggestions,
   type GetActivePluginOptions,
-} from '../../client/docsClientUtils';
+} from './docsClientUtils';
 
 // Important to use a constant object to avoid React useEffect executions etc...,
 // see https://github.com/facebook/docusaurus/issues/5089
@@ -37,6 +37,7 @@ export const useAllDocsData = (): Record<string, GlobalPluginData> =>
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
 
+// TODO this feature should be provided by docusaurus core
 export const useActivePlugin = (
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined => {

packages/docusaurus-plugin-content-docs/src/client/index.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.
+ */
+
+export * from './globalDataHooks';

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

@@ -79,14 +79,6 @@ export default async function pluginContentDocs(
   return {
     name: 'docusaurus-plugin-content-docs',
 
-    getThemePath() {
-      return path.resolve(__dirname, './theme');
-    },
-
-    getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
-    },
-
     extendCli(cli) {
       const isDefaultPluginId = pluginId === DEFAULT_PLUGIN_ID;
 

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -241,7 +241,8 @@ declare module '@theme/Seo' {
   export default Seo;
 }
 
-declare module '@theme/hooks/useDocs' {
+// TODO can't we infer types directly from code?
+declare module '@docusaurus/plugin-content-docs/client' {
   type GlobalPluginData = import('./types').GlobalPluginData;
   type GlobalVersion = import('./types').GlobalVersion;
   type ActivePlugin = import('./client/docsClientUtils').ActivePlugin;

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

@@ -171,10 +171,6 @@ export default function docusaurusThemeClassic(
         .join('|');
 
       return {
-        ignoreWarnings: [
-          // See https://github.com/facebook/docusaurus/pull/3382
-          (e) => e.message.includes("Can't resolve '@theme-init/hooks/useDocs"),
-        ],
         plugins: [
           new ContextReplacementPlugin(
             /prismjs[\\/]components$/,

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

@@ -13,7 +13,7 @@ import {
   useActivePlugin,
   useDocVersionSuggestions,
   type GlobalVersion,
-} from '@theme/hooks/useDocs';
+} from '@docusaurus/plugin-content-docs/client';
 import {
   ThemeClassNames,
   useDocsPreferredVersion,

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

@@ -20,7 +20,7 @@ import {
 import useHideableNavbar from '@theme/hooks/useHideableNavbar';
 import useLockBodyScroll from '@theme/hooks/useLockBodyScroll';
 import useWindowSize from '@theme/hooks/useWindowSize';
-import {useActivePlugin} from '@theme/hooks/useDocs';
+import {useActivePlugin} from '@docusaurus/plugin-content-docs/client';
 import NavbarItem, {type Props as NavbarItemConfig} from '@theme/NavbarItem';
 import Logo from '@theme/Logo';
 import IconMenu from '@theme/IconMenu';

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

@@ -7,7 +7,10 @@
 
 import React from 'react';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
-import {useLatestVersion, useActiveDocContext} from '@theme/hooks/useDocs';
+import {
+  useLatestVersion,
+  useActiveDocContext,
+} from '@docusaurus/plugin-content-docs/client';
 import clsx from 'clsx';
 import {getInfimaActiveClassName} from '@theme/NavbarItem/utils';
 import type {Props} from '@theme/NavbarItem/DocNavbarItem';

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

@@ -7,7 +7,10 @@
 
 import React from 'react';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
-import {useLatestVersion, useActiveDocContext} from '@theme/hooks/useDocs';
+import {
+  useLatestVersion,
+  useActiveDocContext,
+} from '@docusaurus/plugin-content-docs/client';
 import clsx from 'clsx';
 import {getInfimaActiveClassName} from '@theme/NavbarItem/utils';
 import {useDocsPreferredVersion, uniq} from '@docusaurus/theme-common';

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

@@ -12,7 +12,7 @@ import {
   useVersions,
   useLatestVersion,
   useActiveDocContext,
-} from '@theme/hooks/useDocs';
+} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 import {translate} from '@docusaurus/Translate';

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

@@ -11,7 +11,7 @@ import {
   useActiveVersion,
   useLatestVersion,
   type GlobalVersion,
-} from '@theme/hooks/useDocs';
+} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/NavbarItem/DocsVersionNavbarItem';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 

packages/docusaurus-theme-classic/src/theme/hooks/useDocs.ts

@@ -1,12 +0,0 @@
-/**
- * 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.
- */
-
-// Re-expose useDocs
-// Ensure it's always statically available even if user is not using the docs plugin
-// Problem reported for the blog-only mode: https://github.com/facebook/docusaurus/issues/3360
-// eslint-disable-next-line import/no-named-export
-export * from '@docusaurus/plugin-content-docs/lib/theme/hooks/useDocs';

packages/docusaurus-theme-common/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -16,7 +16,10 @@ import React, {
 import {useThemeConfig, type DocsVersionPersistence} from '../useThemeConfig';
 import {isDocsPluginEnabled} from '../docsUtils';
 
-import {useAllDocsData, type GlobalPluginData} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  type GlobalPluginData,
+} from '@docusaurus/plugin-content-docs/client';
 
 import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
 

packages/docusaurus-theme-common/src/utils/docsPreferredVersion/useDocsPreferredVersion.ts

@@ -11,7 +11,7 @@ import {
   useAllDocsData,
   useDocsData,
   type GlobalVersion,
-} from '@theme/hooks/useDocs';
+} from '@docusaurus/plugin-content-docs/client';
 
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
 

packages/docusaurus-theme-common/src/utils/docsUtils.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {createContext, type ReactNode, useContext} from 'react';
-import {useAllDocsData} from '@theme/hooks/useDocs';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import type {
   PropSidebar,
   PropSidebarItem,

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

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useAllDocsData, useActivePluginAndVersion} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import {useDocsPreferredVersionByPluginId} from './docsPreferredVersion/useDocsPreferredVersion';
 import {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './searchUtils';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx

@@ -24,7 +24,7 @@ import {
   useDynamicCallback,
 } from '@docusaurus/theme-common';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAllDocsData} from '@theme/hooks/useDocs';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import useSearchQuery from '@theme/hooks/useSearchQuery';
 import Layout from '@theme/Layout';
 import Translate, {translate} from '@docusaurus/Translate';

website/src/pages/versions.tsx

@@ -10,7 +10,10 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Layout from '@theme/Layout';
 
-import {useVersions, useLatestVersion} from '@theme/hooks/useDocs';
+import {
+  useVersions,
+  useLatestVersion,
+} from '@docusaurus/plugin-content-docs/client';
 
 import VersionsArchived from '@site/versionsArchived.json';