docs: try to make plugin/preset config less confusing (#5313)

website/docs/api/plugins/plugin-content-blog.md

@@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-blog
 
 :::tip
 
-If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
+If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
+
+You can configure this plugin through the [preset options](#ex-config-preset).
 
 :::
 
@@ -65,14 +67,20 @@ type EditUrlFunction = (params: {
 }) => string | undefined;
 ```
 
-Example configuration:
+## Example configuration {#ex-config}
 
-```js title="docusaurus.config.js"
+Here's an example configuration object.
-module.exports = {
+
-  plugins: [
+You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
-    [
+
-      '@docusaurus/plugin-content-blog',
+:::tip
-      {
+
+Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
+
+:::
+
+```js
+const config = {
   path: 'blog',
   // Simple use-case: string editUrl
   // editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
@@ -111,7 +119,46 @@ module.exports = {
     copyright: '',
     language: undefined,
   },
+};
+```
+
+### Preset options {#ex-config-preset}
+
+If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        // highlight-start
+        blog: {
+          path: 'blog',
+          // ... configuration object here
         },
+        // highlight-end
+      },
+    ],
+  ],
+};
+```
+
+### Plugin options {#ex-config-plugin}
+
+If you are using a standalone plugin, provide options directly to the plugin:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-blog',
+      // highlight-start
+      {
+        path: 'blog',
+        // ... configuration object here
+      },
+      // highlight-end
     ],
   ],
 };

website/docs/api/plugins/plugin-content-docs.md

@@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-docs
 
 :::tip
 
-If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
+If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
+
+You can configure this plugin through the [preset options](#ex-config-preset).
 
 :::
 
@@ -91,14 +93,20 @@ type Versions = Record<
 >;
 ```
 
-Example configuration:
+## Example configuration {#ex-config}
 
-```js title="docusaurus.config.js"
+Here's an example configuration object.
-module.exports = {
+
-  plugins: [
+You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
-    [
+
-      '@docusaurus/plugin-content-docs',
+:::tip
-      {
+
+Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
+
+:::
+
+```js
+const config = {
   path: 'docs',
   // Simple use-case: string editUrl
   // editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
@@ -173,7 +181,46 @@ module.exports = {
     },
   },
   onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
+};
+```
+
+### Preset options {#ex-config-preset}
+
+If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        // highlight-start
+        docs: {
+          path: 'docs',
+          // ... configuration object here
         },
+        // highlight-end
+      },
+    ],
+  ],
+};
+```
+
+### Plugin options {#ex-config-plugin}
+
+If you are using a standalone plugin, provide options directly to the plugin:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      // highlight-start
+      {
+        path: 'docs',
+        // ... configuration object here
+      },
+      // highlight-end
     ],
   ],
 };

website/docs/api/plugins/plugin-content-pages.md

@@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-pages
 
 :::tip
 
-If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
+If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
+
+You can configure this plugin through the [preset options](#ex-config-preset).
 
 :::
 
@@ -27,7 +29,7 @@ Accepted fields:
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `path` | `string` | `'src/pages'` | Path to data on filesystem relative to site dir. Components in this directory will be automatically converted to pages. |
-| `routeBasePath` | `string` | `'/'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. |
+| `routeBasePath` | `string` | `'/'` | URL route for the pages section of your site. **DO NOT** include a trailing slash. |
 | `include` | `string[]` | `['**/*.{js,jsx,ts,tsx,md,mdx}']` | Matching files will be included and processed. |
 | `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
 | `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. |
@@ -38,14 +40,20 @@ Accepted fields:
 
 </small>
 
-Example configuration:
+## Example configuration {#ex-config}
 
-```js title="docusaurus.config.js"
+Here's an example configuration object.
-module.exports = {
+
-  plugins: [
+You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
-    [
+
-      '@docusaurus/plugin-content-pages',
+:::tip
-      {
+
+Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
+
+:::
+
+```js
+const config = {
   path: 'src/pages',
   routeBasePath: '',
   include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
@@ -60,7 +68,46 @@ module.exports = {
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],
+};
+```
+
+### Preset options {#ex-config-preset}
+
+If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        // highlight-start
+        pages: {
+          path: 'src/pages',
+          // ... configuration object here
         },
+        // highlight-end
+      },
+    ],
+  ],
+};
+```
+
+### Plugin options {#ex-config-plugin}
+
+If you are using a standalone plugin, provide options directly to the plugin:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-pages',
+      // highlight-start
+      {
+        path: 'src/pages',
+        // ... configuration object here
+      },
+      // highlight-end
     ],
   ],
 };