chore(plugin-docs): remove legacy versioned prefix on doc ids and sidebar names in versioned sidebars (#9310)

This commit is contained in:
Sébastien Lorber 2023-09-15 18:52:42 +02:00 committed by GitHub
parent f5ae537d3e
commit 598b32011f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
25 changed files with 264 additions and 396 deletions

View file

@ -67,7 +67,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebar_custom_props: {custom: 'prop'},
},
title: '',
unversionedId: 'doc1',
},
{
id: 'doc2',
@ -76,7 +75,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 3,
frontMatter: {},
title: '',
unversionedId: 'doc2',
},
{
id: 'doc3',
@ -85,7 +83,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 1,
frontMatter: {},
title: '',
unversionedId: 'doc3',
},
{
id: 'doc4',
@ -94,7 +91,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 1.5,
frontMatter: {},
title: '',
unversionedId: 'doc4',
},
{
id: 'doc5',
@ -103,7 +99,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc5',
},
],
isCategoryIndex: () => false,
@ -150,7 +145,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 0,
frontMatter: {},
title: '',
unversionedId: 'intro',
},
{
id: 'tutorials-index',
@ -159,7 +153,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: 'Tutorials',
unversionedId: 'tutorials-index',
},
{
id: 'tutorial2',
@ -168,7 +161,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: '',
unversionedId: 'tutorial2',
},
{
id: 'tutorial1',
@ -177,7 +169,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 1,
frontMatter: {},
title: '',
unversionedId: 'tutorial1',
},
{
id: 'guides-index',
@ -185,7 +176,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: '02-Guides',
frontMatter: {},
title: 'Guides',
unversionedId: 'guides-index',
},
{
id: 'guide2',
@ -194,7 +184,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: '',
unversionedId: 'guide2',
},
{
id: 'guide1',
@ -205,7 +194,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebar_class_name: 'foo',
},
title: '',
unversionedId: 'guide1',
},
{
id: 'nested-guide',
@ -214,7 +202,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'nested-guide',
},
{
id: 'end',
@ -223,7 +210,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 3,
frontMatter: {},
title: '',
unversionedId: 'end',
},
],
});
@ -268,7 +254,6 @@ describe('DefaultSidebarItemsGenerator', () => {
title: 'Subsubsubfolder category label',
sidebarPosition: undefined,
frontMatter: {},
unversionedId: 'doc1',
},
{
id: 'doc2',
@ -277,7 +262,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc2',
},
{
id: 'doc3',
@ -286,7 +270,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc2',
},
{
id: 'doc4',
@ -295,7 +278,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc4',
},
{
id: 'doc5',
@ -304,7 +286,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc5',
},
{
id: 'doc6',
@ -313,7 +294,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: undefined,
frontMatter: {},
title: '',
unversionedId: 'doc6',
},
{
id: 'doc7',
@ -322,7 +302,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: '',
unversionedId: 'doc7',
},
{
id: 'doc8',
@ -331,7 +310,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 1,
frontMatter: {},
title: '',
unversionedId: 'doc8',
},
],
});
@ -370,7 +348,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category',
frontMatter: {},
title: '',
unversionedId: 'parent/doc1',
},
{
id: 'parent/doc2',
@ -378,7 +355,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category',
frontMatter: {},
title: '',
unversionedId: 'parent/doc2',
},
{
id: 'parent/doc3',
@ -386,7 +362,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category',
frontMatter: {},
title: '',
unversionedId: 'parent/doc3',
},
{
id: 'parent/doc4',
@ -394,7 +369,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category2',
frontMatter: {},
title: '',
unversionedId: 'parent/doc4',
},
{
id: 'parent/doc5',
@ -402,7 +376,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category2',
frontMatter: {},
title: '',
unversionedId: 'parent/doc5',
},
{
id: 'parent/doc6',
@ -410,7 +383,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: 'Category2',
frontMatter: {},
title: '',
unversionedId: 'parent/doc6',
},
],
isCategoryIndex: () => false,
@ -449,7 +421,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 0,
frontMatter: {},
title: '',
unversionedId: 'intro',
},
{
id: 'tutorials-index',
@ -458,7 +429,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: 'Tutorials',
unversionedId: 'tutorials-index',
},
{
id: 'tutorial2',
@ -467,7 +437,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: '',
unversionedId: 'tutorial2',
},
{
id: 'tutorial1',
@ -476,7 +445,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 1,
frontMatter: {},
title: '',
unversionedId: 'tutorial1',
},
{
id: 'not-guides-index',
@ -484,7 +452,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sourceDirName: '02-Guides',
frontMatter: {},
title: 'Guides',
unversionedId: 'not-guides-index',
},
{
id: 'guide2',
@ -493,7 +460,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebarPosition: 2,
frontMatter: {},
title: 'guide2',
unversionedId: 'guide2',
},
{
id: 'guide1',
@ -504,7 +470,6 @@ describe('DefaultSidebarItemsGenerator', () => {
sidebar_class_name: 'foo',
},
title: '',
unversionedId: 'guide1',
},
],
});
@ -536,7 +501,6 @@ describe('DefaultSidebarItemsGenerator', () => {
docs: [
{
id: 'intro',
unversionedId: 'intro',
source: '@site/docs/category/intro.md',
sourceDirName: 'category',
frontMatter: {},

View file

@ -155,7 +155,7 @@ describe('postProcess', () => {
{
sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
version: {path: 'version'},
drafts: [{id: 'foo', unversionedId: 'foo'}],
drafts: [{id: 'foo'}],
} as unknown as SidebarPostProcessorParams,
),
).toMatchSnapshot();

View file

@ -155,8 +155,7 @@ describe('createSidebarsUtils', () => {
it('getDocNavigation', () => {
expect(
getDocNavigation({
unversionedId: 'doc1',
versionedId: 'doc1',
docId: 'doc1',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -170,8 +169,7 @@ describe('createSidebarsUtils', () => {
});
expect(
getDocNavigation({
unversionedId: 'doc2',
versionedId: 'doc2',
docId: 'doc2',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -186,8 +184,7 @@ describe('createSidebarsUtils', () => {
expect(
getDocNavigation({
unversionedId: 'doc3',
versionedId: 'doc3',
docId: 'doc3',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -201,8 +198,7 @@ describe('createSidebarsUtils', () => {
});
expect(
getDocNavigation({
unversionedId: 'doc4',
versionedId: 'doc4',
docId: 'doc4',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -218,8 +214,7 @@ describe('createSidebarsUtils', () => {
expect(
getDocNavigation({
unversionedId: 'doc5',
versionedId: 'doc5',
docId: 'doc5',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -233,8 +228,7 @@ describe('createSidebarsUtils', () => {
});
expect(
getDocNavigation({
unversionedId: 'doc6',
versionedId: 'doc6',
docId: 'doc6',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -251,8 +245,7 @@ describe('createSidebarsUtils', () => {
});
expect(
getDocNavigation({
unversionedId: 'doc7',
versionedId: 'doc7',
docId: 'doc7',
displayedSidebar: undefined,
unlistedIds: new Set(),
}),
@ -266,8 +259,7 @@ describe('createSidebarsUtils', () => {
});
expect(
getDocNavigation({
unversionedId: 'doc3',
versionedId: 'doc3',
docId: 'doc3',
displayedSidebar: null,
unlistedIds: new Set(),
}),
@ -278,8 +270,7 @@ describe('createSidebarsUtils', () => {
});
expect(() =>
getDocNavigation({
unversionedId: 'doc3',
versionedId: 'doc3',
docId: 'doc3',
displayedSidebar: 'foo',
unlistedIds: new Set(),
}),
@ -288,8 +279,7 @@ describe('createSidebarsUtils', () => {
);
expect(
getDocNavigation({
unversionedId: 'doc3',
versionedId: 'doc3',
docId: 'doc3',
displayedSidebar: 'sidebar1',
unlistedIds: new Set(),
}),

View file

@ -7,7 +7,6 @@
import _ from 'lodash';
import {normalizeUrl} from '@docusaurus/utils';
import {getDocIds} from '../docs';
import type {
SidebarItem,
Sidebars,
@ -102,7 +101,7 @@ export function postProcessSidebars(
sidebars: ProcessedSidebars,
params: SidebarProcessorParams,
): Sidebars {
const draftIds = new Set(params.drafts.flatMap(getDocIds));
const draftIds = new Set(params.drafts.map((d) => d.id));
return _.mapValues(sidebars, (sidebar) =>
sidebar

View file

@ -33,7 +33,6 @@ function toSidebarItemsGeneratorDoc(
): SidebarItemsGeneratorDoc {
return _.pick(doc, [
'id',
'unversionedId',
'title',
'frontMatter',
'source',

View file

@ -235,7 +235,6 @@ export type CategoryMetadataFile = {
export type SidebarItemsGeneratorDoc = Pick<
DocMetadataBase,
| 'id'
| 'unversionedId'
| 'title'
| 'frontMatter'
| 'source'

View file

@ -23,6 +23,7 @@ import type {
import type {
DocMetadataBase,
PropNavigationLink,
VersionMetadata,
} from '@docusaurus/plugin-content-docs';
export function isCategoriesShorthand(
@ -136,8 +137,7 @@ export type SidebarsUtils = {
getFirstDocIdOfFirstSidebar: () => string | undefined;
getSidebarNameByDocId: (docId: string) => string | undefined;
getDocNavigation: (params: {
unversionedId: string;
versionedId: string;
docId: string;
displayedSidebar: string | null | undefined;
unlistedIds: Set<string>;
}) => SidebarNavigation;
@ -163,7 +163,22 @@ export type SidebarsUtils = {
}
| undefined;
checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
checkLegacyVersionedSidebarNames: ({
versionMetadata,
}: {
sidebarFilePath: string;
versionMetadata: VersionMetadata;
}) => void;
checkSidebarsDocIds: ({
allDocIds,
sidebarFilePath,
versionMetadata,
}: {
allDocIds: string[];
sidebarFilePath: string;
versionMetadata: VersionMetadata;
}) => void;
};
export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
@ -194,26 +209,18 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
}
function getDocNavigation({
unversionedId,
versionedId,
docId,
displayedSidebar,
unlistedIds,
}: {
unversionedId: string;
versionedId: string;
docId: string;
displayedSidebar: string | null | undefined;
unlistedIds: Set<string>;
}): SidebarNavigation {
// TODO legacy id retro-compatibility!
let docId = unversionedId;
let sidebarName =
const sidebarName =
displayedSidebar === undefined
? getSidebarNameByDocId(docId)
: displayedSidebar;
if (sidebarName === undefined) {
docId = versionedId;
sidebarName = getSidebarNameByDocId(docId);
}
if (!sidebarName) {
return emptySidebarNavigation();
@ -303,19 +310,115 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
};
}
function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
// TODO remove in Docusaurus v4
function getLegacyVersionedPrefix(versionMetadata: VersionMetadata): string {
return `version-${versionMetadata.versionName}/`;
}
// In early v2, sidebar names used to be versioned
// example: "version-2.0.0-alpha.66/my-sidebar-name"
// In v3 it's not the case anymore and we throw an error to explain
// TODO remove in Docusaurus v4
function checkLegacyVersionedSidebarNames({
versionMetadata,
sidebarFilePath,
}: {
versionMetadata: VersionMetadata;
sidebarFilePath: string;
}): void {
const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) =>
sidebarName.startsWith(illegalPrefix),
);
if (legacySidebarNames.length > 0) {
throw new Error(
`Invalid sidebar file at "${toMessageRelativeFilePath(
sidebarFilePath,
)}".
These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
- ${legacySidebarNames.sort().join('\n- ')}
The sidebar names you should now use are:
- ${legacySidebarNames
.sort()
.map((legacyName) => legacyName.split('/').splice(1).join('/'))
.join('\n- ')}
Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
`,
);
}
}
// throw a better error message for Docusaurus v3 breaking change
// TODO this can be removed in Docusaurus v4
function handleLegacyVersionedDocIds({
invalidDocIds,
sidebarFilePath,
versionMetadata,
}: {
invalidDocIds: string[];
sidebarFilePath: string;
versionMetadata: VersionMetadata;
}) {
const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
// In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
// Example: "version-1.4/my-doc-id"
//
const legacyVersionedDocIds = invalidDocIds.filter((docId) =>
docId.startsWith(illegalPrefix),
);
if (legacyVersionedDocIds.length > 0) {
throw new Error(
`Invalid sidebar file at "${toMessageRelativeFilePath(
sidebarFilePath,
)}".
These legacy versioned document ids are not supported anymore in Docusaurus v3:
- ${legacyVersionedDocIds.sort().join('\n- ')}
The document ids you should now use are:
- ${legacyVersionedDocIds
.sort()
.map((legacyId) => legacyId.split('/').splice(1).join('/'))
.join('\n- ')}
Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
`,
);
}
}
function checkSidebarsDocIds({
allDocIds,
sidebarFilePath,
versionMetadata,
}: {
allDocIds: string[];
sidebarFilePath: string;
versionMetadata: VersionMetadata;
}) {
const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
const invalidSidebarDocIds = _.difference(allSidebarDocIds, validDocIds);
if (invalidSidebarDocIds.length > 0) {
const invalidDocIds = _.difference(allSidebarDocIds, allDocIds);
if (invalidDocIds.length > 0) {
handleLegacyVersionedDocIds({
invalidDocIds,
sidebarFilePath,
versionMetadata,
});
throw new Error(
`Invalid sidebar file at "${toMessageRelativeFilePath(
sidebarFilePath,
)}".
These sidebar document ids do not exist:
- ${invalidSidebarDocIds.sort().join('\n- ')}
- ${invalidDocIds.sort().join('\n- ')}
Available document ids are:
- ${_.uniq(validDocIds).sort().join('\n- ')}`,
- ${_.uniq(allDocIds).sort().join('\n- ')}
`,
);
}
}
@ -369,6 +472,7 @@ Available document ids are:
getDocNavigation,
getCategoryGeneratedIndexList,
getCategoryGeneratedIndexNavigation,
checkLegacyVersionedSidebarNames,
checkSidebarsDocIds,
getFirstLink: (id) => getFirstLink(sidebars[id]!),
};