@lukoweb/apitogo 0.2.56 → 0.2.57

package/src/vite/plugin-docs.ts

@@ -1,205 +1,213 @@
-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;
+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);
+    // A path that is the file's own route changes nothing; moving it would delete the page (`index` at `/index`, API-129).
+    if (customPath === fileRoutePath) return;
+    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,`,
+        // The home page owns its path, so `pages/index.md` does not take it over (API-129).
+        ...(config.__resolvedModules.landing.enabled
+          ? [
+              `  reservedPaths: ${JSON.stringify([config.__resolvedModules.landing.path])},`,
+            ]
+          : []),
+        `  defaultOptions: ${JSON.stringify(docsConfig.defaultOptions)},`,
+        `});`,
+      );
+
+      await writePluginDebugCode(config.__meta.rootDir, "docs-plugin", code);
+
+      return code.join("\n");
+    },
+  };
+};
+
+export default viteDocsPlugin;

package/docs/concepts/auth-provider-api-identities.md

@@ -1,105 +0,0 @@
----
-title: Authentication Providers & API Identities
-sidebar_label: Authentication and Identities
----
-
-When building an API documentation portal, you often need a way for users to authenticate API
-requests — API keys and other identities — separately from how they sign in to the portal. APIToGo
-splits **portal authentication** from **API identities**.
-
-## Authentication Providers and API Identities
-
-:::tip
-
-**Authentication providers** allow your users to sign in to your documentation portal. **API
-Identities** allow your users to authenticate their API requests.
-
-:::
-
-Before diving into API Identities, it's important to understand that APIToGo separates user
-authentication from API authentication. Authentication providers handle how users sign in to your
-documentation portal, while API Identities manage how these users interact with your APIs.
-
-Portal products use [`dev-portal`](../configuration/authentication.md) auth (backend-delegated
-OIDC). SPA providers (Auth0, Clerk, …) are advanced for standalone docs sites. Providers handle:
-
-- User authentication for the documentation portal
-- Session management
-- User authorization and access control
-
-This separation allows you to:
-
-- Use different authentication methods for your portal and APIs
-- Manage API access independently of user authentication
-- Support multiple API authentication schemes simultaneously
-
-[Learn more about authentication providers](../configuration/authentication)
-
-## Understanding API Identities
-
-API Identities in APIToGo represent different authentication contexts that can be used to make API
-requests. These could be different environments (production, staging), different authentication
-methods (API key, JWT), or different service accounts.
-
-### The API Identity Interface
-
-```typescript
-interface ApiIdentity {
-  id: string;
-  label: string;
-  authorizeRequest: (request: Request) => Promise<Request> | Request;
-}
-
-interface ApiIdentityPlugin {
-  getIdentities: () => Promise<ApiIdentity[]> | ApiIdentity[];
-}
-```
-
-Each API Identity consists of:
-
-- `id`: A unique identifier for the identity
-- `label`: A human-readable name shown in the UI
-- `authorizeRequest`: A function that modifies requests to include the necessary authentication
-
-## Implementing API Identities
-
-In this example, we'll use Auth0 as our authentication provider and implement an API Identity for a
-demo API.
-
-:::note
-
-For APItoGo-hosted portals, subscription keys come from the platform after `dev-portal` sign-in.
-Implement custom API Identities when the playground should attach your own keys or JWTs.
-
-:::
-
-To add API Identities, implement the `ApiIdentityPlugin` interface:
-
-```typescript
-import { createApiIdentityPlugin } from "@lukoweb/apitogo/plugins";
-
-export default {
-  authentication: {
-    type: "auth0",
-    domain: "my-domain.auth0.com",
-    clientId: "my-client-id",
-  },
-  plugins: [
-    createApiIdentityPlugin({
-      getIdentities: async (context) => [
-        {
-          id: "api-key-one",
-          label: "My API Key",
-          authorizeRequest: (request) => {
-            // We get the access token from the
-            // authentication provider (Auth0) and add it to the request headers
-            return context.authentication?.signRequest(request);
-          },
-        },
-      ],
-    }),
-  ],
-};
-```
-
-When implemented, this identity will appear in the APIToGo playground.

package/docs/configuration/ai-assistants.md

@@ -1,65 +0,0 @@
----
-title: AI Assistants
-sidebar_icon: bot
-description:
-  Configure which AI assistant integrations appear in dropdown menus across your APIToGo
-  documentation site, including built-in presets and custom providers.
----
-
-By default, APIToGo shows "Use in Claude" and "Use in ChatGPT" options in dropdown menus on both
-[API reference](./api-reference.md) and [documentation](./docs.md) pages. You can customize this
-behavior using the top-level `aiAssistants` configuration.
-
-## Disable AI Assistants
-
-To remove all AI assistant options:
-
-```ts title=config
-const config = {
-  aiAssistants: false,
-  // ...
-};
-```
-
-## Use Only Specific Presets
-
-```ts title=config
-const config = {
-  aiAssistants: ["claude"], // Only show Claude
-  // ...
-};
-```
-
-Available presets: `"claude"`, `"chatgpt"`
-
-## Add Custom AI Assistants
-
-You can add custom entries with a label and URL. Use `{pageUrl}` as a placeholder in the URL string,
-or provide a callback for full control:
-
-```ts title=config
-const config = {
-  aiAssistants: [
-    "claude", // built-in preset
-    {
-      label: "Open in MyAI",
-      // Simple string with placeholder
-      url: "https://myai.com/?context={pageUrl}",
-    },
-    {
-      label: "Open in CustomAI",
-      // Callback for full control
-      url: ({ pageUrl, type }) => {
-        if (type === "openapi") {
-          return `https://custom.ai/?q=${encodeURIComponent("Explain this API: " + pageUrl)}`;
-        }
-        return `https://custom.ai/?q=${encodeURIComponent("Explain this page: " + pageUrl)}`;
-      },
-    },
-  ],
-  // ...
-};
-```
-
-The callback receives `{ pageUrl: string, type: "docs" | "openapi" }` so you can customize behavior
-per context.