docs: add troubleshooting steps to migration/upgrade page (#9490)

Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: sebastienlorber <[email protected]> Co-authored-by: Sébastien Lorber <[email protected]>
facebook · Apr 18, 2024 · edb695b · edb695b
1 parent 8e084ef
commit edb695b
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 1 deletion.
diff --git 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
@@ -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',