Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 23 commits into from
Jul 23, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .github/workflows/tests-e2e.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
3 changes: 2 additions & 1 deletion packages/docusaurus-plugin-content-blog/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ import type {
GlobalVersion,
ActivePlugin,
GlobalDoc,
} from '@docusaurus/plugin-content-docs/client';
} from '../index';

describe('docsClientUtils', () => {
it('getActivePlugin', () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ import {
useSidebarBreadcrumbs,
isVisibleSidebarItem,
} from '../docsUtils';
import {DocsSidebarProvider} from '../../contexts/docsSidebar';
import {DocsVersionProvider} from '../../contexts/docsVersion';
import {DocsSidebarProvider} from '../docsSidebar';
import {DocsVersionProvider} from '../docsVersion';
import type {
PropSidebar,
PropSidebarItem,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
type DocsVersionPersistence,
} from '../utils/useThemeConfig';
import {isDocsPluginEnabled} from '../utils/docsUtils';
import {ReactContextError} from '../utils/reactUtils';
import {createStorageSlot} from '../utils/storageUtils';
ReactContextError,
createStorageSlot,
} from '@docusaurus/theme-common/internal';

type DocsVersionPersistence = ThemeConfig['docs']['versionPersistence'];

const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;

Expand Down Expand Up @@ -177,14 +177,11 @@ export function DocsPreferredVersionContextProvider({
}: {
children: ReactNode;
}): JSX.Element {
if (isDocsPluginEnabled) {
return (
<DocsPreferredVersionContextProviderUnsafe>
{children}
</DocsPreferredVersionContextProviderUnsafe>
);
}
return <>{children}</>;
return (
<DocsPreferredVersionContextProviderUnsafe>
{children}
</DocsPreferredVersionContextProviderUnsafe>
);
}

function useDocsPreferredVersionContext(): ContextValue {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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');
});
});
Original file line number Diff line number Diff line change
@@ -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)];
}
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@ import {useMemo} from 'react';
import {matchPath, useLocation} from '@docusaurus/router';
import renderRoutes from '@docusaurus/renderRoutes';
import {
useAllDocsData,
useActivePlugin,
useActiveDocContext,
useLatestVersion,
type GlobalVersion,
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 {useDocsVersion} from '../contexts/docsVersion';
import {useDocsSidebar} from '../contexts/docsSidebar';
import {uniq} from './jsUtils';
import {isSamePath} from './routesUtils';
import {useDocsPreferredVersion} from './docsPreferredVersion';
import {useDocsVersion} from './docsVersion';
import {useDocsSidebar} from './docsSidebar';

import type {
PropSidebar,
PropSidebarItem,
Expand All @@ -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.
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
39 changes: 39 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/client/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,8 @@
import React, {type ReactNode} from 'react';
import clsx from 'clsx';
import {ThemeClassNames} from '@docusaurus/theme-common';
import {
useSidebarBreadcrumbs,
useHomePageRoute,
} from '@docusaurus/theme-common/internal';
import {useSidebarBreadcrumbs} from '@docusaurus/plugin-content-docs/client';
import {useHomePageRoute} from '@docusaurus/theme-common/internal';
import Link from '@docusaurus/Link';
import {translate} from '@docusaurus/Translate';
import HomeBreadcrumbItem from '@theme/DocBreadcrumbs/Items/Home';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,8 @@
*/

import React from 'react';
import {
PageMetadata,
useCurrentSidebarCategory,
} from '@docusaurus/theme-common';
import {PageMetadata} from '@docusaurus/theme-common';
import {useCurrentSidebarCategory} from '@docusaurus/plugin-content-docs/client';
import useBaseUrl from '@docusaurus/useBaseUrl';
import DocCardList from '@theme/DocCardList';
import DocPaginator from '@theme/DocPaginator';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down
Loading