@lukoweb/apitogo 0.2.59 → 0.2.61

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

@@ -1,214 +1,210 @@
-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;
+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 { markdownOutputPath } from "./markdown-output-path.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 outputPath = markdownOutputPath(distDir, routePath);
+
+          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;

package/src/vite/prerender/prerender.ts

@@ -1,4 +1,4 @@
-import { readFile, rm } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -13,6 +13,7 @@ import type { ZudokuConfig } from "../../config/validators/ZudokuConfig.js";
 import { runPluginTransformConfig } from "../../lib/core/transform-config.js";
 import invariant from "../../lib/util/invariant.js";
 import { joinUrl } from "../../lib/util/joinUrl.js";
+import { removeExportedMarkdown } from "../markdown-output-path.js";
 import type { MarkdownFileInfo } from "../plugin-markdown-export.js";
 import { isTTY, throttle, writeLine } from "../reporter.js";
 import { generateSitemap } from "../sitemap.js";
@@ -231,10 +232,9 @@ export const prerender = async ({
       });
     }
 
+    // The .md copies were only written for llms.txt: remove them from dist again.
     if (!docsConfig.publishMarkdown) {
-      await Promise.all(
-        markdownFileInfos.map((info) => rm(info.filePath).catch(() => {})),
-      );
+      await removeExportedMarkdown(distDir, markdownFileInfos);
     }
   }
 

package/src/vite/watch-ignore.ts

@@ -69,6 +69,25 @@ export function stateIgnore(
   };
 }
 
+/** A state folder (`.apitogo/` or `apitogo/.state/`) anywhere in a path relative to the site root. */
+const STATE_FOLDER = /(?:^|[\\/])(?:\.apitogo|apitogo[\\/]\.state)(?:[\\/]|$)/;
+
+/**
+ * What the dev server's watcher must leave alone below the site root of any project: the state folder of a config
+ * version 2 project kept inside it (a test project in a subfolder, say). Its `generated/content` links back to that
+ * project's folder, so a watcher that follows the link walks `content/apitogo/.state/generated/content/...` forever
+ * and keeps a CPU core busy, and every page waits seconds for the server. Paths outside the site root are left to
+ * {@link stateIgnore}.
+ */
+export function nestedStateIgnore(root: string): (file: string) => boolean {
+  const resolvedRoot = path.resolve(root);
+  return (file) => {
+    const relative = path.relative(resolvedRoot, path.resolve(file));
+    if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
+    return STATE_FOLDER.test(relative);
+  };
+}
+
 /**
  * The folders the dev server may serve files from. The site root of a config version 2 workspace sits inside the
  * state folder, so the package (`node_modules`) and the tenant's pages are outside it. Without them the page's main