Require Docusaurus-friendly section index pages

If a directory has no section index page within it that is named after the directory, e.g., `dir1/dir2/dir2.mdx`, throw an exception when building the docs. Currently, the docs engine also allows a section index page at the same level as its corresponding directory, since this is a convention the docs content has followed. However, this leads to undesired output when building the site with Docusaurus.
gravitational · Oct 22, 2024 · d8dfc43 · d8dfc43
1 parent 1ec9d04
commit d8dfc43
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 63 deletions.
diff --git a/server/pages-helpers.ts b/server/pages-helpers.ts
@@ -90,9 +90,8 @@ const sortByTitle = (a, b) => {
   }
 };
 
-// categoryPagePathForDir looks for a category page at the same directory level
-// as its associated directory OR within the associated directory. Throws an
-// error if there is no category page for the directory.
+// categoryPagePathForDir looks for a category page within the associated
+// directory. Throws an error if there is no category page for the directory.
 const categoryPagePathForDir = (fs, dirPath) => {
   const { name } = parse(dirPath);
 
@@ -103,17 +102,19 @@ const categoryPagePathForDir = (fs, dirPath) => {
 
   if (outerExists && innerExists) {
     throw new Error(
-      `cannot generate the docs navigation sidebar due to an ambiguous category page: must have a page named ${outerCategoryPage} or ${innerCategoryPage}, not not both`
+      `cannot generate the docs navigation sidebar due to an ambiguous category page: remove ${outerCategoryPage} and keep ${innerCategoryPage}`
     );
   }
   if (outerExists) {
-    return outerCategoryPage;
+    throw new Error(
+      `subdirectory in generated sidebar section ${dirPath} needs a page called ${innerCategoryPage}. Move ${outerCategoryPage}`
+    );
   }
   if (innerExists) {
     return innerCategoryPage;
   }
   throw new Error(
-    `subdirectory in generated sidebar section ${dirPath} has no category page ${innerCategoryPage} or ${outerCategoryPage}`
+    `subdirectory in generated sidebar section ${dirPath} has no category page ${innerCategoryPage}`
   );
 };
 

diff --git a/uvu-tests/config-docs.test.ts b/uvu-tests/config-docs.test.ts
@@ -295,6 +295,29 @@ title: MySQL Guide
   }
 );
 
+Suite(
+  "generateNavPaths throws if there is a category page at an incorrect location",
+  () => {
+    const files = {
+      "/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.mdx": `---
+title: "Database Access Guides"
+---`,
+    };
+
+    const vol = Volume.fromJSON(files);
+    const fs = createFsFromVolume(vol);
+    assert.throws(() => {
+      generateNavPaths(fs, "/docs/pages/database-access");
+    }, "database-access/guides/guides.mdx");
+  }
+);
+
 Suite("generateNavPaths shows third-level pages on the sidebar", () => {
   const files = {
     "/docs/pages/database-access/guides/guides.mdx": `---
@@ -347,61 +370,6 @@ title: Get Started with DB RBAC
   assert.equal(actual, expected);
 });
 
-Suite(
-  "allows category pages in the same directory as the associated subdirectory",
-  () => {
-    const files = {
-      "/docs/pages/database-access/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/rbac.mdx": `---
-title: Database Access RBAC
----`,
-      "/docs/pages/database-access/guides/rbac/get-started.mdx": `---
-title: Get Started with DB RBAC
----`,
-    };
-
-    const expected = [
-      {
-        title: "Database Access Guides",
-        slug: "/database-access/guides/",
-        entries: [
-          {
-            title: "Database Access RBAC",
-            slug: "/database-access/guides/rbac/",
-            entries: [
-              {
-                title: "Get Started with DB RBAC",
-                slug: "/database-access/guides/rbac/get-started/",
-              },
-            ],
-          },
-          {
-            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);
-    let actual = generateNavPaths(fs, "/docs/pages/database-access");
-    assert.equal(actual, expected);
-  }
-);
-
 Suite("generates four levels of the sidebar", () => {
   const files = {
     "/docs/pages/database-access/guides/guides.mdx": `---
@@ -458,7 +426,6 @@ title: Deploying the Database Service on Kubernetes
   assert.throws(
     () => {
       const actual = generateNavPaths(fs, "/docs/pages/database-access");
-      console.log(actual);
     },
     "database-access/deployment/deployment.mdx",
     "database-access/deployment.mdx"

diff --git a/uvu-tests/remark-includes.test.ts b/uvu-tests/remark-includes.test.ts
@@ -500,7 +500,7 @@ Suite("Throws an error if a variable is unresolved and has no default", () => {
   assert.equal(out.messages.length, 1);
   assert.equal(
     out.messages[0].reason,
-    "The following partial parameters were not assigned and have no default value: {{ unsupported }}"
+    "install-version.mdx: the following partial parameters were not assigned and have no default value: {{ unsupported }}"
   );
 });