fix(docs): fix old /config/#option hash links causing hydration errors (#9610)

Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Vladimir <[email protected]>

Author: 3 people

docs/.vitepress/theme/index.ts

@@ -14,35 +14,44 @@ import '@shikijs/vitepress-twoslash/style.css'
 import 'virtual:group-icons.css'
 
 if (inBrowser) {
+  // redirect old hash links (e.g. /config/#reporters -> /config/reporters)
+  // before hydration to avoid SSG hydration mismatch
+  const redirect = getRedirectPath(new URL(location.href))
+  if (redirect) {
+    location.replace(redirect)
+  }
   import('./pwa')
 }
 
+function getRedirectPath(url: URL) {
+  if (url.pathname === '/api/' || url.pathname === '/api' || url.pathname === '/api/index.html') {
+    return '/api/test'
+  }
+  if (!url.hash) {
+    return
+  }
+
+  // /config/#reporters           -> /config/reporters
+  // /config/#coverage-provider   -> /config/coverage#coverage-provider
+  // /config/#browser.enabled     -> /config/browser/enabled
+  if (url.pathname === '/config' || url.pathname === '/config/' || url.pathname === '/config.html') {
+    if (url.hash.startsWith('#browser.')) {
+      const [page, ...hash] = url.hash.slice('#browser.'.length).toLowerCase().split('-')
+      return `/config/browser/${page}${hash.length ? `#${[page, ...hash].join('-')}` : ''}`
+    }
+    const [page, ...hash] = url.hash.slice(1).toLowerCase().split('-')
+    return `/config/${page}${hash.length ? `#${[page, ...hash].join('-')}` : ''}`
+  }
+  // /guide/browser/config#browser.locators-testidattribute -> /config/browser/locators#browser-locators-testidattribute
+  if (url.pathname === '/guide/browser/config' || url.pathname === '/guide/browser/config/' || url.pathname === '/guide/browser/config.html') {
+    const [page, ...hash] = url.hash.slice('#browser.'.length).toLowerCase().split('-')
+    return `/config/browser/${page}${hash.length ? `#${[page, ...hash].join('-')}` : ''}`
+  }
+}
+
 export default {
   extends: VitestTheme as unknown as any,
-  enhanceApp({ app, router }) {
-    router.onBeforeRouteChange = (to) => {
-      if (typeof location === 'undefined') {
-        return true
-      }
-      const url = new URL(to, location.href)
-      if (url.pathname === '/api/' || url.pathname === '/api' || url.pathname === '/api/index.html') {
-        setTimeout(() => { router.go(`/api/test`) })
-        return false
-      }
-      if (!url.hash) {
-        return true
-      }
-      if (url.pathname === '/config' || url.pathname === '/config/' || url.pathname === '/config.html') {
-        const [page, ...hash] = (url.hash.startsWith('#browser.') ? url.hash.slice(9) : url.hash.slice(1)).toLowerCase().split('-')
-        setTimeout(() => { router.go(`/config/${page}${hash.length ? `#${[page, ...hash].join('-')}` : ''}`) })
-        return false
-      }
-      if (url.pathname === '/guide/browser/config' || url.pathname === '/guide/browser/config/' || url.pathname === '/guide/browser/config.html') {
-        const [page, ...hash] = url.hash.slice('#browser.'.length).toLowerCase().split('-')
-        setTimeout(() => { router.go(`/config/browser/${page}${hash.length ? `#${[page, ...hash].join('-')}` : ''}`) })
-        return false
-      }
-    }
+  enhanceApp({ app }) {
     app.component('Version', Version)
     app.component('CRoot', CRoot)
     app.component('Experimental', Experimental)

packages/browser/context.d.ts

@@ -514,7 +514,7 @@ export interface LocatorSelectors {
    */
   getByTitle: (text: string | RegExp, options?: LocatorOptions) => Locator
   /**
-   * Creates a locator capable of finding an element that matches the specified test id attribute. You can configure the attribute name with [`browser.locators.testIdAttribute`](/config/#browser-locators-testidattribute).
+   * Creates a locator capable of finding an element that matches the specified test id attribute. You can configure the attribute name with [`browser.locators.testIdAttribute`](/config/browser/locators#browser-locators-testidattribute).
    * @see {@link https://vitest.dev/api/browser/locators#getbytestid}
    */
   getByTestId: (text: string | RegExp) => Locator

packages/spy/src/types.ts

@@ -224,7 +224,7 @@ export interface MockInstance<T extends Procedure | Constructable = Procedure> e
   /**
    * Clears all information about every call. After calling it, all properties on `.mock` will return to their initial state. This method does not reset implementations. It is useful for cleaning up mocks between different assertions.
    *
-   * To automatically call this method before each test, enable the [`clearMocks`](https://vitest.dev/config/#clearmocks) setting in the configuration.
+   * To automatically call this method before each test, enable the [`clearMocks`](https://vitest.dev/config/clearmocks) setting in the configuration.
    * @see https://vitest.dev/api/mock#mockclear
    */
   mockClear(): this
@@ -234,7 +234,7 @@ export interface MockInstance<T extends Procedure | Constructable = Procedure> e
    * Note that resetting a mock from `vi.fn()` will set implementation to an empty function that returns `undefined`.
    * Resetting a mock from `vi.fn(impl)` will set implementation to `impl`. It is useful for completely resetting a mock to its default state.
    *
-   * To automatically call this method before each test, enable the [`mockReset`](https://vitest.dev/config/#mockreset) setting in the configuration.
+   * To automatically call this method before each test, enable the [`mockReset`](https://vitest.dev/config/mockreset) setting in the configuration.
    * @see https://vitest.dev/api/mock#mockreset
    */
   mockReset(): this

packages/vitest/src/integrations/vi.ts

@@ -43,12 +43,12 @@ export interface VitestUtils {
   runOnlyPendingTimersAsync: () => Promise<VitestUtils>
   /**
    * This method will invoke every initiated timer until the timer queue is empty. It means that every timer called during `runAllTimers` will be fired.
-   * If you have an infinite interval, it will throw after 10,000 tries (can be configured with [`fakeTimers.loopLimit`](https://vitest.dev/config/#faketimers-looplimit)).
+   * If you have an infinite interval, it will throw after 10,000 tries (can be configured with [`fakeTimers.loopLimit`](https://vitest.dev/config/faketimers#faketimers-looplimit)).
    */
   runAllTimers: () => VitestUtils
   /**
    * This method will asynchronously invoke every initiated timer until the timer queue is empty. It means that every timer called during `runAllTimersAsync` will be fired even asynchronous timers.
-   * If you have an infinite interval, it will throw after 10 000 tries (can be configured with [`fakeTimers.loopLimit`](https://vitest.dev/config/#faketimers-looplimit)).
+   * If you have an infinite interval, it will throw after 10 000 tries (can be configured with [`fakeTimers.loopLimit`](https://vitest.dev/config/faketimers#faketimers-looplimit)).
    */
   runAllTimersAsync: () => Promise<VitestUtils>
   /**

packages/vitest/src/node/core.ts

@@ -1453,7 +1453,7 @@ export class Vitest {
           }
 
           if (!this.reporters.some(r => r instanceof HangingProcessReporter)) {
-            console.warn('You can try to identify the cause by enabling "hanging-process" reporter. See https://vitest.dev/config/#reporters')
+            console.warn('You can try to identify the cause by enabling "hanging-process" reporter. See https://vitest.dev/config/reporters')
           }
         }
 

packages/vitest/src/node/types/browser.ts

@@ -288,7 +288,7 @@ export interface BrowserConfigOptions {
   /**
    * Enables tracking uncaught errors and exceptions so they can be reported by Vitest.
    *
-   * If you need to hide certain errors, it is recommended to use [`onUnhandledError`](https://vitest.dev/config/#onunhandlederror) option instead.
+   * If you need to hide certain errors, it is recommended to use [`onUnhandledError`](https://vitest.dev/config/onunhandlederror) option instead.
    *
    * Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on.
    * @default true
@@ -455,12 +455,12 @@ type ToMatchScreenshotResolvePath = (data: {
   screenshotDirectory: string
   /**
    * Absolute path to the project's
-   * {@linkcode https://vitest.dev/config/#root|root}.
+   * {@linkcode https://vitest.dev/config/root|root}.
    */
   root: string
   /**
    * Path to the test file, relative to the project's
-   * {@linkcode https://vitest.dev/config/#root|root}.
+   * {@linkcode https://vitest.dev/config/root|root}.
    */
   testFileDirectory: string
   /**
@@ -474,7 +474,7 @@ type ToMatchScreenshotResolvePath = (data: {
   testName: string
   /**
    * The value provided to
-   * {@linkcode https://vitest.dev/config/#attachmentsdir|attachmentsDir},
+   * {@linkcode https://vitest.dev/config/attachmentsdir|attachmentsDir},
    * if none is provided, its default value.
    */
   attachmentsDir: string