Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 10 commits into from
Apr 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions website/docs/migration/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Comment on lines +41 to +43
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't find it necessary to document powershell—https://docusaurus.io/docs/i18n/tutorial#translate-the-docs here we don't. Particularly for simple commands like this that can even be done through the file UI, let's keep things simple.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the primary scripting language of a vast swathe of Docusaurus users who're using Windows, I feel it's helpful to have those examples where they make sense - which they don't in all cases but happy for it not to be included if that's the concensus

Copy link
Contributor

@armano2 armano2 Mar 29, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

 rm -r node_modules
 rm -r yarn.lock
 rm -r package-lock.json

should work fine with new versions of powershell

PS D:\Projects\docusaurus> rm -r node_modules
PS D:\Projects\docusaurus> rm -r yarn.lock
PS D:\Projects\docusaurus> rm -r package-lock.json
Remove-Item: Cannot find path 'D:\Projects\docusaurus\package-lock.json' because it does not exist.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great to know thanks. Is this really new or most Windows users have it supported?

@homotechsual can you confirm it works for you with rm -rf? if yes I'd rather remove those tabs before merging

Copy link
Contributor

@armano2 armano2 Apr 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it should be supported in most of win 10-11 and in and potentially in older versions of windows if user uses powershell

rm is just a shortcut for Remove-Item

PS D:\> 'rm', 'rmdir', 'rd' | Get-Command

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Alias           rm -> Remove-Item
Alias           rmdir -> Remove-Item
Alias           rd -> Remove-Item

-rf s alittle tricker but if you really want to have f like behaviour you want to use something like rm -r -fo node_modules, but that should not be necessary

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rm works - but the switches don't translate 1-1 on any version of Windows or PowerShell which is why the separate command is needed. You could do rm -r -fo for Windows but then really you still have a different command - but you're just making it needlessly confusing by using an aliased version of the full command I included.

If you guys don't think it needs to be included I get it - I can remove it. I'm just seeing more frequent questions from devs on Windows and all our command examples are linux only. I'm more than happy to widen this effort so it's consistent where it makes sense in a similar method to how we handle providing npm yarn and pnpm examples.


</TabItem>
</Tabs>

Then reinstall packages and regenerate the `lock` file using:

```bash npm2yarn
npm install
```
2 changes: 1 addition & 1 deletion website/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -486,6 +485,7 @@ export default async function createConfigAsync() {
'haskell',
'matlab',
'PHp',
'powershell',
'bash',
'diff',
'json',
Expand Down
Loading