From edb695b9aa577ef3c2a5d4a15f2c92e8ed43e9e7 Mon Sep 17 00:00:00 2001
From: Mikey O'Toole <mikey@homotechsual.dev>
Date: Thu, 18 Apr 2024 16:04:56 +0100
Subject: [PATCH] docs: add troubleshooting steps to migration/upgrade page
 (#9490)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
---
 website/docs/migration/index.mdx | 39 ++++++++++++++++++++++++++++++++
 website/docusaurus.config.ts     |  2 +-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/website/docs/migration/index.mdx b/website/docs/migration/index.mdx
index c78662f032eb..9a9a5616edac 100644
--- a/website/docs/migration/index.mdx
+++ b/website/docs/migration/index.mdx
@@ -11,3 +11,42 @@ Docusaurus versioning is based on the `major.minor.patch` scheme and respects [*
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />
+
+## Troubleshooting upgrades
+
+When upgrading Docusaurus you may experience issues caused by mismatching cached dependencies - there are a few troubleshooting steps you should perform to resolve these common issues before reporting a bug or seeking support.
+
+### Run the `clear` command
+
+This CLI command is used to clear a Docusaurus site's generated assets, caches and build artifacts.
+
+```bash npm2yarn
+npm run clear
+```
+
+### Remove `node_modules` and your lock file(s)
+
+Remove the `node_modules` folder and your package manager's lock file using the following:
+
+<Tabs>
+<TabItem label="Bash" value="bash">
+
+```bash
+rm -rf node_modules yarn.lock package-lock.json
+```
+
+</TabItem>
+<TabItem label="PowerShell" value="powershell">
+
+```powershell
+@('node_modules','yarn.lock','package-lock.json') | Remove-Item -Force -Recurse -ErrorAction SilentlyContinue
+```
+
+</TabItem>
+</Tabs>
+
+Then reinstall packages and regenerate the `lock` file using:
+
+```bash npm2yarn
+npm install
+```
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index a5cdb17b4ae1..996dcb42b0df 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import path from 'path';
-
 import npm2yarn from '@docusaurus/remark-plugin-npm2yarn';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
@@ -523,6 +522,7 @@ export default async function createConfigAsync() {
           'haskell',
           'matlab',
           'PHp',
+          'powershell',
           'bash',
           'diff',
           'json',