6 files changed, 30 insertions, 10 deletions
diff --git a/scripts/apidoc/faker-class.ts b/scripts/apidoc/faker-class.ts
index 44648831..6672896c 100644
--- a/scripts/apidoc/faker-class.ts
+++ b/scripts/apidoc/faker-class.ts
@@ -55,7 +55,8 @@ async function processClass(
     comment,
     examples,
     deprecated,
-    methods
+    methods,
+    ''
   );
 }
 
diff --git a/scripts/apidoc/faker-utilities.ts b/scripts/apidoc/faker-utilities.ts
index 0da03581..ad1f74c3 100644
--- a/scripts/apidoc/faker-utilities.ts
+++ b/scripts/apidoc/faker-utilities.ts
@@ -34,6 +34,7 @@ async function processUtilities(
     comment,
     undefined,
     undefined,
-    methods
+    methods,
+    ''
   );
 }
diff --git a/scripts/apidoc/generate.ts b/scripts/apidoc/generate.ts
index 316757cc..44610869 100644
--- a/scripts/apidoc/generate.ts
+++ b/scripts/apidoc/generate.ts
@@ -24,13 +24,15 @@ export async function generate(): Promise<void> {
 
   const pages = [
     ...(await processFakerClasses(project)),
+    await processFakerRandomizer(project),
+    await processFakerUtilities(project),
     ...(await processModules(project)).sort((a, b) =>
       a.text.localeCompare(b.text)
     ),
-    await processFakerRandomizer(project),
-    await processFakerUtilities(project),
   ];
-  await writeApiPagesIndex(pages.map(({ text, link }) => ({ text, link })));
+  await writeApiPagesIndex(
+    pages.map(({ text, link, category }) => ({ text, link, category }))
+  );
   writeApiDiffIndex(
     Object.fromEntries(pages.map(({ text, diff }) => [text, diff]))
   );
diff --git a/scripts/apidoc/module-methods.ts b/scripts/apidoc/module-methods.ts
index 772a7236..c21ccf97 100644
--- a/scripts/apidoc/module-methods.ts
+++ b/scripts/apidoc/module-methods.ts
@@ -57,7 +57,8 @@ async function processModule(
     comment,
     examples,
     deprecated,
-    methods
+    methods,
+    'Modules'
   );
 }
 
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index b6b533f6..18176da5 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -4,7 +4,7 @@ import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 
 // Types
 
-export type Page = { text: string; link: string };
+export type Page = { text: string; link: string; category: string };
 
 export type ModuleSummary = Page & {
   methods: Method[];
diff --git a/scripts/apidoc/writer.ts b/scripts/apidoc/writer.ts
index 0fc7ae78..23586230 100644
--- a/scripts/apidoc/writer.ts
+++ b/scripts/apidoc/writer.ts
@@ -2,8 +2,10 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
 import { ReflectionKind } from 'typedoc';
+import type { DefaultTheme } from 'vitepress';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import type { APIGroup } from '../../docs/api/api-types';
+import { groupBy } from '../../src/internal/group-by';
 import { formatMarkdown, formatTypescript } from './format';
 import { extractSourceBaseUrl } from './typedoc';
 import type { DocsApiDiffIndex, ModuleSummary, Page } from './utils';
@@ -40,6 +42,7 @@ editLink: false
  * @param examples The example code.
  * @param deprecated The deprecation message.
  * @param methods The methods of the module.
+ * @param category The category of the module.
  */
 export async function writeApiDocsModule(
   moduleName: string,
@@ -47,7 +50,8 @@ export async function writeApiDocsModule(
   comment: string,
   examples: string | undefined,
   deprecated: string | undefined,
-  methods: Method[]
+  methods: Method[],
+  category: string
 ): Promise<ModuleSummary> {
   await writeApiDocsModulePage(
     moduleName,
@@ -63,6 +67,7 @@ export async function writeApiDocsModule(
     text: moduleName,
     link: `/api/${lowerModuleName}.html`,
     methods,
+    category,
     diff: {
       moduleHash: diffHash({
         name: moduleName,
@@ -164,13 +169,23 @@ function writeApiDocsModuleData(
  * @param pages The pages to write into the index.
  */
 export async function writeApiPagesIndex(pages: Page[]): Promise<void> {
+  const pagesByCategory = groupBy(pages, (page) => page.category);
+  const pageTree = Object.entries(pagesByCategory).flatMap(
+    ([category, items]): DefaultTheme.SidebarItem[] => {
+      const cleanedItems = items.map(({ text, link }) => ({ text, link }));
+      return category
+        ? [{ text: category, items: cleanedItems }]
+        : cleanedItems;
+    }
+  );
+
   // Write api-pages.ts
   console.log('Updating api-pages.ts');
-  pages.splice(0, 0, { text: 'Overview', link: '/api/' });
+  pageTree.splice(0, 0, { text: 'Overview', link: '/api/' });
   let apiPagesContent = `
     // This file is automatically generated.
     // Run '${scriptCommand}' to update
-    export const apiPages = ${JSON.stringify(pages)};
+    export const apiPages = ${JSON.stringify(pageTree)};
     `.replace(/\n +/, '\n');
 
   apiPagesContent = await formatTypescript(apiPagesContent);