Documentation improvements (#5968)

- Adds a new `/corepack` page
- Fills the missing section about ghost dependencies

packages/docusaurus/docs/features/plugnplay.md

@@ -124,3 +124,18 @@ Yarn PnP was designed to use the exact same "public interfaces" as other package
 One caveat though: the opposite isn't always true. Since other package managers don't / can't enforce proper listing of dependencies, they are more vulnerable to shipping ghost dependencies by accident to their consumers. In that way, using Yarn PnP can be seen as a good practice for the health of the ecosystem! 🙂
 
 ### How can I fix ghost dependencies?
+
+Ghost dependencies can be solved using the `packageExtensions` setting, which allows you to add new dependencies to any package in your dependency tree. For example, should you face an error such as `@babel/core tried to access @babel/types, but it isn't declared in its dependencies`, you can easily fix it by adding the following to your `.yarnrc.yml` file:
+
+```yaml
+packageExtensions:
+  "@babel/core@*":
+    dependencies:
+      "@babel/types": "*"
+```
+
+It may sometimes make sense to extend the `peerDependencies` field rather the `dependencies` field, this is to be addressed case-by-case.
+
+:::tip
+To avoid you having to add too many `packageExtensions` entries, the Yarn team maintains a list of [known ghost dependencies in the ecosystem](https://github.com/yarnpkg/berry/blob/master/packages/yarnpkg-extensions/sources/index.ts) that we automatically fix. This list is used by both Yarn and pnpm, and we're more than happy to merge contributions there.
+:::

packages/docusaurus/docs/getting-started/basics/install.md

@@ -7,10 +7,10 @@ sidebar_position: 2
 ---
 
 :::tip
-The preferred way to manage Yarn is by-project and through [Corepack](https://nodejs.org/dist/latest/docs/api/corepack.html), a tool shipped by default with Node.js. Modern releases of Yarn aren't meant to be installed globally, or from npm.
+The preferred way to manage Yarn is by-project and through [Corepack](/corepack), a tool shipped by default with Node.js. Modern releases of Yarn aren't meant to be installed globally, or from npm.
 :::
 
-1. Start by enabling Corepack, if it isn't already:
+1. Start by enabling [Corepack](/corepack), if it isn't already; this will add the `yarn` binary to your PATH:
 
 <CommandLineHighlight type={`code`} lines={[{type: `command`, command: {name: `corepack`, path: [`enable`], argv: [`enable`]}, split: false, tooltip: null, tokens: [{type: `path`, segmentIndex: 0, text: `enable`}]}]}/>
 

packages/docusaurus/docs/getting-started/extra/corepack.md

@@ -0,0 +1,44 @@
+---
+category: getting-started
+slug: /corepack
+title: Corepack
+description: About Corepack, the Node.js package manager provider.
+sidebar_position: 2
+---
+
+You may notice by reading our [installation guide](/getting-started/install) that we don't tell you to run `npm install -g yarn` to install Yarn - we even recommend against it. The reason is simple: **just like your project dependencies must be locked, so should be the package manager itself.**
+
+Installing Yarn as a global binary meant you always used whatever was the latest version published. Most of the time it worked fine, but every once in a while something was shipped that could impact the way your project was installed - be it a bugfix, new bug, or breaking change.
+
+To counter that, Yarn joined forces with the Node.js project to start the development of [Corepack](https://nodejs.org/api/corepack.html), an official Node.js tool letting you define which package manager version you want to use on a per-project basis, just like your lockfile does for your project dependencies.
+
+:::info
+Corepack is marked experimental so we can iterate on its CLI faster, but it's already the preferred way to install package managers - both for Yarn and for pnpm.
+:::
+
+## Installation
+
+Corepack is included with all official Node.js releases starting from Node.js 14.19 / 16.9. It's however opt-in for the duration of the experimental stage, so you'll need to run `corepack enable` before it's active.
+
+You can quickly check whether Corepack is enabled by running `yarn exec env | grep COREPACK_ROOT`: if you get a path as output, Corepack is properly installed. If not, something may be messing with how the shims are installed. In that case check the [Troubleshooting](/corepack#troubleshooting) section for advices.
+
+:::warning
+Some third-party distributors may not include Corepack by default, in particular if you install Node.js from your system package manager. If that happens, running `npm install -g corepack` before `corepack enable` should do the trick.
+:::
+
+## Troubleshooting
+
+### Offline workflow
+
+If you use an airgapped network, as is often the case in company CIs, you may hit problems where Corepack isn't able to download the Yarn binary for the active project. The Corepack documentation includes a [dedicated section](https://github.com/nodejs/corepack?tab=readme-ov-file#offline-workflow) explaining how to avoid this problem.
+
+### Volta
+
+Volta doesn't currently integrate with Corepack, as it installs its own shims which prevent the Corepack ones from being applied. You will need to run the following two commands to force the integration:
+
+```bash
+npm install -g corepack
+
+# Specifying an explicit install-directory makes corepack overwrite volta's yarn shims, which is what we want
+corepack enable --install-directory ~/.volta/bin
+```

packages/docusaurus/docs/getting-started/migrating/pnp.md

@@ -1,14 +1,14 @@
 ---
 category: getting-started
 slug: /migration/pnp
-title: "Yarn PnP migration"
+title: "To go further: Yarn PnP"
 description: A step-by-step and in-depth migration guide from Yarn 1 (Classic) to Yarn 2 (Berry).
 sidebar_position: 3
 sidebar_label: "To go further"
 ---
 
 :::info
-This step is **completely optional**!
+These steps are **completely optional**!
 
 While we recommend to use [Yarn Plug'n'Play](/features/pnp) for new projects, enabling it on existing projects may require a time investment. Feel free to skip this part if you prefer, and to come back to it whenever you have more time and/or a concrete benefit to get from it.
 :::