feat: shorthands for themes/plugins/presets configuration (#5930)

Co-authored-by: Josh-Cena <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

website/_dogfooding/dogfooding.config.js

@@ -10,7 +10,7 @@ const fs = require('fs');
 /** @type {import('@docusaurus/types').PluginConfig[]} */
 const dogfoodingPluginInstances = [
   [
-    '@docusaurus/plugin-content-docs',
+    'content-docs', // dogfood shorthand
     /** @type {import('@docusaurus/plugin-content-docs').Options} */
     ({
       id: 'docs-tests',
@@ -24,7 +24,7 @@ const dogfoodingPluginInstances = [
   ],
 
   [
-    '@docusaurus/plugin-content-blog',
+    '@docusaurus/plugin-content-blog', // dogfood longhand
     /** @type {import('@docusaurus/plugin-content-blog').Options} */
     ({
       id: 'blog-tests',
@@ -46,7 +46,7 @@ const dogfoodingPluginInstances = [
   ],
 
   [
-    '@docusaurus/plugin-content-pages',
+    require.resolve('@docusaurus/plugin-content-pages'), // dogfood longhand resolve
     /** @type {import('@docusaurus/plugin-content-pages').Options} */
     ({
       id: 'pages-tests',

website/docs/configuration.md

@@ -48,6 +48,65 @@ module.exports = {
 };
 ```
 
+:::tip
+
+Docusaurus supports **module shorthands**, allowing you to simplify the above configuration as:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  // ...
+  plugins: ['content-blog', 'content-pages'],
+  themes: ['classic'],
+};
+```
+
+<details>
+
+<summary>How are shorthands resolved?</summary>
+
+When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:
+
+- `{name}`
+- `@docusaurus/{type}-{name}`
+- `docusaurus-{type}-{name}`,
+
+where `type` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded.
+
+If the name is scoped (beginning with `@`), the name is first split into scope and package name by the first slash:
+
+```
+@scope
+^----^
+ scope  (no name!)
+
+@scope/awesome
+^----^ ^-----^
+ scope   name
+
+@scope/awesome/main
+^----^ ^----------^
+ scope     name
+```
+
+If the name is not specified, `{scope}/docusaurus-{type}` is loaded. Otherwise, the following are attempted:
+
+- `{scope}/{name}`
+- `{scope}/docusaurus-{type}-{name}`
+
+Below are some examples, for a plugin registered in the `plugins` field. Note that unlike [ESLint](https://eslint.org/docs/user-guide/configuring/plugins#configuring-plugins) or [Babel](https://babeljs.io/docs/en/options#name-normalization) where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.
+
+| Declaration | May be resolved as |
+| --- | --- |
+| `awesome` | `docusaurus-plugin-awesome` |
+| `sitemap` | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) |
+| `@mycompany` | `@mycompany/docusaurus-plugin` (the only possible resolution!) |
+| `@mycompany/awesome` | `@mycompany/docusaurus-plugin-awesome` |
+| `@mycompany/awesome/web` | `@mycompany/docusaurus-plugin-awesome/web` |
+
+</details>
+
+:::
+
 They can also be loaded from local directories:
 
 ```js title="docusaurus.config.js"
@@ -66,7 +125,7 @@ module.exports = {
   // ...
   plugins: [
     [
-      '@docusaurus/plugin-content-blog',
+      'content-blog',
       {
         path: 'blog',
         routeBasePath: 'blog',
@@ -74,7 +133,7 @@ module.exports = {
         // ...
       },
     ],
-    '@docusaurus/plugin-content-pages',
+    'content-pages',
   ],
 };
 ```
@@ -100,6 +159,12 @@ module.exports = {
 };
 ```
 
+:::tip
+
+The `presets: [['classic', {...}]]` shorthand works as well.
+
+:::
+
 For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
 
 ### Custom configurations {#custom-configurations}

website/docusaurus.config-blog-only.js

@@ -15,11 +15,11 @@ module.exports = {
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
   favicon: 'img/docusaurus.ico',
-  themes: ['@docusaurus/theme-live-codeblock'],
+  themes: ['live-codeblock'],
   plugins: [],
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       {
         docs: false,
         pages: false,

website/docusaurus.config.js

@@ -119,11 +119,11 @@ const config = {
     path.join(__dirname, '_dogfooding/_asset-tests'),
   ],
   clientModules: [require.resolve('./_dogfooding/clientModuleExample.ts')],
-  themes: ['@docusaurus/theme-live-codeblock'],
+  themes: ['live-codeblock'],
   plugins: [
     FeatureRequestsPlugin,
     [
-      '@docusaurus/plugin-content-docs',
+      'content-docs',
       /** @type {import('@docusaurus/plugin-content-docs').Options} */
       ({
         id: 'community',
@@ -142,7 +142,7 @@ const config = {
       }),
     ],
     [
-      '@docusaurus/plugin-client-redirects',
+      'client-redirects',
       /** @type {import('@docusaurus/plugin-client-redirects').Options} */
       ({
         fromExtensions: ['html'],
@@ -171,7 +171,7 @@ const config = {
       }),
     ],
     [
-      '@docusaurus/plugin-ideal-image',
+      'ideal-image',
       {
         quality: 70,
         max: 1030, // max resized image's size.
@@ -180,7 +180,7 @@ const config = {
       },
     ],
     [
-      '@docusaurus/plugin-pwa',
+      'pwa',
       {
         debug: isDeployPreview,
         offlineModeActivationStrategies: [
@@ -244,7 +244,7 @@ const config = {
   ],
   presets: [
     [
-      '@docusaurus/preset-classic',
+      'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         debug: true, // force debug plugin usage