@mehdad67/apitogo 0.1.24

package/src/vite/plugin-config.ts

@@ -0,0 +1,75 @@
+import { normalizePath, type Plugin, type ResolvedConfig } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+
+const virtualModuleId = "virtual:zudoku-config";
+const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+const viteConfigPlugin = (): Plugin => {
+  let viteConfig: ResolvedConfig;
+
+  return {
+    name: "zudoku-config-plugin",
+    resolveId(id) {
+      if (id !== virtualModuleId) return;
+
+      return resolvedVirtualModuleId;
+    },
+    configResolved(resolvedConfig) {
+      viteConfig = resolvedConfig;
+    },
+    load(id) {
+      if (id !== resolvedVirtualModuleId) return;
+
+      const configPath = getCurrentConfig().__meta.configPath;
+      if (!configPath) {
+        return `export default {};`;
+      }
+
+      return `
+import rawConfig from "${normalizePath(configPath)}";
+import { runPluginTransformConfig } from "@lukoweb/apitogo/plugins";
+
+const config = await runPluginTransformConfig(rawConfig);
+export default config;
+`;
+    },
+    async transform(code, id) {
+      if (id !== getCurrentConfig().__meta.configPath) return;
+
+      const replacedCode = code.replaceAll(
+        /process\.env\.([a-z_][a-z0-9_]*)/gi,
+        (_, envVar) => {
+          const allowedPrefixes = Array.isArray(viteConfig.envPrefix)
+            ? viteConfig.envPrefix
+            : [viteConfig.envPrefix];
+
+          if (!allowedPrefixes.some((prefix) => envVar.startsWith(prefix))) {
+            viteConfig.logger.warn(
+              `Warning: process.env.${envVar} is not prefixed with ${allowedPrefixes.join(
+                " or ",
+              )}.`,
+            );
+            return "undefined";
+          }
+
+          const value =
+            viteConfig.define?.[`process.env.${envVar}`] ??
+            viteConfig.define?.[`import.meta.env.${envVar}`];
+
+          if (value === undefined) {
+            viteConfig.logger.warn(
+              `Warning: process.env.${envVar} is not defined.`,
+            );
+            return "undefined";
+          }
+
+          return value;
+        },
+      );
+
+      return { code: replacedCode, map: null };
+    },
+  };
+};
+
+export default viteConfigPlugin;

package/src/vite/plugin-custom-pages.ts

@@ -0,0 +1,36 @@
+import type { Plugin } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+
+const viteCustomPagesPlugin = (): Plugin => {
+  const virtualModuleId = "virtual:zudoku-custom-pages-plugin";
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+  return {
+    name: "zudoku-custom-pages-plugin",
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id === resolvedVirtualModuleId) {
+        const config = getCurrentConfig();
+
+        if (config.__meta.mode === "standalone" || !config.navigation) {
+          return `export const configuredCustomPagesPlugin = undefined;`;
+        }
+
+        const code = [
+          `import config from "virtual:zudoku-config";`,
+          config.__meta.mode === "internal"
+            ? `import { customPagesPlugin } from "${config.__meta.moduleDir}/src/lib/plugins/custom-pages/index.tsx";`
+            : `import { customPagesPlugin } from "@lukoweb/apitogo/plugins/custom-pages";`,
+          `export const configuredCustomPagesPlugin = customPagesPlugin(config.navigation);`,
+        ];
+
+        return code.join("\n");
+      }
+    },
+  };
+};
+
+export default viteCustomPagesPlugin;

package/src/vite/plugin-doc-metadata.ts

