feat: Allow to configure folder for pages / markdown

.nx/version-plans/version-plan-1725723651035.md

@@ -0,0 +1,5 @@
+---
+__default__: patch
+---
+
+Removed hard coded '/pages/' path from route builder

packages/zudoku/src/config/config.ts

@@ -1,4 +1,3 @@
-import { MarkdownPluginOptions } from "../lib/plugins/markdown/index.js";
 import type { ZudokuConfig } from "./validators/validate.js";
 
 export type URLString = `https://${string}` | `http://${string}`;
@@ -13,11 +12,6 @@ export interface ZudokuPluginOptions extends ZudokuConfig {
   mode: "internal" | "module" | "standalone";
 }
 
-export interface DocsConfig {
-  files?: string;
-  defaultOptions?: MarkdownPluginOptions["defaultOptions"];
-}
-
 export type ClerkAuthenticationConfig = {
   type: "clerk";
   clerkPubKey: `pk_test_${string}` | `pk_live_${string}`;

packages/zudoku/src/config/validators/validate.ts

@@ -137,6 +137,17 @@ const SiteMapSchema = z
   })
   .optional();
 
+const DocsConfigSchema = z.object({
+  files: z.string(),
+  defaultOptions: z
+    .object({
+      toc: z.boolean(),
+      disablePager: z.boolean(),
+    })
+    .partial()
+    .optional(),
+});
+
 const ConfigSchema = z
   .object({
     basePath: z.string().optional(),
@@ -220,17 +231,7 @@ const ConfigSchema = z
       primaryBrandColor: z.string(),
       organizationDisplayName: z.string(),
     }),
-    docs: z
-      .object({
-        files: z.string(),
-        defaultOptions: z
-          .object({
-            toc: z.boolean(),
-            disablePager: z.boolean(),
-          })
-          .partial(),
-      })
-      .partial(),
+    docs: DocsConfigSchema,
     apis: z.union([ApiSchema, z.array(ApiSchema)]),
     apiKeys: ApiKeysSchema,
     redirects: z.array(z.object({ from: z.string(), to: z.string() })),
@@ -270,6 +271,7 @@ Following IDs are available: ${topNavIds.join(", ")}`,
 export type ZudokuApiConfig = z.infer<typeof ApiSchema>;
 export type ZudokuConfig = z.infer<typeof ConfigSchema>;
 export type ZudokuSiteMapConfig = z.infer<typeof SiteMapSchema>;
+export type ZudokuDocsConfig = z.infer<typeof DocsConfigSchema>;
 
 export function validateConfig(config: unknown) {
   const validationResult = ConfigSchema.safeParse(config);

packages/zudoku/src/lib/plugins/markdown/generateRoutes.tsx

@@ -7,17 +7,20 @@ import {
 
 export const generateRoutes = (
   markdownFiles: MarkdownPluginOptions["markdownFiles"],
+  filesPath: string,
   defaultOptions?: MarkdownPluginDefaultOptions,
 ): RouteObject[] =>
   Object.entries(markdownFiles).flatMap(([file, importPromise]) => {
-    // @todo we can pass in the folder name and then filter the markdown files based on that path
-    const match = file.match(/pages\/(.*).mdx?$/);
-    const path = match?.at(1);
+    let rootDir = filesPath.split("**")[0];
+    rootDir = rootDir.replace("/**", "/");
+    const re = new RegExp(`^${rootDir}(.*).mdx?`);
+    const match = file.match(re);
+    const fsPath = match?.at(1);
 
-    if (!path) return [];
+    if (!fsPath) return [];
 
     return {
-      path,
+      path: fsPath,
       lazy: async () => {
         const { MdxPage } = await import("./MdxPage.js");
         const { default: Component, ...props } = await importPromise();

packages/zudoku/src/lib/plugins/markdown/index.tsx

@@ -6,6 +6,7 @@ import { generateRoutes } from "./generateRoutes.js";
 export type MarkdownPluginOptions = {
   markdownFiles: Record<string, () => Promise<MDXImport>>;
   defaultOptions?: MarkdownPluginDefaultOptions;
+  filesPath: string;
 };
 export type MarkdownPluginDefaultOptions = Pick<
   Frontmatter,
@@ -29,6 +30,7 @@ export type MDXImport = {
 export const markdownPlugin = ({
   markdownFiles,
   defaultOptions,
+  filesPath,
 }: MarkdownPluginOptions): DevPortalPlugin => ({
-  getRoutes: () => generateRoutes(markdownFiles, defaultOptions),
+  getRoutes: () => generateRoutes(markdownFiles, filesPath, defaultOptions),
 });

packages/zudoku/src/lib/plugins/openapi/index.tsx

@@ -16,7 +16,6 @@ import { ErrorPage } from "../../components/ErrorPage.js";
 import { ColorMap } from "../../components/navigation/SidebarBadge.js";
 import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
 import { Button } from "../../ui/Button.js";
-import { joinPath } from "../../util/joinPath.js";
 import { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
@@ -73,7 +72,7 @@ export type OpenApiPluginOptions = OasPluginConfig & InternalOasPluginConfig;
 export const openApiPlugin = (
   config: OpenApiPluginOptions,
 ): DevPortalPlugin => {
-  const basePath = joinPath(config.navigationId ?? "/reference");
+  const basePath = "/reference";
 
   const client = config.server
     ? new UrqlClient({

packages/zudoku/src/vite/plugin-docs.ts

@@ -1,9 +1,8 @@
 import { type Plugin } from "vite";
-import type { DocsConfig, ZudokuPluginOptions } from "../config/config.js";
+import type { ZudokuPluginOptions } from "../config/config.js";
+import { ZudokuDocsConfig } from "../config/validators/validate.js";
 
-function getDefaultConfigIfFilesExist() {
-  return [{ files: "/pages/**/*.{md,mdx}" }];
-}
+const DEFAULT_DOCS_FILES = "/pages/**/*.{md,mdx}";
 
 const viteDocsPlugin = (getConfig: () => ZudokuPluginOptions): Plugin => {
   const virtualModuleId = "virtual:zudoku-docs-plugins";
@@ -32,11 +31,12 @@ const viteDocsPlugin = (getConfig: () => ZudokuPluginOptions): Plugin => {
             : `import { markdownPlugin } from "zudoku/plugins/markdown";`,
           `const configuredDocsPlugins = [];`,
         ];
-        const docsConfigs: DocsConfig[] = config.docs
+
+        const docsConfigs: ZudokuDocsConfig[] = config.docs
           ? Array.isArray(config.docs)
             ? config.docs
             : [config.docs]
-          : getDefaultConfigIfFilesExist();
+          : [{ files: DEFAULT_DOCS_FILES }];
 
         docsConfigs.forEach((docsConfig) => {
           code.push(
@@ -45,7 +45,11 @@ const viteDocsPlugin = (getConfig: () => ZudokuPluginOptions): Plugin => {
               `const markdownFiles = import.meta.glob(${JSON.stringify(docsConfig.files)}, {`,
               `  eager: false,`,
               `});`,
-              `configuredDocsPlugins.push(markdownPlugin({ markdownFiles, defaultOptions: ${JSON.stringify(docsConfig.defaultOptions)} }));`,
+              `configuredDocsPlugins.push(markdownPlugin({ `,
+              ` markdownFiles,`,
+              ` defaultOptions: ${JSON.stringify(docsConfig.defaultOptions)},`,
+              ` filesPath: ${JSON.stringify(docsConfig.files)}`,
+              `}));`,
             ],
           );
         });