feat(v2): allow user to customize/enhance the default sidebar items generator (#4658)

* allow and document how to wrap/enhance the default docusaurus sidebar items generator

* improve doc

* doc

* doc

website/docs/guides/docs/sidebar.md

@@ -521,14 +521,19 @@ module.exports = {
     [
       '@docusaurus/plugin-content-docs',
       {
-        /**
-         * Function used to replace the sidebar items of type "autogenerated"
-         * by real sidebar items (docs, categories, links...)
-         */
         // highlight-start
-        sidebarItemsGenerator: function ({item, version, docs}) {
-          // Use the provided data to create a custom "sidebar slice"
-          return [{type: 'doc', id: 'doc1'}];
+        sidebarItemsGenerator: async function ({
+          defaultSidebarItemsGenerator,
+          numberPrefixParser,
+          item,
+          version,
+          docs,
+        }) {
+          // Example: return an hardcoded list of static sidebar items
+          return [
+            {type: 'doc', id: 'doc1'},
+            {type: 'doc', id: 'doc2'},
+          ];
         },
         // highlight-end
       },
@@ -537,6 +542,51 @@ module.exports = {
 };
 ```
 
+:::tip
+
+**Re-use and enhance the default generator** instead of writing a generator from scratch.
+
+**Add, update, filter, re-order** the sidebar items according to your use-case:
+
+```js title="docusaurus.config.js"
+// highlight-start
+// Reverse the sidebar items ordering (including nested category items)
+function reverseSidebarItems(items) {
+  // Reverse items in categories
+  const result = items.map((item) => {
+    if (item.type === 'category') {
+      return {...item, items: reverseSidebarItems(item.items)};
+    }
+    return item;
+  });
+  // Reverse items at current level
+  result.reverse();
+  return result;
+}
+// highlight-end
+
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        // highlight-start
+        sidebarItemsGenerator: async function ({
+          defaultSidebarItemsGenerator,
+          ...args
+        }) {
+          const sidebarItems = await defaultSidebarItemsGenerator(args);
+          return reverseSidebarItems(sidebarItems);
+        },
+        // highlight-end
+      },
+    ],
+  ],
+};
+```
+
+:::
+
 ## Hideable sidebar {#hideable-sidebar}
 
 Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).