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.

Sign up for GitHub

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

Jump to bottom

refactor(theme-classic): move all sidebar-related config under themeConfig.docs.sidebar #7277

Merged
merged 1 commit into from
May 4, 2022
Merged

refactor(theme-classic): move all sidebar-related config under themeConfig.docs.sidebar #7277

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 0 additions & 1 deletion packages/docusaurus-theme-classic/src/__tests__/__snapshots__/translations.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,6 @@ exports[`translateThemeConfig returns translated themeConfig 1`] = `
],
"style": "light",
},
"hideableSidebar": true,
"navbar": {
"hideOnScroll": false,
"items": [
Expand Down
1 change: 0 additions & 1 deletion packages/docusaurus-theme-classic/src/__tests__/translations.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ const ThemeConfigSample: ThemeConfig = {
docs: {
versionPersistence: 'none',
},
hideableSidebar: true,
navbar: {
title: 'navbar title',
style: 'dark',
Expand Down
20 changes: 20 additions & 0 deletions packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,13 @@ describe('themeConfig', () => {
defaultLanguage: 'javascript',
additionalLanguages: ['kotlin', 'java'],
},
docs: {
versionPersistence: 'localStorage',
sidebar: {
hideable: true,
autoCollapseCategories: false,
},
},
announcementBar: {
id: 'supports',
content: 'pls support',
Expand Down Expand Up @@ -101,6 +108,19 @@ describe('themeConfig', () => {
});
});

it('rejects outdated sidebar options', () => {
expect(() =>
testValidateThemeConfig({hideableSidebar: true}),
).toThrowErrorMatchingInlineSnapshot(
`"themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable."`,
);
expect(() =>
testValidateThemeConfig({autoCollapseSidebarCategories: true}),
).toThrowErrorMatchingInlineSnapshot(
`"themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories."`,
);
});

it('allows possible types of navbar items', () => {
const config = {
navbar: {
Expand Down
6 changes: 4 additions & 2 deletions packages/docusaurus-theme-classic/src/theme/DocSidebar/Desktop/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@ import styles from './styles.module.css';
function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
const {
navbar: {hideOnScroll},
hideableSidebar,
docs: {
sidebar: {hideable},
},
} = useThemeConfig();

return (
Expand All @@ -30,7 +32,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
)}>
{hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
<Content path={path} sidebar={sidebar} />
{hideableSidebar && <CollapseButton onClick={onCollapse} />}
{hideable && <CollapseButton onClick={onCollapse} />}
</div>
);
}
Expand Down
16 changes: 7 additions & 9 deletions packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,23 +127,21 @@ export default function DocSidebarItemCategory({
setExpandedItem(toCollapsed ? null : index);
setCollapsed(toCollapsed);
}
const {autoCollapseSidebarCategories} = useThemeConfig();
const {
docs: {
sidebar: {autoCollapseCategories},
},
} = useThemeConfig();
useEffect(() => {
if (
collapsible &&
expandedItem &&
expandedItem !== index &&
autoCollapseSidebarCategories
autoCollapseCategories
) {
setCollapsed(true);
}
}, [
collapsible,
expandedItem,
index,
setCollapsed,
autoCollapseSidebarCategories,
]);
}, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);

return (
<li
Expand Down
24 changes: 18 additions & 6 deletions packages/docusaurus-theme-classic/src/validateThemeConfig.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,21 @@ import type {

const DEFAULT_DOCS_CONFIG = {
versionPersistence: 'localStorage',
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
};
const DocsSchema = Joi.object({
versionPersistence: Joi.string()
.equal('localStorage', 'none')
.default(DEFAULT_DOCS_CONFIG.versionPersistence),
sidebar: Joi.object({
hideable: Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.hideable),
autoCollapseCategories: Joi.bool().default(
DEFAULT_DOCS_CONFIG.sidebar.autoCollapseCategories,
),
}).default(DEFAULT_DOCS_CONFIG.sidebar),
}).default(DEFAULT_DOCS_CONFIG);

const DEFAULT_COLOR_MODE_CONFIG = {
Expand All @@ -39,8 +49,6 @@ export const DEFAULT_CONFIG = {
hideOnScroll: false,
items: [],
},
hideableSidebar: false,
autoCollapseSidebarCategories: false,
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 3,
Expand Down Expand Up @@ -381,10 +389,14 @@ export const ThemeConfigSchema = Joi.object({
})
.default(DEFAULT_CONFIG.prism)
.unknown(),
hideableSidebar: Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
autoCollapseSidebarCategories: Joi.bool().default(
DEFAULT_CONFIG.autoCollapseSidebarCategories,
),
hideableSidebar: Joi.forbidden().messages({
'any.unknown':
'themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable.',
}),
autoCollapseSidebarCategories: Joi.forbidden().messages({
'any.unknown':
'themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories.',
}),
sidebarCollapsible: Joi.forbidden().messages({
'any.unknown':
'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',
Expand Down
7 changes: 4 additions & 3 deletions packages/docusaurus-theme-common/src/utils/useThemeConfig.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,10 @@ export type TableOfContents = {
export type ThemeConfig = {
docs: {
versionPersistence: DocsVersionPersistence;
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This API is, AFAIK, undocumented. Is it intended for usage by anyone? I initially thought about docsSidebar so there's some degree of parallel with navbar and footer, but because of the existence of this field, I eventually put it in docs.sidebar, with one extra level of nesting.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should likely document versionPersistence, implemented in #3543

Note some sites may want to minimize the usage of local storage. But it may have been me misinterpreting the GDPR rules and may not be that useful to provide an option for it 🤷‍♂️

Nesting docs.sidebar doesn't look like a bad idea anyway, still related to preemptive pluralization 🤪

sidebar: {
hideable: boolean;
autoCollapseCategories: boolean;
};
};

// TODO we should complete this theme config type over time
Expand All @@ -116,11 +120,8 @@ export type ThemeConfig = {
announcementBar?: AnnouncementBarConfig;
prism: PrismConfig;
footer?: Footer;
hideableSidebar: boolean;
autoCollapseSidebarCategories: boolean;
image?: string;
metadata: Array<{[key: string]: string}>;
sidebarCollapsible: boolean;
tableOfContents: TableOfContents;
};

Expand Down
8 changes: 6 additions & 2 deletions website/docs/api/docusaurus.config.js.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,8 +283,12 @@ Example:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
hideableSidebar: false,
autoCollapseSidebarCategories: false,
docs: {
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
colorMode: {
defaultMode: 'light',
disableSwitch: false,
Expand Down
19 changes: 14 additions & 5 deletions website/docs/guides/docs/sidebar/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,27 +121,36 @@ type SidebarsFile = {

### Hideable sidebar {#hideable-sidebar}

By enabling the `themeConfig.hideableSidebar` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).

```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-start
hideableSidebar: true,
docs: {
sidebar: {
hideable: true,
},
},
// highlight-end
},
};
```

### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}

The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.

```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-next-line
autoCollapseSidebarCategories: true,
// highlight-start
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
// highlight-end
},
};
```
Expand Down
8 changes: 6 additions & 2 deletions website/docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,8 +354,12 @@ const config = {
liveCodeBlock: {
playgroundPosition: 'bottom',
},
hideableSidebar: true,
autoCollapseSidebarCategories: true,
docs: {
sidebar: {
hideable: true,
autoCollapseCategories: true,
},
},
colorMode: {
defaultMode: 'light',
disableSwitch: false,
Expand Down