docs: add notes about external packages (#3962)

* docs: add notes about external packages

* docs: fix link

Author: paul-soporan

.yarn/versions/5f57d7bd.yml

@@ -0,0 +1,14 @@
+releases:
+  "@yarnpkg/builder": patch
+  "@yarnpkg/pnpify": patch
+  "@yarnpkg/sdks": patch
+
+declined:
+  - "@yarnpkg/plugin-constraints"
+  - "@yarnpkg/plugin-exec"
+  - "@yarnpkg/plugin-interactive-tools"
+  - "@yarnpkg/plugin-stage"
+  - "@yarnpkg/plugin-typescript"
+  - "@yarnpkg/plugin-version"
+  - "@yarnpkg/plugin-workspace-tools"
+  - "@yarnpkg/cli"

packages/gatsby/gatsby-config.js

@@ -112,19 +112,19 @@ module.exports = {
       options: {
         binaries: [
           {
-            namespace: null,
+            package: null,
             binary: `${__dirname}/../../scripts/run-yarn.js`,
           },
           {
-            namespace: `pnpify`,
+            package: `@yarnpkg/pnpify`,
             binary: `${__dirname}/../../scripts/run-pnpify.js`,
           },
           {
-            namespace: `sdks`,
+            package: `@yarnpkg/sdks`,
             binary: `${__dirname}/../../scripts/run-sdks.js`,
           },
           {
-            namespace: `builder`,
+            package: `@yarnpkg/builder`,
             binary: `${__dirname}/../../scripts/run-builder.js`,
           },
         ],

packages/gatsby/gatsby-plugin-clipanion-cli/gatsby-node.js

@@ -3,9 +3,13 @@ const {execFileSync}  = require(`child_process`);
 exports.sourceNodes = ({actions, createNodeId, createContentDigest}, opts) => {
   const {createNode} = actions;
 
-  for (const {binary, namespace} of opts.binaries) {
-    const namespaceLeadingSlash = namespace ? `/${namespace}` : ``;
-    const namespaceTrailingSlash = namespace ? `${namespace}/` : ``;
+  for (const {binary, package} of opts.binaries) {
+    const packageParts = package?.match(/^(?:@([^/]+?)\/)?([^/]+)$/);
+
+    const [, scope, name] = packageParts ?? [];
+
+    const namespaceLeadingSlash = name ? `/${name}` : ``;
+    const namespaceTrailingSlash = name ? `${name}/` : ``;
 
     const output = execFileSync(`node`, [binary, `--clipanion=definitions`]);
 
@@ -39,7 +43,17 @@ exports.sourceNodes = ({actions, createNodeId, createContentDigest}, opts) => {
         sections.push([
           `> **Plugin**\n`,
           `>\n`,
-          `> To use this command, first install the \`${pluginName}\` plugin: \`yarn plugin import ${pluginName}\`\n`,
+          `> To use this command, first install the [\`${pluginName}\`](https://github.com/yarnpkg/berry/blob/HEAD/packages/plugin-${pluginName}/README.md) plugin: \`yarn plugin import ${pluginName}\`\n`,
+        ].join(``));
+      }
+
+      if (package) {
+        sections.push([
+          `> **External Package**\n`,
+          `>\n`,
+          `> To use this command, you need to use the [\`${package}\`](https://github.com/yarnpkg/berry/blob/HEAD/packages/${scope}-${name}/README.md) package either:\n`,
+          `> - By installing it locally using [\`yarn add\`](/cli/add) and running it using [\`yarn run\`](/cli/run)\n`,
+          `> - By downloading and running it in a temporary environment using [\`yarn dlx\`](/cli/dlx)\n`,
         ].join(``));
       }
 

packages/gatsby/src/components/markdown.js

@@ -48,6 +48,11 @@ const Content = styled.div`
     background-color: #fff3e2;
   }
 
+  blockquote > ul {
+    margin: 0;
+    padding: 0.5em 2em;
+  }
+
   blockquote > p {
     margin: 0;
   }

packages/yarnpkg-builder/README.md

@@ -17,8 +17,8 @@ A CLI tool designed for creating, building, and managing complex plugins.
 
 ## Commands
 
-- [`build bundle`](https://yarnpkg.com/builder/cli/build/bundle) - Build the local bundle.
+- [`builder build bundle`](https://yarnpkg.com/builder/cli/build/bundle) - Build the local bundle.
 
-- [`build plugin`](https://yarnpkg.com/builder/cli/build/plugin) - Build a local plugin.
+- [`builder build plugin`](https://yarnpkg.com/builder/cli/build/plugin) - Build a local plugin.
 
-- [`new plugin`](https://yarnpkg.com/builder/cli/new/plugin) - Create a new plugin.
+- [`builder new plugin`](https://yarnpkg.com/builder/cli/new/plugin) - Create a new plugin.

packages/yarnpkg-builder/sources/commands/build/bundle.ts

@@ -39,6 +39,8 @@ export default class BuildBundleCommand extends Command {
     description: `build the local bundle`,
     details: `
       This command builds the local bundle - the Yarn binary file that is installed in projects.
+
+      For more details about the build process, please consult the \`@yarnpkg/builder\` README: https://github.com/yarnpkg/berry/blob/HEAD/packages/yarnpkg-builder/README.md.
     `,
     examples: [[
       `Build the local bundle`,

packages/yarnpkg-builder/sources/commands/build/plugin.ts

@@ -34,6 +34,8 @@ export default class BuildPluginCommand extends Command {
     description: `build a local plugin`,
     details: `
       This command builds a local plugin.
+
+      For more details about the build process, please consult the \`@yarnpkg/builder\` README: https://github.com/yarnpkg/berry/blob/HEAD/packages/yarnpkg-builder/README.md.
     `,
     examples: [[
       `Build a local plugin`,

packages/yarnpkg-builder/sources/commands/new/plugin.ts

@@ -13,6 +13,8 @@ export default class NewPluginCommand extends Command {
     description: `generate the template for a new plugin`,
     details: `
       This command generates a new plugin based on the template.
+
+      For more details about the build process, please consult the \`@yarnpkg/builder\` README: https://github.com/yarnpkg/berry/blob/HEAD/packages/yarnpkg-builder/README.md.
     `,
     examples: [[
       `Create a new plugin`,

packages/yarnpkg-pnpify/README.md

@@ -0,0 +1,13 @@
+# @yarnpkg/pnpify
+
+A CLI tool designed for running commands with a virtual node_modules folder.
+
+[**Documentation**](https://yarnpkg.com/advanced/pnpify)
+
+## Installation
+
+`yarn add -D @yarnpkg/pnpify`
+
+## Commands
+
+- [`pnpify run`](https://yarnpkg.com/pnpify/cli/run) - Run a command with a virtual node_modules folder.

packages/yarnpkg-pnpify/sources/commands/RunCommand.ts

@@ -17,6 +17,8 @@ export default class RunCommand extends Command {
       When a non-PnP-compliant project tries to access the \`node_modules\` directories (for example through \`readdir\` or \`readFile\`), PnPify intercepts those calls and converts them into calls to the PnP API. Then, based on the result, it simulates the existence of a virtual \`node_modules\` folder that the underlying tool will then consume - still unaware that the files are extracted from a virtual filesystem.
 
       The \`run\` keyword can be omitted if the executed command doesn't conflict with built-in commands.
+
+      For more details on PnPify, please consult the dedicated page from our website: https://yarnpkg.com/advanced/pnpify.
     `,
     examples: [[
       `Run Angular using PnPify`,

packages/yarnpkg-sdks/README.md

@@ -0,0 +1,11 @@
+# @yarnpkg/sdks
+
+A CLI tool designed for generating and updating [Editor SDKs](https://yarnpkg.com/getting-started/editor-sdks) and settings.
+
+## Installation
+
+`yarn add -D @yarnpkg/sdks`
+
+## Commands
+
+- [`sdks`](https://yarnpkg.com/sdks/cli/default) - Generate editor SDKs and settings.

packages/yarnpkg-sdks/sources/commands/SdkCommand.ts

@@ -32,6 +32,8 @@ export default class SdkCommand extends Command {
       The supported integrations at this time are: ${[...SUPPORTED_INTEGRATIONS.keys()].map(integration => `\`${integration}\``).join(`, `)}.
 
       **Note:** This command always updates the already-installed SDKs and editor settings, no matter which arguments are passed.
+
+      For more details on Editor SDKs, please consult the dedicated page from our website: https://yarnpkg.com/getting-started/editor-sdks.
     `,
     examples: [[
       `Generate the base SDKs`,