Use introduction.mdx pages as section intros

server/config-docs.ts

@@ -334,7 +334,10 @@ export const loadConfig = (version: string) => {
     }
 
     if (!!item.generateFrom) {
-      config.navigation[i].entries = generateNavPaths(fs, item.generateFrom);
+      config.navigation[i].entries = generateNavPaths(
+        fs,
+        join("content", version, "docs", "pages", item.generateFrom)
+      );
     }
   });
 

server/pages-helpers.ts

@@ -65,7 +65,7 @@ export const getPageInfo = <T = MDXPageFrontmatter>(
 const getEntryForPath = (fs, filePath) => {
   const txt = fs.readFileSync(filePath, "utf8");
   const { data } = matter(txt);
-  const slug = filePath.replace(/\/?docs\/pages/, "").replace(".mdx", "/");
+  const slug = filePath.split("docs/pages")[1].replace(".mdx", "/");
   return {
     title: data.title,
     slug: slug,
@@ -89,15 +89,22 @@ export const generateNavPaths = (fs, dirPath) => {
   let sectionIntros = new Set();
   firstLvlDirs.forEach((d) => {
     const asFile = d + ".mdx";
+    const introPath = join(d, "introduction.mdx");
+    if (fs.existsSync(introPath)) {
+      sectionIntros.add(introPath);
+    }
+
     if (firstLvlFiles.has(asFile)) {
       sectionIntros.add(asFile);
       firstLvlFiles.delete(asFile);
+      return;
     }
   });
 
   // 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.
+  // subdirectory containing pages in the section, or have the name
+  // "introduction.mdx".
   firstLvlFiles.forEach((f) => {
     result.push(getEntryForPath(fs, f));
   });
@@ -109,9 +116,18 @@ export const generateNavPaths = (fs, dirPath) => {
       title: title,
       entries: [],
     };
-    const sectionDir = si.slice(0, si.length - ".mdx".length);
+    let sectionDir;
+    if (si.endsWith("introduction.mdx")) {
+      sectionDir = dirname(si);
+    } else {
+      sectionDir = si.slice(0, si.length - ".mdx".length);
+    }
     const secondLvl = fs.readdirSync(sectionDir, "utf8");
     secondLvl.forEach((f2) => {
+      // We have already used this as an introduction page.
+      if (f2.endsWith("introduction.mdx")) {
+        return;
+      }
       const fullPath2 = join(sectionDir, f2);
       const stat = fs.statSync(fullPath2);
       if (stat.isDirectory()) {

uvu-tests/config-docs.test.ts

@@ -1,11 +1,8 @@
 import { Redirect } from "next/dist/lib/load-custom-routes";
 import { suite } from "uvu";
 import * as assert from "uvu/assert";
-import {
-  generateNavPaths,
-  Config,
-  checkURLsForCorrespondingFiles,
-} from "../server/config-docs";
+import { Config, checkURLsForCorrespondingFiles } from "../server/config-docs";
+import { generateNavPaths } from "../server/pages-helpers";
 import { randomUUID } from "crypto";
 import { join } from "path";
 import { Volume, createFsFromVolume } from "memfs";
@@ -116,7 +113,7 @@ Suite("Ensures that URLs correspond to docs pages", () => {
   assert.equal(actual, expected);
 });
 
-Suite.only("generateNavPaths", () => {
+Suite("generateNavPaths", () => {
   const files = {
     "/docs/pages/database-access/introduction.mdx": `---
 title: Protect Databases with Teleport
@@ -130,7 +127,7 @@ title: Postgres Guide
     "/docs/pages/database-access/guides/mysql.mdx": `---
 title: MySQL Guide
 ---`,
-    "/docs/pages/database-access/rbac.mdx": `---
+    "/docs/pages/database-access/rbac/introduction.mdx": `---
 title: Database Access RBAC
 ---`,
     "/docs/pages/database-access/rbac/get-started.mdx": `---
@@ -162,7 +159,7 @@ title: Database RBAC Reference
     },
     {
       title: "Database Access RBAC",
-      slug: "/database-access/rbac/",
+      slug: "/database-access/rbac/introduction/",
       entries: [
         {
           title: "Get Started with DB RBAC",