Minor tweaks to website (#6264)

## What's the problem this PR addresses?

Some minor/nitpick-level problems with the website

Note: This PR has *some* overlap with #6218. I'll rebase one when the
other is merged

## How did you fix it?

- Removed remnants of TypeScript misconfiguration created when first
adding the docusaurus workspace via `create-docusaurus`
- Reorganized the directory structure of the docusaurus workspace. In
particular, moved stuff that is run in build-time (except the
`docusaurus.config.ts` itself) to a `config` directory. May not seem
like much but as more stuff gets added this can keep thing clean and
manageable.
- Used admonitions instead of plain text where appropriate
- Made the remark plugins apply to the CHANGELOG (they weren't before)
- Cleaned up and reorganized the dependencies. Of course there are
different schools of philosophy regarding what should count as a
dependency vs devDependency in a frontend app. Ultimately I decided for
Docusaurus, it makes more sense to say everything needed to run `yarn
build` successfully is a dep and devDeps are those that are purely for
DX (e.g. types)
- Removed babel and browserslist config as we are not using them at all

## 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.

packages/docusaurus/config/docusaurus/plugins/webpack-config.ts

@@ -0,0 +1,74 @@
+import type {Options as MDXLoaderOptions, MDXOptions} from '@docusaurus/mdx-loader';
+import type {LoadContext, Plugin}                     from '@docusaurus/types';
+import {createRequire}                                from 'node:module';
+import path                                           from 'node:path';
+
+const webpack = createRequire(require.resolve(`@docusaurus/core/package.json`))(`webpack`);
+
+export type Options = {
+  changelog: Partial<MDXOptions>;
+};
+
+const plugin = async function(context: LoadContext, options: Options): Promise<Plugin> {
+  return {
+    name: `docusaurus-plugin-yarn-webpack-config`,
+    configureWebpack(config, isServer, utils) {
+      return {
+        module: {
+          rules: [
+            {
+              test: /\.term\.dat$/,
+              use: [require.resolve(`../../webpack/ansi-loader.js`)],
+            },
+            {
+              test: /\.mdx?$/,
+              include: require.resolve(`@yarnpkg/monorepo/CHANGELOG.md`),
+              use: [
+                utils.getJSLoader({isServer}),
+                {
+                  loader: require.resolve(`@docusaurus/mdx-loader`),
+                  options: {
+                    admonitions: true,
+                    siteDir: context.siteDir,
+                    staticDirs: context.siteConfig.staticDirectories.map(dir => path.resolve(context.siteDir, dir)),
+                    isMDXPartial: () => true,
+                    isMDXPartialFrontMatterWarningDisabled: true,
+                    markdownConfig: context.siteConfig.markdown,
+                    ...options.changelog,
+                  } satisfies MDXLoaderOptions,
+                },
+              ],
+            },
+          ],
+        },
+        resolve: {
+          fallback: {
+            fs: false,
+            module: false,
+            buffer: false,
+            os: require.resolve(`os-browserify`),
+            path: require.resolve(`path-browserify`),
+          },
+          alias: {
+            '@mdx-js/react': require.resolve(`@mdx-js/react`),
+            react: path.resolve(require.resolve(`react/package.json`), `..`),
+          },
+        },
+        plugins: [
+          new webpack.DefinePlugin({
+            [`process.env`]: JSON.stringify({
+              NODE_ENV: `development`,
+            }),
+            [`process.platform`]: JSON.stringify(`browser`),
+            [`process.versions`]: JSON.stringify({
+              node: `18.0.0`,
+            }),
+          }),
+        ],
+      };
+    },
+  };
+};
+
+// eslint-disable-next-line arca/no-default-export
+export default plugin;

packages/docusaurus/src/remark/autoLink.ts → packages/docusaurus/config/remark/autoLink.ts

@@ -3,7 +3,6 @@ import type {MdxJsxFlowElement} from 'mdast-util-mdx-jsx';
 import type {Parent, Root}      from 'mdast';
 import type {Transformer}       from 'unified';
 import {visitParents as visit}  from 'unist-util-visit-parents';
-import {pathToFileURL}          from 'url';
 
 export type AutoLinkSpec = {
   sourceType: `json-schema`;
@@ -95,8 +94,7 @@ export const plugin = (userSpecs: Array<AutoLinkSpec>) => () => {
     });
 
     if (hasAutoLinks) {
-      const url = pathToFileURL(require.resolve(`../components/AutoLink.tsx`));
-      const code = `import {AutoLink} from ${JSON.stringify(url)};\n`;
+      const code = `import {AutoLink} from "@site/src/components/AutoLink.tsx";\n`;
       ast.children.unshift({
         type: `mdxjsEsm`,
         value: code,

packages/docusaurus/src/remark/commandLineHighlight.ts → packages/docusaurus/config/remark/commandLineHighlight.ts

@@ -1,13 +1,12 @@
 import {YarnCli, getCli}        from '@yarnpkg/cli';
 import {parseShell}             from '@yarnpkg/parsers';
-import {Definition, Token}      from 'clipanion';
+import type {Definition, Token} from 'clipanion';
 import {fromJs}                 from 'esast-util-from-js';
 import {capitalize}             from 'lodash';
 import type {MdxJsxFlowElement} from 'mdast-util-mdx-jsx';
 import type {Parent, Root}      from 'mdast';
 import type {Transformer}       from 'unified';
 import {visitParents as visit}  from 'unist-util-visit-parents';
-import {pathToFileURL}          from 'url';
 
 export type ScriptLine =
   | RawLine
@@ -198,8 +197,7 @@ export const plugin = () => () => {
     });
 
     if (highlightNodes.length > 0) {
-      const url = pathToFileURL(require.resolve(`../components/CommandLineHighlight.tsx`));
-      const code = `import {CommandLineHighlight} from ${JSON.stringify(url)};\n`;
+      const code = `import {CommandLineHighlight} from "@site/src/components/CommandLineHighlight.tsx";\n`;
       ast.children.unshift({
         type: `mdxjsEsm`,
         value: code,

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

@@ -120,7 +120,9 @@ export const VERSIONS: {std: number, [key: string]: number};
 
 The `VERSIONS` object contains a set of numbers that detail which version of the API is currently exposed. The only version that is guaranteed to be there is `std`, which will refer to the version of this document. Other keys are meant to be used to describe extensions provided by third-party implementors. Versions will only be bumped when the signatures of the public API change.
 
-**Note:** The current version is 3. We bump it responsibly and strive to make each version backward-compatible with the previous ones, but as you can probably guess some features are only available with the latest versions.
+:::note
+The current version is 3. We bump it responsibly and strive to make each version backward-compatible with the previous ones, but as you can probably guess some features are only available with the latest versions.
+:::
 
 ### `topLevel`
 
@@ -132,7 +134,9 @@ The `topLevel` object is a simple package locator pointing to the top-level pack
 
 This object is provided for convenience and doesn't necessarily needs to be used; you may create your own top-level locator by using your own locator literal with both fields set to `null`.
 
-**Note:** These special top-level locators are merely aliases to physical locators, which can be accessed by calling `findPackageLocator`.
+:::note
+These special top-level locators are merely aliases to physical locators, which can be accessed by calling `findPackageLocator`.
+:::
 
 ### `getLocator(...)`
 
@@ -152,15 +156,19 @@ export function getDependencyTreeRoots(): PackageLocator[];
 
 The `getDependencyTreeRoots` function will return the set of locators that constitute the roots of individual dependency trees. In Yarn, there is exactly one such locator for each workspace in the project.
 
-**Note:** This function will always return the physical locators, so it'll never return the special top-level locator described in the `topLevel` section.
+:::note
+This function will always return the physical locators, so it'll never return the special top-level locator described in the `topLevel` section.
+:::
 
 ### `getAllLocators(...)`
 
 ```ts
 export function getAllLocators(): PackageLocator[];
 ```
 
-**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 `getAllLocators` property.
+:::warning 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 `getAllLocators` property.
+:::
 
 The `getAllLocators` function will return all locators from the dependency tree, in no particular order (although it'll always be a consistent order between calls for the same API). It can be used when you wish to know more about the packages themselves, but not about the exact tree layout.
 
@@ -180,7 +188,9 @@ export function findPackageLocator(location: string): PackageLocator | null;
 
 Given a location on the disk, the `findPackageLocator` function will return the package locator for the package that "owns" the path. For example, running this function on something conceptually similar to `/path/to/node_modules/foo/index.js` would return a package locator pointing to the `foo` package (and its exact version).
 
-**Note:** This function will always return the physical locators, so it'll never return the special top-level locator described in the `topLevel` section. You can leverage this property to extract the physical locator for the top-level package:
+:::note
+This function will always return the physical locators, so it'll never return the special top-level locator described in the `topLevel` section. You can leverage this property to extract the physical locator for the top-level package:
+:::
 
 ```ts
 const virtualLocator = pnpApi.topLevel;
@@ -265,7 +275,9 @@ 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/pnpapi#versions) dictionary contains a valid `resolveVirtual` property.
+:::warning 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).
 
@@ -302,7 +314,9 @@ console.log(crossFs.readFileSync(`C:\\path\\to\\archive.zip\\package.json`));
 
 The following function implements a tree traversal in order to print the list of locators from the tree.
 
-**Important note:** This implementation iterates over **all** the nodes in the tree, even if they are found multiple times (which is very often the case). As a result the execution time is way higher than it could be. Optimize as needed 🙂
+:::warning important
+This implementation iterates over **all** the nodes in the tree, even if they are found multiple times (which is very often the case). As a result the execution time is way higher than it could be. Optimize as needed 🙂
+:::
 
 ```ts
 const pnp = require(`pnpapi`);

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

@@ -235,7 +235,9 @@ GET_PACKAGE(manifest, locator)
 FIND_LOCATOR(manifest, moduleUrl)
 ```
 
-Note: The algorithm described here is quite inefficient. You should make sure to prepare data structure more suited for this task when you read the manifest.
+:::note
+The algorithm described here is quite inefficient. You should make sure to prepare data structure more suited for this task when you read the manifest.
+:::
 
 1. Let `bestLength` be **0**
 

packages/docusaurus/docs/advanced/04-technical/contributing.mdx

@@ -116,7 +116,9 @@ yarn version check --interactive
 
 If it fails and you have no idea why, feel free to ping a maintainer and we'll do our best to help you.
 
-**Note:** If you modify one of the [default plugins](https://github.com/yarnpkg/berry#default-plugins), you will also need to bump `@yarnpkg/cli`.
+:::note
+If you modify one of the [default plugins](https://github.com/yarnpkg/berry#default-plugins), you will also need to bump `@yarnpkg/cli`.
+:::
 
 ## Reviewing other PRs
 
@@ -125,7 +127,7 @@ It's generally seen as [bad form](https://twitter.com/brian_d_vaughn/status/1224
 
 ## Writing documentation
 
-We use [Docusaurus](https://docusaurus.io/docs) to generate HTML pages from [mdx](https://mdxjs.com/docs/) sources files. 
+We use [Docusaurus](https://docusaurus.io/docs) to generate HTML pages from [mdx](https://mdxjs.com/docs/) sources files.
 
 Our website is stored within the [`packages/docusaurus`](https://github.com/yarnpkg/berry/tree/master/packages/docusaurus) directory. You can change a page by modifying the corresponding `.mdx` file in the `docs` folder. For example, you'd edit this very page [here](https://github.com/yarnpkg/berry/blob/master/packages/docusaurus/docs/advanced/04-technical/contributing.md).
 

packages/docusaurus/docs/features/constraints.mdx

@@ -136,7 +136,7 @@ const {defineConfig} = require(`@yarnpkg/types`);
 /**
  * This rule will enforce that a workspace MUST depend on the same version of
  * a dependency as the one used by the other workspaces.
- * 
+ *
  * @param {Context} context
  */
 function enforceConsistentDependenciesAcrossTheProject({Yarn}) {

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

@@ -7,9 +7,7 @@ sidebar_position: 2
 ---
 
 :::tip
-
 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](/corepack), if it isn't already; this will add the `yarn` binary to your PATH:

packages/docusaurus/docs/getting-started/extra/questions-and-answers.mdx

@@ -91,12 +91,14 @@ If you're interested to know more about each of these files:
 
 - `.yarnrc.yml` (and its older counterpart, `.yarnrc`) are configuration files. They should always be stored in your project.
 
-> **Tip:** You can also add a `.gitattributes` file to identify the release and plugin bundles as binary content. This way Git won't bother showing massive diffs when each time you subsequently add or update them:
->
-> ```gitattributes
-> /.yarn/releases/** binary
-> /.yarn/plugins/** binary
-> ```
+:::tip
+You can also add a `.gitattributes` file to identify the release and plugin bundles as binary content. This way Git won't bother showing massive diffs when each time you subsequently add or update them:
+
+```gitattributes
+/.yarn/releases/** binary
+/.yarn/plugins/** binary
+```
+:::
 
 ## Does Yarn support ESM?
 

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

@@ -116,7 +116,9 @@ yarn jest
 
 We now need to inject some variables into the environment for Node to be able to locate your dependencies. In order to make this possible, we ask you to use `yarn node` which transparently does the heavy lifting.
 
-**Note:** this section only applies to the _shell CLI_. The commands defined in your `scripts` are unaffected, as we make sure that `node` always points to the right location, with the right variables already set.
+:::note
+this section only applies to the _shell CLI_. The commands defined in your `scripts` are unaffected, as we make sure that `node` always points to the right location, with the right variables already set.
+:::
 
 ### Setup your IDE for PnP support
 

packages/docusaurus/docusaurus.config.ts

@@ -9,8 +9,8 @@ import * as path                                                    from 'node:p
 import {themes}                                                     from 'prism-react-renderer';
 import {satisfies}                                                  from 'semver';
 
-import * as autoLink                                                from './src/remark/autoLink';
-import * as commandLineHighlight                                    from './src/remark/commandLineHighlight';
+import * as autoLink                                                from './config/remark/autoLink';
+import * as commandLineHighlight                                    from './config/remark/commandLineHighlight';
 
 const remarkPlugins = [
   commandLineHighlight.plugin(),
@@ -89,7 +89,7 @@ async function typedocPluginConfig(): Promise<Partial<DocusaurusPluginTypeDocApi
     readmes: true,
     gitRefName: process.env.COMMIT_REF ?? `master`,
     typedocOptions: {
-      plugin: [`./src/typedoc/plugin.ts`],
+      plugin: [`./config/typedoc/plugin.ts`],
     },
     remarkPlugins,
   };
@@ -141,7 +141,14 @@ export default async function (): Promise<Config> {
     },
 
     plugins: [
-      require.resolve(`./plugin`),
+      [
+        `./config/docusaurus/plugins/webpack-config.ts`,
+        {
+          changelog: {
+            remarkPlugins,
+          },
+        },
+      ],
       [
         `docusaurus-plugin-typedoc-api`,
         await typedocPluginConfig(),
@@ -154,7 +161,7 @@ export default async function (): Promise<Config> {
         options: {
           loader: `tsx`,
           format: isServer ? `cjs` : undefined,
-          target: isServer ? `node12` : `es2017`,
+          target: isServer ? `node18` : `es2017`,
         },
       }),
     },
@@ -174,12 +181,12 @@ export default async function (): Promise<Config> {
                 label: `master (${YarnVersion})`,
               },
             },
-            sidebarPath: require.resolve(`./sidebars.ts`),
+            sidebarPath: `./config/docusaurus/sidebars.ts`,
             editUrl: `https://github.com/yarnpkg/berry/edit/master/packages/docusaurus/`,
             remarkPlugins,
           },
           theme: {
-            customCss: require.resolve(`./src/css/custom.css`),
+            customCss: `./src/css/custom.css`,
           },
         } satisfies Options,
       ],