Various minor tweaks for website (#5863)

**What's the problem this PR addresses?**

There are a number of build tooling and minor problems with the website.
(Listed below)

**How did you fix it?**

Maintainers: I have marked this as draft for now due to the
Questions/TODOs/TBDs. Most of these I just implemented the fix that I
think is the most straightforward/reasonable. Feel free to
edit/merge/cherry-pick anything here as you see fit.

- [x] ~~The bundled TS type check is bugged (e.g.
[xterm-headless](https://yarnpkg.com/package?q=xterm-head&name=xterm-headless)
is reported as "no types")~~
- [x] ~~Fix: prioritize type entrypoints (`types` and `typings` fields
in `pacakge.json`, `types` condition) instead of normal (JS) entrypoints
when resolving the package.~~
- On second thought I think it is better to split this to another PR
(#5867)
- [x] Building the website fails on Windows due to [quirks of
child_process](https://nodejs.org/api/child_process.html#child_process_spawning_bat_and_cmd_files_on_windows)
on Windows
- [x] Fix: use `cross-spawn`, which `@yarnpkg/core` already depends on
- [x] There are a number of unused files/assets/patches/dependencyMetas
    - [x] Fix: delete them
- [x] The README is the default one generated by Docusuarus
    - [x] Fix: Update it to have slightly more useful info
- [x] There are a number of broken links, as reported by docusaurus
during `build`
- In particular, the [Release
Workflow](https://v3.yarnpkg.com/features/release-workflow) was not
ported to the new website.
    - [x] Fix: port the Release Workflow page from the old website
    - [x] Fix: Delete the extraneous "Publishing" page, for now
    - [x] Fix: change broken links to new URLs
- [x] ~~**Question**: What is the "Publishing" page? Is it supposed to
be a re-written Release Workflow page?~~
- [ ] There are also a number of broken links from other places in this
repo
- There are a total of 12 broken links (404 or not the intended page)
- 1 of them is to https://yarnpkg.com/advanced/sherlock, where there is
no short-term resolution (see #5859)
        - 2 of them are to https://yarnpkg.com/api, see below
        - 4 of them are in old blog posts. Let's leave them be
        - [x] Fix: Fix the other 5
- There are a few links to https://yarnpkg.com/features/zero-installs,
which 301-redirects to
https://yarnpkg.com/features/caching#zero-installs
- 2 of them are in old blog posts / CHANGELOG. Let's leave them be
        - [x] Fix: Change the others to the canonical URL
- There are a few links to package pages like
https://yarnpkg.com/package/eslint, which 301-redirects to
https://yarnpkg.com/package?name=eslint
        - [ ] **Question**: Should we change those to the canonical URLs
- [x] There is an extraneous TOC block in the
[Rulebook](https://yarnpkg.com/advanced/rulebook), a remnant of the old
Gatsby-based website
- [x] Fix: Remove it. Docusaurus adds a right sidebar/"On this page"
block automatically
- [x] The output during build is quite excessive. In particular, our own
commandLineHighlight plugin is spewing multi-line "fail to parse" errors
onto the console, which interferes with docusaurus' own progress bar
- [x] Fix: reduce the commandLineHighlight plugin output to only display
the command line that failed to parse
- ~~**Question**: This a not a very elegant solution. Are there better
alternatives?~~
    - I have an idea for a better solution. Will be a separate PR
- [x] There are two warnings during build:
    - `webpack` warns `js-yaml` on using `buffer`
    - [x] Fix: Explicitly disable the `buffer` polyfill as suggested
- `autoprefixer` warns `src/css/custom.css` on using
`text-decoration-skip` CSS property
    - [x] Fix: Use `text-decoration-skip-ink` instead as suggested
- [x] Add a dropdown to the navbar that links to the old websites
- [x] ~~**Question**: Should we use [versioned
docs](https://docusaurus.io/docs/versioning) for v4+?~~
- ~~**TBD**: While generating the CLI docs, run the CLI in JS instead of
via the OS shell to avoid spawning a terminal window~~
- ~~**TBD**: The API reference is completely removed. What should we do
about it?~~
- ~~**TBD**: Should we update `caniuse-lite` as suggested? Should we do
it regularly?~~

Closes #5667 (supersedes)
Closes #5860 (supersedes)
~~Closes #5894 (supersedes)~~
Fixes #5707
Fixes #5805
Fixes #5832
~~Fixes #5861~~
~~Fixes #5869~~
Fixes #5926

**Checklist**
<!--- Don't worry if you miss something, chores are automatically
tested. -->
<!--- This checklist exists to help you remember doing the chores when
you submit a PR. -->
<!--- Put an `x` in all the boxes that apply. -->
- [x] I have read the [Contributing
Guide](https://yarnpkg.com/advanced/contributing).

<!-- See
https://yarnpkg.com/advanced/contributing#preparing-your-pr-to-be-released
for more details. -->
<!-- Check with `yarn version check` and fix with `yarn version check
-i` -->
- [x] I have set the packages that need to be released for my changes to
be effective.

<!-- The "Testing chores" workflow validates that your PR follows our
guidelines. -->
<!-- If it doesn't pass, click on it to see details as to what your PR
might be missing. -->
- [x] I will check that all automated PR checks pass before the PR gets
reviewed.

Author: clemyan

.gitignore

@@ -1,4 +1,4 @@
-# https://yarnpkg.com/getting-started/qa/#which-files-should-be-gitignored
+# https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
 .yarn/*
 !.yarn/cache
 !.yarn/patches

.pnp.cjs

@@ -0,0 +1,23 @@
+releases:
+  "@yarnpkg/cli": patch
+  "@yarnpkg/doctor": patch
+  "@yarnpkg/plugin-essentials": patch
+  "@yarnpkg/plugin-init": patch
+  "@yarnpkg/plugin-patch": patch
+
+declined:
+  - "@yarnpkg/plugin-compat"
+  - "@yarnpkg/plugin-constraints"
+  - "@yarnpkg/plugin-dlx"
+  - "@yarnpkg/plugin-interactive-tools"
+  - "@yarnpkg/plugin-nm"
+  - "@yarnpkg/plugin-npm-cli"
+  - "@yarnpkg/plugin-pack"
+  - "@yarnpkg/plugin-pnp"
+  - "@yarnpkg/plugin-pnpm"
+  - "@yarnpkg/plugin-stage"
+  - "@yarnpkg/plugin-typescript"
+  - "@yarnpkg/plugin-version"
+  - "@yarnpkg/plugin-workspace-tools"
+  - "@yarnpkg/builder"
+  - "@yarnpkg/core"

.yarn/patches/typedoc-npm-0.17.0-3-0ce05847cf.patch

@@ -18,7 +18,7 @@
 
 Yarn is a modern package manager split into various packages. Its novel architecture allows to do things currently impossible with existing solutions:
 
-- Yarn supports [plugins](https://yarnpkg.com/features/plugins); adding a plugin is as simple as adding it to your repository
+- Yarn supports [plugins](https://yarnpkg.com/features/extensibility); adding a plugin is as simple as adding it into your repository
 - Yarn supports Node by default but isn't limited to it - plugins can add support for other languages
 - Yarn supports [workspaces](https://yarnpkg.com/features/workspaces) natively, and its CLI takes advantage of that
 - Yarn uses a bash-like [portable shell](https://github.com/yarnpkg/berry/tree/master/packages/yarnpkg-shell#yarnpkgshell) to make package scripts portable across Windows, Linux, and macOS

.yarn/versions/aa1cf688.yml

@@ -32,9 +32,7 @@
   },
   "resolutions": {
     "ink": "patch:ink@npm%3A3.0.8#~/.yarn/patches/ink-npm-3.0.8-3a8005f59f.patch",
-    "yoga-layout-prebuilt": "patch:[email protected]#./.yarn/patches/yoga-layout-prebuilt.patch",
-    "typedoc@npm:0.16.0": "patch:typedoc@npm%3A0.17.0-3#~/.yarn/patches/typedoc-npm-0.17.0-3-0ce05847cf.patch",
-    "typedoc@npm:0.17.0-3": "patch:typedoc@npm%3A0.17.0-3#~/.yarn/patches/typedoc-npm-0.17.0-3-0ce05847cf.patch"
+    "yoga-layout-prebuilt": "patch:[email protected]#./.yarn/patches/yoga-layout-prebuilt.patch"
   },
   "dependenciesMeta": {
     "core-js": {
@@ -48,27 +46,6 @@
     },
     "fsevents": {
       "built": false
-    },
-    "gatsby": {
-      "built": false
-    },
-    "gatsby-cli": {
-      "built": false
-    },
-    "[email protected]": {
-      "unplugged": true
-    },
-    "gatsby-telemetry": {
-      "built": false
-    },
-    "[email protected]": {
-      "unplugged": true
-    },
-    "[email protected]": {
-      "unplugged": true
-    },
-    "svg2png": {
-      "unplugged": true
     }
   },
   "scripts": {

README.md

@@ -2,13 +2,7 @@
 
 This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 
-### Installation
-
-```
-$ yarn
-```
-
-### Local Development
+### Development
 
 ```
 $ yarn start
@@ -26,16 +20,4 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+The `master` branch is automatically deployed to https://yarnpkg.com/ via [Netlify](https://www.netlify.com/). Pull Requests are also deployed as Deploy Previews.

package.json

@@ -132,13 +132,13 @@ See also: [Workspaces](/features/workspaces)
 
 A range is a string that, when combined with a package name, can be used to select multiple versions of a single package. Ranges typically follow <abbr>semver</abbr>, but can use any of the supported Yarn protocols.
 
-See also: [Protocols](/features/protocols)
+See also: [Protocols](/protocols)
 
 ### Reference
 
 A reference is a string that, when combined with a package name, can be used to select one single version of a single package. References typically follow <abbr>semver</abbr>, but can use any of the supported Yarn protocols.
 
-See also: [Protocols](/features/protocols)
+See also: [Protocols](/protocols)
 
 ### Resolver
 
@@ -192,7 +192,7 @@ Generally speaking workspaces are a Yarn features used to work on multiple proje
 
 In the context of Yarn's vocabulary, workspaces are local <abbr>packages</abbr> that directly belong to a <abbr>project</abbr>.
 
-See also: [Packages](/features/packages), [Workspaces](/features/workspaces)
+See also: [Workspaces](/features/workspaces)
 
 ### Worktree
 

packages/docusaurus/README.md

@@ -26,7 +26,7 @@ Although rarely called directly, `yarn pack` is a crucial part of Yarn. Each tim
 This script is called before `yarn npm publish` before the package has even been packed. This is the place where you'll want to check that the project is in an ok state.
 
 :::caution
-Because it's only called on prepublish, **the prepublish hook shouldn't have side effects.** In particular don't transpile the package sources in `prepublish`, as people consuming directly your repository (such as through the [`git:` protocol](/features/protocols#git)) wouldn't be able to use your project. Instead, use `prepack`.
+Because it's only called on prepublish, **the prepublish hook shouldn't have side effects.** In particular don't transpile the package sources in `prepublish`, as people consuming directly your repository (such as through the [`git:` protocol](/protocol/git)) wouldn't be able to use your project. Instead, use `prepack`.
 :::
 
 ## `postinstall`

packages/docusaurus/docs/advanced/01-general-reference/lexicon.md

@@ -9,10 +9,6 @@ Writing portable packages is incredibly important, as it ensures that your users
 
 To help with that, this page details the up-to-date collection of good practices you should follow in order to make your package work seamlessly on all three main package managers (Yarn, pnpm, and npm), and explanations if you want to learn more.
 
-```toc
-# This code block gets replaced with the Table of Contents
-```
-
 ## Packages should only ever require what they formally list in their dependencies
 
 **Why?** Because otherwise your package will be susceptible to unpredictable [hoisting](/advanced/lexicon#hoisting) that will lead some of your consumers to experience pseudo-random crashes, depending on the other packages they will happen to use.

packages/docusaurus/docs/advanced/02-package-management/lifecycle-scripts.md

@@ -265,7 +265,7 @@ This function will return `null` if the request is a builtin module, unless `con
 export function resolveVirtual(path: string): string | null;
 ```
 
-**Important:** This function is not part of the Plug'n'Play specification and only available as a Yarn extension. In order to use it, you first must check that the [`VERSIONS`](/advanced/pnp-api#versions) dictionary contains a valid `resolveVirtual` property.
+**Important:** This function is not part of the Plug'n'Play specification and only available as a Yarn extension. In order to use it, you first must check that the [`VERSIONS`](/advanced/pnpapi#versions) dictionary contains a valid `resolveVirtual` property.
 
 The `resolveVirtual` function will accept any path as parameter and return the same path minus any [virtual component](/advanced/lexicon#virtual-package). This makes it easier to store the location to the files in a portable way as long as you don't care about losing the dependency tree information in the process (requiring files through those paths will prevent them from accessing their peer dependencies).
 

packages/docusaurus/docs/advanced/02-package-management/rulebook.md

@@ -295,7 +295,7 @@ FIND_PNP_MANIFEST(url)
 
 Finding the right PnP manifest to use for a resolution isn't always trivial. There are two main options:
 
-- Assume that there is a single PnP manifest covering the whole project. This is the most common case, as even when referencing third-party projects (for example via the [`portal:` protocol](/features/protocols#whats-the-difference-between-link-and-portal)) their dependency trees are stored in the same manifest as the main project.
+- Assume that there is a single PnP manifest covering the whole project. This is the most common case, as even when referencing third-party projects (for example via the [`portal:` protocol](/protocol/portal#portals-vs-links)) their dependency trees are stored in the same manifest as the main project.
 
   To do that, call [`FIND_CLOSEST_PNP_MANIFEST`](#find_closest_pnp_manifest)`(require.main.filename)` once at the start of the process, cache its result, and return it for each call to [`FIND_PNP_MANIFEST`](#find_pnp_manifest) (if you're running in Node.js, you can even use `require.resolve('pnpapi')` which will do this work for you).
 

packages/docusaurus/docs/advanced/03-pnp/pnp-api.md

@@ -31,7 +31,7 @@ What happens when running `yarn install` can be summarized in a few different st
 
     - Now that we have the exact set of packages that make up our dependency tree, we iterate over it and for each of them we start a new request to the cache to know whether the package is anywhere to be found. If it isn't we do just like we did in the previous step and we ask our plugins (through the [`Fetcher`](https://github.com/yarnpkg/berry/blob/master/packages/yarnpkg-core/sources/Fetcher.ts) interface) whether they know about the package ([`supports`](https://github.com/yarnpkg/berry/blob/master/packages/yarnpkg-core/sources/Fetcher.ts#L43)) and if so to retrieve it from whatever its remote location is ([`fetch`](https://github.com/yarnpkg/berry/blob/master/packages/yarnpkg-core/sources/Fetcher.ts#L67)).
 
-    - Interesting tidbit regarding the fetchers: they communicate with the core through an abstraction layer over `fs`. We do this so that our packages can come from many different sources - it can be from a zip archive for packages downloaded from a registry, or from an actual directory on the disk for [`portal:`](/features/protocols#portal) dependencies.
+    - Interesting tidbit regarding the fetchers: they communicate with the core through an abstraction layer over `fs`. We do this so that our packages can come from many different sources - it can be from a zip archive for packages downloaded from a registry, or from an actual directory on the disk for [`portal:`](/protocol/portal) dependencies.
 
 3. And finally, once all the packages are ready for consumption, comes the "link step":
 

packages/docusaurus/docs/advanced/03-pnp/pnp-spec.md

@@ -5,7 +5,7 @@ title: "Plugin Tutorial"
 description: A basic plugin tutorial which shows how to work with Yarn's plugin API.
 ---
 
-Starting from the Yarn 2, Yarn now supports plugins. For more information about what they are and in which case you'd want to use them, consult the [dedicated page](/features/plugins). We'll talk here about the exact steps needed to write one. It's quite simple, really!
+Starting from the Yarn 2, Yarn now supports plugins. For more information about what they are and in which case you'd want to use them, consult the [dedicated page](/features/extensibility). We'll talk here about the exact steps needed to write one. It's quite simple, really!
 
 ## What does a plugin look like?
 

packages/docusaurus/docs/advanced/04-technical/architecture.md

@@ -6,7 +6,7 @@ description: An in-depth guide to Yarn's constraints, a feature that provides an
 ---
 
 :::info
-This page documents the new JavaScript-based constraints. The older constraints, based on Prolog, are still supported but should be considered deprecated. Their documentation can be found [here](/features/constraints-prolog).
+This page documents the new JavaScript-based constraints. The older constraints, based on Prolog, are still supported but should be considered deprecated. Their documentation can be found [here](https://v3.yarnpkg.com/features/constraints).
 :::
 
 ## Overview
@@ -156,4 +156,3 @@ module.exports = defineConfig({
   },
 });
 ```
-

packages/docusaurus/docs/advanced/04-technical/plugin-tutorial.md

@@ -27,6 +27,6 @@ By default, `yarn patch` will always reset the patch. If you wish to add new cha
 
 ## Limitations
 
-- Because they're currently computed at fetch time rather than resolution time, the package dependencies have already been resolved and patches won't be able to alter them.
+- Because they're currently computed at fetch time rather than resolution time, the package dependencies have already been resolved and patches won't be able to alter them. Instead, use the `packageExtensions` mechanism which is specifically made to add new runtime dependencies to packages.
 
 - Patches are ill-suited for modifying binary files. Minified files are problematic as well, although we could improve the feature to automatically process such files through a Prettier-like tool.