Almost there

server/pages-helpers.ts

@@ -119,43 +119,62 @@ export const generateNavPaths = (fs, dirPath) => {
     }
     firstLvlFiles.add(fullPath);
   });
-  let sectionIntros = new Set();
+
+  // Map category pages to the directories they introduce so we can can add a
+  // sidebar entry for the category page, then traverse the directory.
+  let sectionIntros = new Map();
   firstLvlDirs.forEach((d: string) => {
-    sectionIntros.add(categoryPagePathForDir(fs, d));
+    sectionIntros.set(categoryPagePathForDir(fs, d), d);
   });
 
   // Add files with no corresponding directory to the navigation first. Section
   // introductions, by convention, have a filename that corresponds to the
   // subdirectory containing pages in the section, or have the name
   // "introduction.mdx".
   firstLvlFiles.forEach((f) => {
+    // Handle section intros separately
+    if (sectionIntros.has(f)) {
+      return;
+    }
     result.push(getEntryForPath(fs, f));
   });
 
-  sectionIntros.forEach((si: string) => {
-    const { slug, title } = getEntryForPath(fs, si);
+  sectionIntros.forEach((dirPath, categoryPagePath) => {
+    const { slug, title } = getEntryForPath(fs, categoryPagePath);
     const section = {
       title: title,
       slug: slug,
       entries: [],
     };
-    const sectionDir = dirname(si);
-    const secondLvl = fs.readdirSync(sectionDir, "utf8");
+    const secondLvl = new Set(fs.readdirSync(dirPath, "utf8"));
+
+    console.log("secondLvl:", secondLvl);
+    // Find all second-level category pages first so we don't
+    // repeat them in the sidebar.
     secondLvl.forEach((f2) => {
-      let fullPath2 = join(sectionDir, f2);
+      let fullPath2 = join(dirPath, f2);
       const stat = fs.statSync(fullPath2);
 
       // List category pages on the second level, but not their contents.
-      if (stat.isDirectory()) {
-        fullPath2 = categoryPagePathForDir(fs, fullPath2);
-        // This is a category page for the parent directory, which we have already
-        // listed, so skip it.
-      } else if (fullPath2 == categoryPagePathForDir(fs, dirname(fullPath2))) {
+      if (!stat.isDirectory()) {
         return;
       }
+      const catPath = categoryPagePathForDir(fs, fullPath2);
+      fullPath2 = catPath;
+      secondLvl.delete(f2);
+
+      // Delete the category page from the set so we don't add it again
+      // when we add individual files.
+      secondLvl.delete(parse(catPath).base);
+      section.entries.push(getEntryForPath(fs, fullPath2));
+    });
 
+    secondLvl.forEach((f2) => {
+      let fullPath2 = join(dirPath, f2);
+      const stat = fs.statSync(fullPath2);
       section.entries.push(getEntryForPath(fs, fullPath2));
     });
+
     section.entries.sort(sortByTitle);
     result.push(section);
   });

uvu-tests/config-docs.test.ts

@@ -382,7 +382,7 @@ title: Get Started with DB RBAC
 
     const vol = Volume.fromJSON(files);
     const fs = createFsFromVolume(vol);
-    let actual = generateNavPaths(fs, "/docs/pages/database-access/guides");
+    let actual = generateNavPaths(fs, "/docs/pages/database-access");
     assert.equal(actual, expected);
   }
 );