@@ -0,0 +1,45 @@
+import { glob } from "glob";
+import type { Plugin } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+import { readFrontmatter } from "../lib/util/readFrontmatter.js";
+import { reload } from "./plugin-config-reload.js";
+import { invalidate as invalidateNavigation } from "./plugin-navigation.js";
+
+const serializeMetadata = async (filePath: string): Promise<string> => {
+  const fm = await readFrontmatter(filePath);
+  const h1 = fm.content.match(/^#\s+(.*)$/m)?.[1];
+  return JSON.stringify({ frontmatter: fm.data, h1 });
+};
+
+export const viteDocMetadataPlugin = (): Plugin => ({
+  enforce: "pre",
+  name: "zudoku-doc-metadata-plugin",
+  configureServer: async (server) => {
+    const config = getCurrentConfig();
+    const files = await glob("**/*.{md,mdx}", {
+      cwd: config.__meta.rootDir,
+      ignore: ["node_modules", "dist"],
+      absolute: true,
+    });
+
+    const metadataMap = new Map<string, string>(
+      await Promise.all(
+        files.map(
+          async (file) => [file, await serializeMetadata(file)] as const,
+        ),
+      ),
+    );
+
+    server.watcher.on("all", async (event, filePath) => {
+      if (event !== "change" && event !== "add") return;
+      if (!/\.mdx?$/.test(filePath)) return;
+
+      const metadata = await serializeMetadata(filePath);
+      if (metadataMap.get(filePath) === metadata) return;
+
+      metadataMap.set(filePath, metadata);
+      invalidateNavigation(server);
+      reload(server);
+    });
+  },
+});

package/src/vite/plugin-docs.ts

@@ -0,0 +1,205 @@
+import path from "node:path";
+import { glob } from "glob";
+import globParent from "glob-parent";
+import type { Plugin } from "vite";
+import { type ConfigWithMeta, getCurrentConfig } from "../config/loader.js";
+import {
+  type NavigationItem,
+  NavigationResolver,
+} from "../config/validators/NavigationSchema.js";
+import { DocsConfigSchema } from "../config/validators/ZudokuConfig.js";
+import { traverseNavigation } from "../lib/components/navigation/utils.js";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import { readFrontmatter } from "../lib/util/readFrontmatter.js";
+import { writePluginDebugCode } from "./debug.js";
+
+const ensureLeadingSlash = joinUrl;
+
+// Glob markdown files and returns a mapping of route paths to file paths.
+export const globMarkdownFiles = async (
+  config: ConfigWithMeta,
+  options: { absolute: boolean } = { absolute: false },
+): Promise<Record<string, string>> => {
+  const docsConfig = DocsConfigSchema.parse(config.docs ?? {});
+  const fileMapping: Record<string, string> = {};
+
+  for (const globPattern of docsConfig.files) {
+    const globbedFiles = await glob(globPattern, {
+      root: config.__meta.rootDir,
+      ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**"],
+      // Always glob with relative paths to avoid issues on different OS
+      absolute: false,
+      posix: true,
+    });
+
+    // Normalize parent by removing leading `./` or `/`
+    const parent = globParent(globPattern).replace(/^\.?\//, "");
+
+    // Precompute draft status for all files in production mode to avoid serial I/O
+    let draftFiles = new Set<string>();
+    if (process.env.NODE_ENV !== "development") {
+      const draftStatuses = await Promise.all(
+        globbedFiles.map(async (file) => {
+          const absolutePath = path.resolve(config.__meta.rootDir, file);
+          const { data } = await readFrontmatter(absolutePath);
+          return { file, isDraft: data.draft === true };
+        }),
+      );
+      draftFiles = new Set(
+        draftStatuses
+          .filter((entry) => entry.isDraft)
+          .map((entry) => entry.file),
+      );
+    }
+
+    for (const file of globbedFiles) {
+      // Skip draft documents in production mode
+      if (draftFiles.has(file)) {
+        continue;
+      }
+
+      const relativePath = path.posix.relative(parent, file);
+      const routePath = ensureLeadingSlash(relativePath.replace(/\.mdx?$/, ""));
+      // Resolve to absolute path if requested, using path.resolve to handle cross-platform paths
+      const filePath = options.absolute
+        ? path.resolve(config.__meta.rootDir, file)
+        : file;
+      fileMapping[routePath] = filePath;
+    }
+  }
+
+  return fileMapping;
+};
+
+/**
+ * Resolves custom navigation paths and returns an updated file mapping.
+ * Handles cases where navigation defines custom paths for documents.
+ */
+export const resolveCustomNavigationPaths = async (
+  config: ConfigWithMeta,
+  fileMapping: Record<string, string>,
+): Promise<Record<string, string>> => {
+  if (!config.navigation && !config.navigationRules) return fileMapping;
+
+  const resolver = new NavigationResolver(config);
+  const mapping = { ...fileMapping };
+
+  const processItem = (item: NavigationItem) => {
+    const doc =
+      item.type === "doc"
+        ? { file: item.file, path: item.path }
+        : item.type === "category" && item.link
+          ? { file: item.link.file, path: item.link.path }
+          : undefined;
+
+    // Only continue if the doc has a custom path
+    if (!doc || doc.path === doc.file) return;
+
+    const fileRoutePath = ensureLeadingSlash(doc.file.replace(/\.mdx?$/, ""));
+    const filePath = mapping[fileRoutePath];
+    if (!filePath) return;
+
+    const customPath = ensureLeadingSlash(doc.path);
+    mapping[customPath] = filePath;
+    delete mapping[fileRoutePath];
+  };
+
+  if (config.navigation) {
+    const resolvedNavigation = await resolver.resolve();
+    traverseNavigation(resolvedNavigation, processItem);
+  }
+
+  if (config.navigationRules) {
+    const resolvedRules = await resolver.resolveRules(config.navigationRules);
+    for (const rule of resolvedRules) {
+      if (rule.type === "insert") {
+        traverseNavigation(rule.items, processItem);
+      }
+    }
+  }
+
+  return mapping;
+};
+
+const viteDocsPlugin = (): Plugin => {
+  const virtualModuleId = "virtual:zudoku-docs-plugin";
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+  return {
+    name: "zudoku-docs-plugin",
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id !== resolvedVirtualModuleId) return;
+
+      const config = getCurrentConfig();
+
+      if (
+        config.__meta.mode === "standalone" ||
+        !config.__resolvedModules.docs.enabled
+      ) {
+        return `export const configuredDocsPlugin = undefined;`;
+      }
+
+      const code: string[] = [
+        // IMPORTANT! This path here is important, we MUST resolve
+        // files here as Typescript from the appDir
+        config.__meta.mode === "internal"
+          ? `import { markdownPlugin } from "${config.__meta.moduleDir}/src/lib/plugins/markdown/index.tsx";`
+          : `import { markdownPlugin } from "@lukoweb/apitogo/plugins/markdown";`,
+      ];
+
+      const docsConfig = DocsConfigSchema.parse(config.docs ?? {});
+
+      // This is a workaround for a bug(?) in Vite where `import.meta.glob` failed us:
+      // - Root dir is `/path/to/docs`
+      // - The Markdown docs config is `/docs/**/*.md`
+      // - The basePath config is set to `/docs`
+      // This results in:
+      // > `Internal server error: Failed to resolve import "/some.md" from "virtual:zudoku-docs-plugins". Does the file exist?`
+      // Mind that the `docs` part that should be prepended is not in there
+      //
+      // This does only happen in dev SSR environments, so for prod the `basePath` is not added
+      const globImportBasePath =
+        process.env.NODE_ENV === "development" ? (config.basePath ?? "") : "";
+
+      // Glob markdown files and resolve custom navigation paths
+      const fileMapping = await resolveCustomNavigationPaths(
+        config,
+        await globMarkdownFiles(config, { absolute: false }),
+      );
+
+      // Transform file paths to import paths
+      const globbedDocuments: Record<string, string> = {};
+      for (const [routePath, file] of Object.entries(fileMapping)) {
+        const importPath = ensureLeadingSlash(
+          path.posix.join(globImportBasePath, file),
+        );
+        globbedDocuments[routePath] = importPath;
+      }
+
+      code.push(
+        `const fileImports = {`,
+        ...Object.entries(globbedDocuments).map(
+          ([routePath, importPath]) =>
+            `  "${routePath}": () => import("${importPath}"),`,
+        ),
+        `};`,
+        `export const configuredDocsPlugin = markdownPlugin({`,
+        `  basePath: "${config.basePath ?? ""}",`,
+        `  fileImports,`,
+        `  defaultOptions: ${JSON.stringify(docsConfig.defaultOptions)},`,
+        `});`,
+      );
+
+      await writePluginDebugCode(config.__meta.rootDir, "docs-plugin", code);
+
+      return code.join("\n");
+    },
+  };
+};
+
+export default viteDocsPlugin;

