Alphabetize auto-generated sidebar entries

The exception is any page that includes "Introduction" or "introduction"
in the title. Elevate these to the first entry to avoid a confusing
sidebar order.

server/pages-helpers.ts

@@ -72,6 +72,19 @@ const getEntryForPath = (fs, filePath) => {
   };
 };
 
+const sortByTitle = (a, b) => {
+  switch (true) {
+    case a.title.toLowerCase().includes("introduction"):
+      return -1;
+      break;
+    case b.title.toLowerCase().includes("introduction"):
+      return 1;
+      break;
+    default:
+      return a.title < b.title ? -1 : 1;
+  }
+};
+
 export const generateNavPaths = (fs, dirPath) => {
   const firstLvl = fs.readdirSync(dirPath, "utf8");
   let result = [];
@@ -132,7 +145,9 @@ export const generateNavPaths = (fs, dirPath) => {
 
       section.entries.push(getEntryForPath(fs, fullPath2));
     });
+    section.entries.sort(sortByTitle);
     result.push(section);
   });
+  result.sort(sortByTitle);
   return result;
 };

uvu-tests/config-docs.test.ts

@@ -139,10 +139,6 @@ title: Database RBAC Reference
   };
 
   const expected = [
-    {
-      title: "Protect Databases with Teleport",
-      slug: "/database-access/introduction/",
-    },
     {
       title: "Database Access Guides",
       slug: "/database-access/guides/guides/",
@@ -161,16 +157,20 @@ title: Database RBAC Reference
       title: "Database Access RBAC",
       slug: "/database-access/rbac/rbac/",
       entries: [
-        {
-          title: "Get Started with DB RBAC",
-          slug: "/database-access/rbac/get-started/",
-        },
         {
           title: "Database RBAC Reference",
           slug: "/database-access/rbac/reference/",
         },
+        {
+          title: "Get Started with DB RBAC",
+          slug: "/database-access/rbac/get-started/",
+        },
       ],
     },
+    {
+      title: "Protect Databases with Teleport",
+      slug: "/database-access/introduction/",
+    },
   ];
 
   const vol = Volume.fromJSON(files);
@@ -179,6 +179,96 @@ title: Database RBAC Reference
   assert.equal(actual, expected);
 });
 
+Suite(
+  "generateNavPaths alphabetizes second-level links except 'Introduction'",
+  () => {
+    const files = {
+      "/docs/pages/database-access/mongodb.mdx": `---
+title: MongoDB 
+---`,
+      "/docs/pages/database-access/azure-dbs.mdx": `---
+title: Azure
+---`,
+      "/docs/pages/database-access/introduction.mdx": `---
+title: Introduction to Database Access
+---`,
+    };
+
+    const expected = [
+      {
+        title: "Introduction to Database Access",
+        slug: "/database-access/introduction/",
+      },
+      {
+        title: "Azure",
+        slug: "/database-access/azure-dbs/",
+      },
+      {
+        title: "MongoDB",
+        slug: "/database-access/mongodb/",
+      },
+    ];
+
+    const vol = Volume.fromJSON(files);
+    const fs = createFsFromVolume(vol);
+    const actual = generateNavPaths(fs, "/docs/pages/database-access");
+    assert.equal(actual, expected);
+  }
+);
+
+Suite(
+  "generateNavPaths alphabetizes third-level links except 'Introduction'",
+  () => {
+    const files = {
+      "/docs/pages/database-access/guides/guides.mdx": `---
+title: Database Access Guides
+---`,
+      "/docs/pages/database-access/guides/postgres.mdx": `---
+title: Postgres Guide
+---`,
+      "/docs/pages/database-access/guides/mysql.mdx": `---
+title: MySQL Guide
+---`,
+      "/docs/pages/database-access/guides/get-started.mdx": `---
+title: Introduction to Database RBAC
+---`,
+      "/docs/pages/database-access/guides/reference.mdx": `---
+title: Database RBAC Reference
+---`,
+    };
+
+    const expected = [
+      {
+        title: "Database Access Guides",
+        slug: "/database-access/guides/guides/",
+        entries: [
+          {
+            title: "Introduction to Database RBAC",
+            slug: "/database-access/guides/get-started/",
+          },
+          {
+            title: "Database RBAC Reference",
+            slug: "/database-access/guides/reference/",
+          },
+          {
+            title: "MySQL Guide",
+            slug: "/database-access/guides/mysql/",
+          },
+          {
+            title: "Postgres Guide",
+            slug: "/database-access/guides/postgres/",
+          },
+        ],
+      },
+    ];
+
+    const vol = Volume.fromJSON(files);
+    const fs = createFsFromVolume(vol);
+    const actual = generateNavPaths(fs, "/docs/pages/database-access");
+    assert.equal(actual, expected);
+  }
+);
+
 Suite(
   "generateNavPaths throws if there is no category page in a subdirectory",
   () => {