new: Add sortSidebar setting.

milesj · Nov 8, 2022 · 60a5a69 · 60a5a69
1 parent 31d6a93
commit 60a5a69
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 3 deletions.
diff --git a/packages/plugin/README.md b/packages/plugin/README.md
@@ -99,6 +99,8 @@ The following options are available to the plugin:
   name in the sidebar and index. For example, `boost` will remove `@boost/` and `boost-`.
 - `sortPackages` (`(a, d) => number`) - Function to sort the package list in the sidebar and on the
   index page. Defaults to alphabetical.
+- `sortSidebar` (`(a, d) => number`) - Function to sort the categories and items within each
+  sidebar, excluding "Overview" and "Changelog". Defaults to alphabetical.
 - `tsconfigName` (`string`) - Name of the TypeScript config file in the project root. Defaults to
   `tsconfig.json`.
 - `typedocOptions` (`object`) - [TypeDoc options](https://typedoc.org/guides/options/#input-options)

diff --git a/packages/plugin/src/index.ts b/packages/plugin/src/index.ts
@@ -43,6 +43,7 @@ const DEFAULT_OPTIONS: Required<DocusaurusPluginTypeDocApiOptions> = {
 	packages: [],
 	projectRoot: '.',
 	sortPackages: (a, d) => a.packageName.localeCompare(d.packageName),
+	sortSidebar: (a, d) => a.localeCompare(d),
 	readmeName: 'README.md',
 	readmes: false,
 	removeScopes: [],
@@ -214,7 +215,12 @@ export default function typedocApiPlugin(
 						return {
 							...metadata,
 							packages,
-							sidebars: await extractSidebar(packages, removeScopes, changelogs),
+							sidebars: await extractSidebar(
+								packages,
+								removeScopes,
+								changelogs,
+								options.sortSidebar,
+							),
 						};
 					}),
 				),

diff --git a/packages/plugin/src/plugin/sidebar.ts b/packages/plugin/src/plugin/sidebar.ts
@@ -1,6 +1,11 @@
 import { JSONOutput } from 'typedoc';
 import { normalizeUrl } from '@docusaurus/utils';
-import { DeclarationReflectionMap, PackageReflectionGroup, SidebarItem } from '../types';
+import {
+	DeclarationReflectionMap,
+	DocusaurusPluginTypeDocApiOptions,
+	PackageReflectionGroup,
+	SidebarItem,
+} from '../types';
 import { removeScopes } from '../utils/links';
 import { createReflectionMap } from './data';
 
@@ -68,13 +73,14 @@ export function extractSidebar(
 	packages: PackageReflectionGroup[],
 	scopes: string[],
 	changelogs: boolean,
+	sortSidebar: NonNullable<DocusaurusPluginTypeDocApiOptions['sortSidebar']>,
 ): SidebarItem[] {
 	if (packages.length === 0) {
 		return [];
 	}
 
 	const items: SidebarItem[] = packages.map((pkg) => {
-		const subItems: SidebarItem[] = [];
+		let subItems: SidebarItem[] = [];
 
 		pkg.entryPoints.forEach((entry) => {
 			// Index entry point should always bubble up reflection groups
@@ -95,6 +101,10 @@ export function extractSidebar(
 		// Always include the overview as the 1st item
 		const indexHref = pkg.entryPoints.find((entry) => entry.index)?.reflection.permalink ?? '';
 
+		subItems = subItems.sort((a, d) =>
+			sortSidebar('label' in a ? a.label : '', 'label' in d ? d.label : ''),
+		);
+
 		subItems.unshift({
 			href: indexHref,
 			label: 'Overview',

diff --git a/packages/plugin/src/types.ts b/packages/plugin/src/types.ts
@@ -25,6 +25,7 @@ export interface DocusaurusPluginTypeDocApiOptions
 	readmes?: boolean;
 	removeScopes?: string[];
 	sortPackages?: (a: PackageReflectionGroup, d: PackageReflectionGroup) => number;
+	sortSidebar?: (a: string, d: string) => number;
 	tsconfigName?: string;
 	typedocOptions?: Partial<
 		Pick<