From d8dfc4383a184d1c705d3eb2a46a996224d260b9 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 17 Oct 2024 15:11:24 -0400 Subject: [PATCH] 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. --- server/pages-helpers.ts | 13 ++--- uvu-tests/config-docs.test.ts | 79 +++++++++---------------------- uvu-tests/remark-includes.test.ts | 2 +- 3 files changed, 31 insertions(+), 63 deletions(-) diff --git a/server/pages-helpers.ts b/server/pages-helpers.ts index d982716981..5fc4c27e10 100644 --- 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 index e913f06f6e..1df6710424 100644 --- 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 index 2970b7d017..ef22381eeb 100644 --- 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 }}" ); });