Update docs

docs/src/pages/configurations/options-parameter/index.md

@@ -76,7 +76,9 @@ addons.setConfig({
 
 ### Sorting stories
 
-Import and use `addParameters` with the `options` key in your `preview.js` file.
+By default, stories are sorted in the order in which they were imported. This can be overridden by adding `storySort` to the `options` parameters in your `preview.js` file.
+
+The most powerful method of sorting is to provide a function to `storySort`. Any custom sorting can be achieved with this method.
 
 ```js
 import { addParameters, configure } from '@storybook/react';
@@ -86,9 +88,65 @@ addParameters({
     storySort: (a, b) =>
       a[1].kind === b[1].kind ? 0 : a[1].id.localeCompare(b[1].id, undefined, { numeric: true }),
   },
-};
+});
+```
+
+The `storySort` can also accept a configuration object.
+
+```js
+import { addParameters, configure } from '@storybook/react';
+
+addParameters({
+  options: {
+    storySort: {
+      method: 'alphabetical', // Optional, defaults to 'configure'.
+      sort: ['Intro', 'Components'], // Optional, defaults to [].
+      locales: 'en-US', // Optional, defaults to system locale.
+    },
+  },
+});
+```
+
+To sort your stories alphabetically, set `method` to `'alphabetical'` and optionally set the `locales` string. To sort your stories using a custom list, use the `sort` array; stories that don't match an item in the `sort` list will appear after the items in the list. 2nd
+
+The `sort` array can accept a nested array in order to sort 2nd-level story kinds. For example:
+
+```js
+import { addParameters, configure } from '@storybook/react';
+
+addParameters({
+  options: {
+    storySort: {
+      sort: [
+        'Intro',
+        'Pages',
+        [
+          'Home',
+          'Login',
+          'Admin',
+        ],
+        'Components',
+      ],
+    },
+  },
+});
 ```
 
+Which would result in this story ordering:
+
+1. `Intro` and then `Intro/*` stories
+2. `Pages` story
+3. `Pages/Home` and `Pages/Home/*` stories
+4. `Pages/Login` and `Pages/Login/*` stories
+5. `Pages/Admin` and `Pages/Admin/*` stories
+6. `Pages/*` stories
+7. `Components` and `Components/*` stories
+8. All other stories
+
+Note that the `order` option is independent of the `method` option; stories are sorted first by the `order` array and then by either the `method: 'alphabetical'` or the default `configure()` import order.
+
+### Theming
+
 For more information on configuring the `theme`, see [theming](../theming/).
 
 ### Per-story options