package/src/vite/plugin-markdown-export.ts

@@ -0,0 +1,214 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { matchPath } from "react-router";
+import type { Plugin } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+import { ProtectedRoutesSchema } from "../config/validators/ProtectedRoutesSchema.js";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import { readFrontmatter } from "../lib/util/readFrontmatter.js";
+import {
+  globMarkdownFiles,
+  resolveCustomNavigationPaths,
+} from "./plugin-docs.js";
+
+export type MarkdownFileInfo = {
+  filePath: string;
+  routePath: string;
+  title?: string;
+  description?: string;
+  content: string;
+};
+
+const processMarkdownFile = async (
+  filePath: string,
+): Promise<{ content: string; title?: string; description?: string }> => {
+  const { content: markdownContent, data: frontmatter } =
+    await readFrontmatter(filePath);
+
+  let finalMarkdown = markdownContent;
+  if (frontmatter.title) {
+    // Add title as H1 at the beginning, matching the behavior in MdxPage.tsx
+    finalMarkdown = `# ${frontmatter.title}\n${markdownContent}`;
+  }
+
+  return {
+    content: finalMarkdown,
+    title: frontmatter.title,
+    description: frontmatter.description,
+  };
+};
+
+/**
+ * This plugin exports markdown files (.md) for each document during the build process.
+ * In development mode, you can access documents at their URL path with .md extension
+ * (e.g., /foo/hello.md) to get the raw markdown without frontmatter.
+ *
+ * Markdown files are generated when:
+ * - publishMarkdown is enabled (for copy button functionality)
+ * - llmsTxt or llmsTxtFull is enabled (for generating llms.txt files)
+ *
+ * It also writes metadata to markdown-info.json used by the llms.txt generator.
+ */
+const viteMarkdownExportPlugin = (): Plugin => {
+  let markdownFiles: Record<string, string> = {};
+  let markdownFileInfos: MarkdownFileInfo[] = [];
+
+  return {
+    name: "zudoku-markdown-export-plugin",
+    applyToEnvironment(env) {
+      return env.name === "ssr";
+    },
+    async buildStart() {
+      const config = getCurrentConfig();
+      const llmsConfig = config.docs?.llms;
+
+      const needsMdFiles =
+        config.docs?.publishMarkdown ||
+        llmsConfig?.llmsTxt ||
+        llmsConfig?.llmsTxtFull;
+
+      if (config.__meta.mode === "standalone" || !needsMdFiles) {
+        return;
+      }
+
+      markdownFiles = await resolveCustomNavigationPaths(
+        config,
+        await globMarkdownFiles(config, { absolute: true }),
+      );
+
+      // Filter out protected routes unless `includeProtected` is true
+      if (!llmsConfig?.includeProtected) {
+        const protectedRoutes = ProtectedRoutesSchema.parse(
+          config.protectedRoutes,
+        );
+        if (protectedRoutes) {
+          const isProtectedRoute = (routePath: string): boolean => {
+            return Object.keys(protectedRoutes).some((route) =>
+              matchPath({ path: route, end: true }, routePath),
+            );
+          };
+
+          // Remove protected routes from the mapping
+          for (const routePath of Object.keys(markdownFiles)) {
+            if (isProtectedRoute(routePath)) {
+              delete markdownFiles[routePath];
+            }
+          }
+        }
+      }
+    },
+    async configureServer(server) {
+      const config = getCurrentConfig();
+      const llmsConfig = config.docs?.llms;
+
+      // Serve .md files if markdown export is needed
+      const needsMdFiles =
+        config.docs?.publishMarkdown ||
+        llmsConfig?.llmsTxt ||
+        llmsConfig?.llmsTxtFull;
+
+      if (!needsMdFiles) return;
+
+      markdownFiles = await resolveCustomNavigationPaths(
+        config,
+        await globMarkdownFiles(config, { absolute: true }),
+      );
+
+      server.middlewares.use(async (req, res, next) => {
+        if (req.method !== "GET" || !req.url?.endsWith(".md")) {
+          return next();
+        }
+
+        const basePath = joinUrl(config.basePath);
+        const routePath = joinUrl(
+          req.url.slice(basePath.length).replace(/\.mdx?$/, ""),
+        );
+        const filePath = markdownFiles[routePath];
+
+        if (!filePath) return next();
+
+        try {
+          const { content } = await processMarkdownFile(filePath);
+          res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+          res.end(content);
+        } catch (error) {
+          // biome-ignore lint/suspicious/noConsole: Logging allowed here
+          console.warn(`Failed to serve markdown for ${routePath}:`, error);
+          return next();
+        }
+      });
+    },
+    async closeBundle() {
+      const config = getCurrentConfig();
+      const llmsConfig = config.docs?.llms;
+
+      const needsMdFiles =
+        config.docs?.publishMarkdown ||
+        llmsConfig?.llmsTxt ||
+        llmsConfig?.llmsTxtFull;
+
+      if (
+        process.env.NODE_ENV !== "production" ||
+        Object.keys(markdownFiles).length === 0 ||
+        !needsMdFiles
+      ) {
+        return;
+      }
+
+      // During build, write .md files to the dist directory
+      const distDir = path.join(
+        config.__meta.rootDir,
+        "dist",
+        config.basePath ?? "",
+      );
+
+      markdownFileInfos = [];
+
+      for (const [routePath, filePath] of Object.entries(markdownFiles)) {
+        try {
+          const {
+            content: finalMarkdown,
+            title,
+            description,
+          } = await processMarkdownFile(filePath);
+
+          markdownFileInfos.push({
+            filePath,
+            routePath,
+            title,
+            description,
+            content: finalMarkdown,
+          });
+
+          const segments =
+            routePath === "/"
+              ? ["index"]
+              : routePath.split("/").filter(Boolean);
+
+          const outputPath = `${path.join(distDir, ...segments)}.md`;
+
+          await mkdir(path.dirname(outputPath), { recursive: true });
+
+          await writeFile(outputPath, finalMarkdown, "utf-8");
+        } catch (error) {
+          // biome-ignore lint/suspicious/noConsole: Logging allowed here
+          console.warn(`Failed to export markdown for ${routePath}:`, error);
+        }
+      }
+
+      if (config.docs?.llms?.llmsTxt || config.docs?.llms?.llmsTxtFull) {
+        const markdownInfoPath = path.join(
+          config.__meta.rootDir,
+          "node_modules/.apitogo/markdown-info.json",
+        );
+        await writeFile(
+          markdownInfoPath,
+          JSON.stringify(markdownFileInfos, null, 2),
+          "utf-8",
+        );
+      }
+    },
+  };
+};
+
+export default viteMarkdownExportPlugin;