break: remove old v2 and v3 migration errors for renamed and removed options (AI-assisted) (#12703)

Remove the dedicated migration errors for options renamed or removed in
Docusaurus v2 (and v3 for the admonitions `tag` option). Users had two major
versions to migrate.

- theme-classic: disableDarkMode, defaultDarkMode, navbar.links,
  colorMode.switchConfig, metadatas, sidebarCollapsible, hideableSidebar,
  autoCollapseSidebarCategories
- docs: homePageId
- pwa: reloadPopup
- sitemap: cacheTime, trailingSlash
- preset-classic: themeConfig.gtag
- utils-validation: admonitions tag

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: slorber

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -80,11 +80,6 @@ const OptionsSchema = Joi.object<PluginOptions>({
   editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
   routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
   tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
-  // @ts-expect-error: deprecated
-  homePageId: Joi.any().forbidden().messages({
-    'any.unknown':
-      'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
-  }),
 
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),

packages/docusaurus-plugin-pwa/src/options.ts

@@ -48,11 +48,6 @@ const optionsSchema = Joi.object<PluginOptions>({
   swRegister: Joi.alternatives()
     .try(Joi.string(), Joi.bool().valid(false))
     .default(DEFAULT_OPTIONS.swRegister),
-  // @ts-expect-error: forbidden
-  reloadPopup: Joi.any().forbidden().messages({
-    'any.unknown':
-      'The reloadPopup option is removed in favor of swizzling. See https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#customizing-reload-popup for how to customize the reload popup using swizzling.',
-  }),
 });
 
 export function validateOptions({

packages/docusaurus-plugin-sitemap/src/options.ts

@@ -79,11 +79,6 @@ If you still want to emit this sitemap tag, use the ${logger.code(
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
   // @ts-expect-error: forbidden
-  cacheTime: Joi.forbidden().messages({
-    'any.unknown':
-      'Option `cacheTime` in sitemap config is deprecated. Please remove it.',
-  }),
-
   changefreq: removedOptionSchema('changefreq'),
   priority: removedOptionSchema('priority'),
 
@@ -96,10 +91,6 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   ignorePatterns: Joi.array()
     .items(Joi.string())
     .default(DEFAULT_OPTIONS.ignorePatterns),
-  trailingSlash: Joi.forbidden().messages({
-    'any.unknown':
-      'Please use the new Docusaurus global trailingSlash config instead, and the sitemaps plugin will use it.',
-  }),
   filename: Joi.string().default(DEFAULT_OPTIONS.filename),
 });
 

packages/docusaurus-preset-classic/src/index.ts

@@ -50,12 +50,6 @@ export default function preset(
   if (algolia) {
     themes.push(require.resolve('@docusaurus/theme-search-algolia'));
   }
-  if ('gtag' in themeConfig) {
-    throw new Error(
-      'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. For preset-classic, simply move themeConfig.gtag to preset options. More information at https://github.com/facebook/docusaurus/pull/5832.',
-    );
-  }
-
   // TODO Docusaurus v5: remove
   if ('googleAnalytics' in opts || 'googleAnalytics' in themeConfig) {
     throw new Error(

packages/docusaurus-theme-classic/src/__tests__/options.test.ts

@@ -144,19 +144,6 @@ describe('themeConfig', () => {
     });
   });
 
-  it('rejects outdated sidebar options', () => {
-    expect(() =>
-      testValidateThemeConfig({hideableSidebar: true}),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `[ValidationError: themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable.]`,
-    );
-    expect(() =>
-      testValidateThemeConfig({autoCollapseSidebarCategories: true}),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `[ValidationError: themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories.]`,
-    );
-  });
-
   it('allows possible types of navbar items', () => {
     const config = {
       navbar: {
@@ -662,19 +649,6 @@ describe('themeConfig', () => {
     const withDefaultValues = (colorMode?: ThemeConfig['colorMode']) =>
       _.merge({}, DEFAULT_CONFIG.colorMode, colorMode);
 
-    it('switch config', () => {
-      const colorMode = {
-        switchConfig: {
-          darkIcon: '🌙',
-        },
-      };
-      expect(() =>
-        testValidateThemeConfig({colorMode}),
-      ).toThrowErrorMatchingInlineSnapshot(
-        `[ValidationError: colorMode.switchConfig is deprecated. If you want to customize the icons for light and dark mode, swizzle IconLightMode, IconDarkMode, or ColorModeToggle instead.]`,
-      );
-    });
-
     it('max config', () => {
       const colorMode: ThemeConfig['colorMode'] = {
         defaultMode: 'dark',

packages/docusaurus-theme-classic/src/options.ts

@@ -304,10 +304,6 @@ const ColorModeSchema = Joi.object({
   respectPrefersColorScheme: Joi.bool().default(
     DEFAULT_COLOR_MODE_CONFIG.respectPrefersColorScheme,
   ),
-  switchConfig: Joi.any().forbidden().messages({
-    'any.unknown':
-      'colorMode.switchConfig is deprecated. If you want to customize the icons for light and dark mode, swizzle IconLightMode, IconDarkMode, or ColorModeToggle instead.',
-  }),
 }).default(DEFAULT_COLOR_MODE_CONFIG);
 
 const HtmlMetadataSchema = Joi.object({
@@ -356,30 +352,13 @@ const LogoSchema = Joi.object({
 const PrismLanguage = Joi.string().custom((val) => val.toLowerCase());
 
 export const ThemeConfigSchema = Joi.object<ThemeConfig>({
-  // TODO temporary (@alpha-58)
-  // @ts-expect-error: forbidden
-  disableDarkMode: Joi.any().forbidden().messages({
-    'any.unknown':
-      'disableDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.disableSwitch = true',
-  }),
-  // TODO temporary (@alpha-58)
-  defaultDarkMode: Joi.any().forbidden().messages({
-    'any.unknown':
-      'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
-  }),
   colorMode: ColorModeSchema,
   image: Joi.string(),
   docs: DocsSchema,
   blog: BlogSchema,
   metadata: Joi.array()
     .items(HtmlMetadataSchema)
     .default(DEFAULT_CONFIG.metadata),
-  // cSpell:ignore metadatas
-  metadatas: Joi.any().forbidden().messages({
-    'any.unknown':
-      // cSpell:ignore metadatas
-      'themeConfig.metadatas has been renamed as themeConfig.metadata. See https://github.com/facebook/docusaurus/pull/5871',
-  }),
   announcementBar: Joi.object({
     id: Joi.string().default('announcement-bar'),
     content: Joi.string().required(),
@@ -390,11 +369,6 @@ export const ThemeConfigSchema = Joi.object<ThemeConfig>({
   navbar: Joi.object({
     style: Joi.string().equal('dark', 'primary'),
     hideOnScroll: Joi.bool().default(DEFAULT_CONFIG.navbar.hideOnScroll),
-    // TODO temporary (@alpha-58)
-    links: Joi.any().forbidden().messages({
-      'any.unknown':
-        'themeConfig.navbar.links has been renamed as themeConfig.navbar.items',
-    }),
     items: Joi.array()
       .items(NavbarItemSchema)
       .default(DEFAULT_CONFIG.navbar.items),
@@ -442,18 +416,6 @@ export const ThemeConfigSchema = Joi.object<ThemeConfig>({
   })
     .default(DEFAULT_CONFIG.prism)
     .unknown(),
-  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',
-  }),
   tableOfContents: Joi.object({
     minHeadingLevel: Joi.number()
       .default(DEFAULT_CONFIG.tableOfContents.minHeadingLevel)

packages/docusaurus-utils-validation/src/__tests__/__snapshots__/validationSchemas.test.ts.snap

@@ -10,12 +10,6 @@ exports[`validation schemas > admonitionsSchema > for value={"infima":true} 1`]
 
 exports[`validation schemas > admonitionsSchema > for value={"keywords":["custom-keyword"],"extendDefaults":42} 1`] = `[ValidationError: "extendDefaults" must be a boolean]`;
 
-exports[`validation schemas > admonitionsSchema > for value={"tag":""} 1`] = `[ValidationError: It is not possible anymore to use a custom admonition tag. The only admonition tag supported is ':::' (Markdown Directive syntax)]`;
-
-exports[`validation schemas > admonitionsSchema > for value={"tag":"+++","keywords":["info","tip"]} 1`] = `[ValidationError: It is not possible anymore to use a custom admonition tag. The only admonition tag supported is ':::' (Markdown Directive syntax)]`;
-
-exports[`validation schemas > admonitionsSchema > for value={"tag":"+++"} 1`] = `[ValidationError: It is not possible anymore to use a custom admonition tag. The only admonition tag supported is ':::' (Markdown Directive syntax)]`;
-
 exports[`validation schemas > admonitionsSchema > for value={"unknownAttribute":"val"} 1`] = `[ValidationError: "unknownAttribute" is not allowed]`;
 
 exports[`validation schemas > admonitionsSchema > for value=3 1`] = `[ValidationError: "value" does not look like a valid admonitions config]`;

packages/docusaurus-utils-validation/src/__tests__/validationSchemas.test.ts

@@ -112,10 +112,7 @@ describe('validation schemas', () => {
     testFail(3);
     testFail([]);
     testFail({unknownAttribute: 'val'});
-    testFail({tag: ''});
     testFail({keywords: ['custom-keyword'], extendDefaults: 42});
-    testFail({tag: '+++'});
-    testFail({tag: '+++', keywords: ['info', 'tip']});
 
     // Legacy types
     testFail({

packages/docusaurus-utils-validation/src/validationSchemas.ts

@@ -48,11 +48,6 @@ export const AdmonitionsSchema = JoiFrontMatter.alternatives()
         // .required(),
       ),
       extendDefaults: JoiFrontMatter.boolean(),
-
-      // TODO Remove before 2024
-      tag: Joi.any().forbidden().messages({
-        'any.unknown': `It is not possible anymore to use a custom admonition tag. The only admonition tag supported is ':::' (Markdown Directive syntax)`,
-      }),
     }).required(),
   )
   .default(true)