mirror of
https://github.com/facebook/docusaurus.git
synced 2025-07-31 07:18:59 +02:00
feat(content-docs): sidebar category linking to document or auto-generated index page (#5830)
Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: Armano <armano2@users.noreply.github.com> Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
95f911efef
commit
cfae5d0933
105 changed files with 3904 additions and 816 deletions
|
|
@ -32,7 +32,18 @@ export {
|
|||
|
||||
export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
|
||||
|
||||
export {isDocsPluginEnabled} from './utils/docsUtils';
|
||||
export {
|
||||
isDocsPluginEnabled,
|
||||
DocsVersionProvider,
|
||||
useDocsVersion,
|
||||
useDocById,
|
||||
DocsSidebarProvider,
|
||||
useDocsSidebar,
|
||||
findSidebarCategory,
|
||||
findFirstCategoryLink,
|
||||
useCurrentSidebarCategory,
|
||||
isActiveSidebarItem,
|
||||
} from './utils/docsUtils';
|
||||
|
||||
export {isSamePath} from './utils/pathUtils';
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,331 @@
|
|||
/**
|
||||
* 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 {renderHook} from '@testing-library/react-hooks';
|
||||
import {
|
||||
findFirstCategoryLink,
|
||||
isActiveSidebarItem,
|
||||
DocsVersionProvider,
|
||||
useDocsVersion,
|
||||
useDocById,
|
||||
useDocsSidebar,
|
||||
DocsSidebarProvider,
|
||||
findSidebarCategory,
|
||||
} from '../docsUtils';
|
||||
import {
|
||||
PropSidebar,
|
||||
PropSidebarItem,
|
||||
PropSidebarItemCategory,
|
||||
PropVersionMetadata,
|
||||
} from '@docusaurus/plugin-content-docs';
|
||||
|
||||
// Make tests more readable with some useful category item defaults
|
||||
function testCategory(
|
||||
data?: Partial<PropSidebarItemCategory>,
|
||||
): PropSidebarItemCategory {
|
||||
return {
|
||||
type: 'category',
|
||||
href: undefined,
|
||||
label: 'Category label',
|
||||
items: [],
|
||||
collapsed: true,
|
||||
collapsible: true,
|
||||
...data,
|
||||
};
|
||||
}
|
||||
|
||||
function testVersion(data?: Partial<PropVersionMetadata>): PropVersionMetadata {
|
||||
return {
|
||||
version: 'versionName',
|
||||
label: 'Version Label',
|
||||
className: 'version className',
|
||||
badge: true,
|
||||
banner: 'unreleased',
|
||||
docs: {},
|
||||
docsSidebars: {},
|
||||
isLast: false,
|
||||
pluginId: 'default',
|
||||
...data,
|
||||
};
|
||||
}
|
||||
|
||||
describe('docsUtils', () => {
|
||||
describe('useDocsVersion', () => {
|
||||
test('should throw if context provider is missing', () => {
|
||||
expect(
|
||||
() => renderHook(() => useDocsVersion()).result.current,
|
||||
).toThrowErrorMatchingInlineSnapshot(
|
||||
`"This hook requires usage of <DocsVersionProvider>"`,
|
||||
);
|
||||
});
|
||||
|
||||
test('should read value from context provider', () => {
|
||||
const version = testVersion();
|
||||
const {result} = renderHook(() => useDocsVersion(), {
|
||||
wrapper: ({children}) => (
|
||||
<DocsVersionProvider version={version}>
|
||||
{children}
|
||||
</DocsVersionProvider>
|
||||
),
|
||||
});
|
||||
expect(result.current).toBe(version);
|
||||
});
|
||||
});
|
||||
|
||||
describe('useDocsSidebar', () => {
|
||||
test('should throw if context provider is missing', () => {
|
||||
expect(
|
||||
() => renderHook(() => useDocsSidebar()).result.current,
|
||||
).toThrowErrorMatchingInlineSnapshot(
|
||||
`"This hook requires usage of <DocsSidebarProvider>"`,
|
||||
);
|
||||
});
|
||||
|
||||
test('should read value from context provider', () => {
|
||||
const sidebar: PropSidebar = [];
|
||||
const {result} = renderHook(() => useDocsSidebar(), {
|
||||
wrapper: ({children}) => (
|
||||
<DocsSidebarProvider sidebar={sidebar}>
|
||||
{children}
|
||||
</DocsSidebarProvider>
|
||||
),
|
||||
});
|
||||
expect(result.current).toBe(sidebar);
|
||||
});
|
||||
});
|
||||
|
||||
describe('useDocById', () => {
|
||||
const version = testVersion({
|
||||
docs: {
|
||||
doc1: {
|
||||
id: 'doc1',
|
||||
title: 'Doc 1',
|
||||
description: 'desc1',
|
||||
sidebar: 'sidebar1',
|
||||
},
|
||||
doc2: {
|
||||
id: 'doc2',
|
||||
title: 'Doc 2',
|
||||
description: 'desc2',
|
||||
sidebar: 'sidebar2',
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
function callHook(docId: string | undefined) {
|
||||
const {result} = renderHook(() => useDocById(docId), {
|
||||
wrapper: ({children}) => (
|
||||
<DocsVersionProvider version={version}>
|
||||
{children}
|
||||
</DocsVersionProvider>
|
||||
),
|
||||
});
|
||||
return result.current;
|
||||
}
|
||||
|
||||
test('should accept undefined', () => {
|
||||
expect(callHook(undefined)).toBeUndefined();
|
||||
});
|
||||
|
||||
test('should find doc1', () => {
|
||||
expect(callHook('doc1')).toMatchObject({id: 'doc1'});
|
||||
});
|
||||
test('should find doc2', () => {
|
||||
expect(callHook('doc2')).toMatchObject({id: 'doc2'});
|
||||
});
|
||||
|
||||
test('should throw for doc3', () => {
|
||||
expect(() => callHook('doc3')).toThrowErrorMatchingInlineSnapshot(
|
||||
`"no version doc found by id=doc3"`,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('findSidebarCategory', () => {
|
||||
test('should be able to return undefined', () => {
|
||||
expect(findSidebarCategory([], () => false)).toBeUndefined();
|
||||
expect(
|
||||
findSidebarCategory([testCategory(), testCategory()], () => false),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
test('should return first element matching predicate', () => {
|
||||
const first = testCategory();
|
||||
const second = testCategory();
|
||||
const third = testCategory();
|
||||
const sidebar = [first, second, third];
|
||||
expect(findSidebarCategory(sidebar, () => true)).toEqual(first);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === first)).toEqual(
|
||||
first,
|
||||
);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === second)).toEqual(
|
||||
second,
|
||||
);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === third)).toEqual(
|
||||
third,
|
||||
);
|
||||
});
|
||||
|
||||
test('should be able to search in sub items', () => {
|
||||
const subsub1 = testCategory();
|
||||
const subsub2 = testCategory();
|
||||
const sub1 = testCategory({
|
||||
items: [subsub1, subsub2],
|
||||
});
|
||||
const sub2 = testCategory();
|
||||
const parent = testCategory({
|
||||
items: [sub1, sub2],
|
||||
});
|
||||
const sidebar = [parent];
|
||||
|
||||
expect(findSidebarCategory(sidebar, () => true)).toEqual(parent);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === sub1)).toEqual(
|
||||
sub1,
|
||||
);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === sub2)).toEqual(
|
||||
sub2,
|
||||
);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === subsub1)).toEqual(
|
||||
subsub1,
|
||||
);
|
||||
expect(findSidebarCategory(sidebar, (item) => item === subsub2)).toEqual(
|
||||
subsub2,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('findFirstCategoryLink', () => {
|
||||
test('category without link nor child', () => {
|
||||
expect(
|
||||
findFirstCategoryLink(
|
||||
testCategory({
|
||||
href: undefined,
|
||||
}),
|
||||
),
|
||||
).toEqual(undefined);
|
||||
});
|
||||
|
||||
test('category with link', () => {
|
||||
expect(
|
||||
findFirstCategoryLink(
|
||||
testCategory({
|
||||
href: '/itemPath',
|
||||
}),
|
||||
),
|
||||
).toEqual('/itemPath');
|
||||
});
|
||||
|
||||
test('category with deeply nested category link', () => {
|
||||
expect(
|
||||
findFirstCategoryLink(
|
||||
testCategory({
|
||||
href: undefined,
|
||||
items: [
|
||||
testCategory({
|
||||
href: undefined,
|
||||
items: [
|
||||
testCategory({
|
||||
href: '/itemPath',
|
||||
}),
|
||||
],
|
||||
}),
|
||||
],
|
||||
}),
|
||||
),
|
||||
).toEqual('/itemPath');
|
||||
});
|
||||
|
||||
test('category with deeply nested link', () => {
|
||||
expect(
|
||||
findFirstCategoryLink(
|
||||
testCategory({
|
||||
href: undefined,
|
||||
items: [
|
||||
testCategory({
|
||||
href: undefined,
|
||||
items: [{type: 'link', href: '/itemPath', label: 'Label'}],
|
||||
}),
|
||||
],
|
||||
}),
|
||||
),
|
||||
).toEqual('/itemPath');
|
||||
});
|
||||
});
|
||||
|
||||
describe('isActiveSidebarItem', () => {
|
||||
test('with link href', () => {
|
||||
const item: PropSidebarItem = {
|
||||
type: 'link',
|
||||
href: '/itemPath',
|
||||
label: 'Label',
|
||||
};
|
||||
|
||||
expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
|
||||
|
||||
expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
|
||||
|
||||
// Ensure it's not trailing slash sensitive:
|
||||
expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
|
||||
expect(
|
||||
isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
|
||||
).toEqual(true);
|
||||
});
|
||||
|
||||
test('with category href', () => {
|
||||
const item: PropSidebarItem = testCategory({
|
||||
href: '/itemPath',
|
||||
});
|
||||
|
||||
expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
|
||||
|
||||
expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
|
||||
|
||||
// Ensure it's not trailing slash sensitive:
|
||||
expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
|
||||
expect(
|
||||
isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
|
||||
).toEqual(true);
|
||||
});
|
||||
|
||||
test('with category nested items', () => {
|
||||
const item: PropSidebarItem = testCategory({
|
||||
href: '/category-path',
|
||||
items: [
|
||||
{
|
||||
type: 'link',
|
||||
href: '/sub-link-path',
|
||||
label: 'Label',
|
||||
},
|
||||
testCategory({
|
||||
href: '/sub-category-path',
|
||||
items: [
|
||||
{
|
||||
type: 'link',
|
||||
href: '/sub-sub-link-path',
|
||||
label: 'Label',
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
|
||||
expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
|
||||
|
||||
expect(isActiveSidebarItem(item, '/category-path')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-link-path')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-category-path')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-sub-link-path')).toEqual(true);
|
||||
|
||||
// Ensure it's not trailing slash sensitive:
|
||||
expect(isActiveSidebarItem(item, '/category-path/')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-link-path/')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-category-path/')).toEqual(true);
|
||||
expect(isActiveSidebarItem(item, '/sub-sub-link-path/')).toEqual(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -1,11 +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.
|
||||
*/
|
||||
|
||||
import {useAllDocsData} from '@theme/hooks/useDocs';
|
||||
|
||||
// TODO not ideal, see also "useDocs"
|
||||
export const isDocsPluginEnabled: boolean = !!useAllDocsData;
|
||||
185
packages/docusaurus-theme-common/src/utils/docsUtils.tsx
Normal file
185
packages/docusaurus-theme-common/src/utils/docsUtils.tsx
Normal file
|
|
@ -0,0 +1,185 @@
|
|||
/**
|
||||
* 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, {createContext, ReactNode, useContext} from 'react';
|
||||
import {useAllDocsData} from '@theme/hooks/useDocs';
|
||||
import {
|
||||
PropSidebar,
|
||||
PropSidebarItem,
|
||||
PropSidebarItemCategory,
|
||||
PropVersionDoc,
|
||||
PropVersionMetadata,
|
||||
} from '@docusaurus/plugin-content-docs';
|
||||
import {isSamePath} from './pathUtils';
|
||||
import {useLocation} from '@docusaurus/router';
|
||||
|
||||
// TODO not ideal, see also "useDocs"
|
||||
export const isDocsPluginEnabled: boolean = !!useAllDocsData;
|
||||
|
||||
// Using a Symbol because null is a valid context value (a doc can have no sidebar)
|
||||
// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
|
||||
const EmptyContextValue: unique symbol = Symbol('EmptyContext');
|
||||
|
||||
const DocsVersionContext = createContext<
|
||||
PropVersionMetadata | typeof EmptyContextValue
|
||||
>(EmptyContextValue);
|
||||
|
||||
export function DocsVersionProvider({
|
||||
children,
|
||||
version,
|
||||
}: {
|
||||
children: ReactNode;
|
||||
version: PropVersionMetadata | typeof EmptyContextValue;
|
||||
}): JSX.Element {
|
||||
return (
|
||||
<DocsVersionContext.Provider value={version}>
|
||||
{children}
|
||||
</DocsVersionContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
export function useDocsVersion(): PropVersionMetadata {
|
||||
const version = useContext(DocsVersionContext);
|
||||
if (version === EmptyContextValue) {
|
||||
throw new Error('This hook requires usage of <DocsVersionProvider>');
|
||||
}
|
||||
return version;
|
||||
}
|
||||
|
||||
export function useDocById(id: string): PropVersionDoc;
|
||||
export function useDocById(id: string | undefined): PropVersionDoc | undefined;
|
||||
export function useDocById(id: string | undefined): PropVersionDoc | undefined {
|
||||
const version = useDocsVersion();
|
||||
if (!id) {
|
||||
return undefined;
|
||||
}
|
||||
const doc = version.docs[id];
|
||||
if (!doc) {
|
||||
throw new Error(`no version doc found by id=${id}`);
|
||||
}
|
||||
return doc;
|
||||
}
|
||||
|
||||
const DocsSidebarContext = createContext<
|
||||
PropSidebar | null | typeof EmptyContextValue
|
||||
>(EmptyContextValue);
|
||||
|
||||
export function DocsSidebarProvider({
|
||||
children,
|
||||
sidebar,
|
||||
}: {
|
||||
children: ReactNode;
|
||||
sidebar: PropSidebar | null;
|
||||
}): JSX.Element {
|
||||
return (
|
||||
<DocsSidebarContext.Provider value={sidebar}>
|
||||
{children}
|
||||
</DocsSidebarContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
export function useDocsSidebar(): PropSidebar | null {
|
||||
const sidebar = useContext(DocsSidebarContext);
|
||||
if (sidebar === EmptyContextValue) {
|
||||
throw new Error('This hook requires usage of <DocsSidebarProvider>');
|
||||
}
|
||||
return sidebar;
|
||||
}
|
||||
|
||||
// Use the components props and the sidebar in context
|
||||
// to get back the related sidebar category that we want to render
|
||||
export function findSidebarCategory(
|
||||
sidebar: PropSidebar,
|
||||
predicate: (category: PropSidebarItemCategory) => boolean,
|
||||
): PropSidebarItemCategory | undefined {
|
||||
// eslint-disable-next-line no-restricted-syntax
|
||||
for (const item of sidebar) {
|
||||
if (item.type === 'category') {
|
||||
if (predicate(item)) {
|
||||
return item;
|
||||
} else {
|
||||
const subItem = findSidebarCategory(item.items, predicate);
|
||||
if (subItem) {
|
||||
return subItem;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
// If a category card has no link => link to the first subItem having a link
|
||||
export function findFirstCategoryLink(
|
||||
item: PropSidebarItemCategory,
|
||||
): string | undefined {
|
||||
if (item.href) {
|
||||
return item.href;
|
||||
}
|
||||
|
||||
// eslint-disable-next-line no-restricted-syntax
|
||||
for (const subItem of item.items) {
|
||||
if (subItem.type === 'link') {
|
||||
return subItem.href;
|
||||
}
|
||||
if (subItem.type === 'category') {
|
||||
const categoryLink = findFirstCategoryLink(subItem);
|
||||
if (categoryLink) {
|
||||
return categoryLink;
|
||||
}
|
||||
} else {
|
||||
throw new Error(
|
||||
`Unexpected category item type for ${JSON.stringify(subItem)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
export function useCurrentSidebarCategory(): PropSidebarItemCategory {
|
||||
const {pathname} = useLocation();
|
||||
const sidebar = useDocsSidebar();
|
||||
if (!sidebar) {
|
||||
throw new Error('Unexpected: cant find current sidebar in context');
|
||||
}
|
||||
const category = findSidebarCategory(sidebar, (item) =>
|
||||
isSamePath(item.href, pathname),
|
||||
);
|
||||
if (!category) {
|
||||
throw new Error(
|
||||
`Unexpected: sidebar category could not be found for pathname='${pathname}'.
|
||||
Hook useCurrentSidebarCategory() should only be used on Category pages`,
|
||||
);
|
||||
}
|
||||
return category;
|
||||
}
|
||||
|
||||
function containsActiveSidebarItem(
|
||||
items: PropSidebarItem[],
|
||||
activePath: string,
|
||||
): boolean {
|
||||
return items.some((subItem) => isActiveSidebarItem(subItem, activePath));
|
||||
}
|
||||
|
||||
export function isActiveSidebarItem(
|
||||
item: PropSidebarItem,
|
||||
activePath: string,
|
||||
): boolean {
|
||||
const isActive = (testedPath: string | undefined) =>
|
||||
typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
|
||||
|
||||
if (item.type === 'link') {
|
||||
return isActive(item.href);
|
||||
}
|
||||
|
||||
if (item.type === 'category') {
|
||||
return (
|
||||
isActive(item.href) || containsActiveSidebarItem(item.items, activePath)
|
||||
);
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue