diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/index.test.ts index 8b259d8fcd..d165ae6673 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/index.test.ts @@ -58,7 +58,7 @@ describe('loadSidebars', () => { await expect(() => loadSidebars(sidebarPath, params), ).rejects.toThrowErrorMatchingInlineSnapshot( - `"Invalid category {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}: items must be an array of sidebar items or a category shorthand"`, + `"Invalid sidebar items collection \`\\"doc1\\"\` in \`items\` of the category Category Label: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`, ); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts index 23234b60de..fbb00ec825 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts @@ -37,4 +37,53 @@ describe('normalization', () => { }), ).toMatchSnapshot(); }); + test('rejects some invalid cases', () => { + expect(() => + normalizeSidebars({ + sidebar: { + Category: {type: 'autogenerated', dirName: 'foo'}, + Category2: {type: 'autogenerated', dirName: 'bar'}, + }, + }), + ).toThrowErrorMatchingInlineSnapshot( + `"Invalid sidebar items collection \`{\\"type\\":\\"autogenerated\\",\\"dirName\\":\\"foo\\"}\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`, + ); + + expect(() => + normalizeSidebars({ + sidebar: [ + 'foo', + { + Category: { + type: 'category', + items: ['bar', 'baz'], + }, + }, + ], + }), + ).toThrowErrorMatchingInlineSnapshot( + `"Invalid sidebar items collection \`{\\"type\\":\\"category\\",\\"items\\":[\\"bar\\",\\"baz\\"]}\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`, + ); + + expect(() => + normalizeSidebars({ + sidebar: [ + 'foo', + { + Category: 'bar', + }, + ], + }), + ).toThrowErrorMatchingInlineSnapshot( + `"Invalid sidebar items collection \`\\"bar\\"\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`, + ); + + expect(() => + normalizeSidebars({ + sidebar: 'item', + }), + ).toThrowErrorMatchingInlineSnapshot( + `"Invalid sidebar items collection \`\\"item\\"\` in sidebar sidebar: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`, + ); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts index 1492ba0970..dad431fbd1 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts @@ -18,6 +18,7 @@ import type { } from './types'; import {isCategoriesShorthand} from './utils'; import _ from 'lodash'; +import logger from '@docusaurus/logger'; function normalizeCategoriesShorthand( sidebar: SidebarCategoriesShorthand, @@ -37,40 +38,37 @@ export function normalizeItem( item: SidebarItemConfig, ): NormalizedSidebarItem[] { if (typeof item === 'string') { - return [ - { - type: 'doc', - id: item, - }, - ]; + return [{type: 'doc', id: item}]; } if (isCategoriesShorthand(item)) { - return normalizeCategoriesShorthand(item).flatMap((subItem) => - normalizeItem(subItem), - ); + // This will never throw anyways + return normalizeSidebar(item, 'sidebar items slice'); } if (item.type === 'category') { - if (typeof item.items !== 'undefined' && typeof item.items !== 'object') { - throw new Error( - `Invalid category ${JSON.stringify( - item, - )}: items must be an array of sidebar items or a category shorthand`, - ); - } const normalizedCategory: NormalizedSidebarItemCategory = { ...item, - items: Array.isArray(item.items) - ? item.items.flatMap((subItem) => normalizeItem(subItem)) - : normalizeCategoriesShorthand(item.items).flatMap((subItem) => - normalizeItem(subItem), - ), + items: normalizeSidebar( + item.items, + logger.interpolate`code=${'items'} of the category name=${item.label}`, + ), }; return [normalizedCategory]; } return [item]; } -function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar { +function normalizeSidebar( + sidebar: SidebarConfig, + place: string, +): NormalizedSidebar { + if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) { + throw new Error( + logger.interpolate`Invalid sidebar items collection code=${JSON.stringify( + sidebar, + )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`, + ); + } + const normalizedSidebar = Array.isArray(sidebar) ? sidebar : normalizeCategoriesShorthand(sidebar); @@ -81,5 +79,7 @@ function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar { export function normalizeSidebars( sidebars: SidebarsConfig, ): NormalizedSidebars { - return _.mapValues(sidebars, normalizeSidebar); + return _.mapValues(sidebars, (sidebar, id) => + normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`), + ); } diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts index 1948c6b09c..a0c69020eb 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts @@ -26,7 +26,7 @@ import type {DocMetadataBase, DocNavLink} from '../types'; export function isCategoriesShorthand( item: SidebarItemConfig, ): item is SidebarCategoriesShorthand { - return typeof item !== 'string' && !item.type; + return typeof item === 'object' && !item.type; } export function transformSidebarItems(