feat: improve build configuration and MDX components

- Update vite.config.ts for dual-mode builds (submodule/symlink)
- Fix "Back to Dashboard" navigation to work with /docs/ base path
- Add API key selector dropdown in documentation
- Add copy-to-clipboard functionality for config code blocks
- Update package.json build script for flexible output handling
- Downgrade @types/node to v18 for compatibility
- Add dist/ to .gitignore

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: pescn

.gitignore

@@ -17,5 +17,6 @@ node_modules
 
 .source
 
-# Build output (generated to backend/docs)
-../backend/docs/
+# Build output
+dist/
+../backend/docs/

bun.lock

@@ -5,10 +5,10 @@
   "sideEffects": false,
   "scripts": {
     "dev": "vite dev",
-    "build": "vite build && rm -rf ../backend/docs/server",
+    "build": "vite build && rm -rf dist/server ../backend/docs/server 2>/dev/null; [ -d dist/client ] && (cp -r dist/client/. ../NexusGate/backend/docs/ 2>/dev/null || cp -r dist/client/. ../backend/docs/); [ -d ../backend/docs/client ] && cp -r ../backend/docs/client/. ../backend/docs/ && rm -rf ../backend/docs/client; true",
     "start": "serve dist/client",
     "types:check": "fumadocs-mdx && tsc --noEmit",
-    "postinstall": "fumadocs-mdx"
+    "postinstall": "fumadocs-mdx 2>/dev/null || true"
   },
   "dependencies": {
     "@orama/orama": "^3.1.18",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "@tailwindcss/vite": "^4.1.18",
     "@types/mdx": "^2.0.13",
-    "@types/node": "^25.0.5",
+    "@types/node": "^18.19.0",
     "@types/react": "^19.2.8",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.2",

package.json

@@ -0,0 +1,89 @@
+'use client';
+
+import { createContext, useContext, useState, useEffect, ReactNode } from 'react';
+
+interface ApiKeyInfo {
+  key: string;
+  comment: string;
+  revoked: boolean;
+}
+
+interface ApiKeyContextType {
+  apiKeys: ApiKeyInfo[];
+  selectedApiKey: string | null;
+  setSelectedApiKey: (key: string | null) => void;
+  isLoading: boolean;
+  error: string | null;
+}
+
+const ApiKeyContext = createContext<ApiKeyContextType | null>(null);
+
+export function ApiKeyProvider({ children }: { children: ReactNode }) {
+  const [apiKeys, setApiKeys] = useState<ApiKeyInfo[]>([]);
+  const [selectedApiKey, setSelectedApiKey] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const fetchApiKeys = async () => {
+      try {
+        // Get admin secret from localStorage (same as frontend)
+        const adminSecret = localStorage.getItem('admin-secret');
+        if (!adminSecret) {
+          setError('Not authenticated');
+          setIsLoading(false);
+          return;
+        }
+
+        const response = await fetch('/api/admin/apiKey', {
+          headers: {
+            'Authorization': `Bearer ${JSON.parse(adminSecret)}`,
+          },
+        });
+
+        if (!response.ok) {
+          throw new Error('Failed to fetch API keys');
+        }
+
+        const data = await response.json();
+        // Filter out revoked keys
+        const activeKeys = data.filter((k: ApiKeyInfo) => !k.revoked);
+        setApiKeys(activeKeys);
+
+        // Auto-select first key if available
+        if (activeKeys.length > 0) {
+          setSelectedApiKey(activeKeys[0].key);
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    if (typeof window !== 'undefined') {
+      fetchApiKeys();
+    }
+  }, []);
+
+  return (
+    <ApiKeyContext.Provider value={{ apiKeys, selectedApiKey, setSelectedApiKey, isLoading, error }}>
+      {children}
+    </ApiKeyContext.Provider>
+  );
+}
+
+export function useApiKey() {
+  const context = useContext(ApiKeyContext);
+  if (!context) {
+    // Return default values if used outside provider
+    return {
+      apiKeys: [],
+      selectedApiKey: null,
+      setSelectedApiKey: () => {},
+      isLoading: false,
+      error: 'No provider',
+    };
+  }
+  return context;
+}

src/components/mdx/api-key-context.tsx

@@ -1,13 +1,17 @@
 'use client';
 
 import { useEffect, useState } from 'react';
+import { ChevronDown } from 'lucide-react';
+import { useApiKey } from './api-key-context';
 
 interface ApiKeyLinkProps {
   text?: string;
 }
 
 export function ApiKeyLink({ text }: ApiKeyLinkProps) {
   const [isZh, setIsZh] = useState(false);
+  const [isOpen, setIsOpen] = useState(false);
+  const { apiKeys, selectedApiKey, setSelectedApiKey, isLoading, error } = useApiKey();
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
@@ -18,20 +22,83 @@ export function ApiKeyLink({ text }: ApiKeyLinkProps) {
   const handleClick = () => {
     if (typeof window !== 'undefined') {
       const origin = window.location.origin.replace(/\/docs\/?$/, '');
-      window.location.href = `${origin}/api-keys`;
+      window.location.href = `${origin}/apps`;
     }
   };
 
-  const displayText = text || (isZh ? '点此查看 API Key' : 'Click to view API Key');
-  const title = isZh ? '点击前往 API Keys 页面' : 'Click to go to API Keys page';
+  // If loading, error, or no API keys, fallback to original behavior
+  if (isLoading || error || apiKeys.length === 0) {
+    const displayText = text || (isZh ? '点此查看 API Key' : 'Click to view API Key');
+    const title = isZh ? '点击前往 API Keys 页面' : 'Click to go to API Keys page';
+
+    return (
+      <button
+        onClick={handleClick}
+        className="fd-inline-code cursor-pointer underline decoration-dotted underline-offset-2 hover:text-fd-primary transition-colors"
+        title={title}
+      >
+        {displayText}
+      </button>
+    );
+  }
+
+  // Find the selected key info
+  const selectedKeyInfo = apiKeys.find(k => k.key === selectedApiKey);
+  const displayName = selectedKeyInfo?.comment || (isZh ? '选择 API Key' : 'Select API Key');
+
+  // Mask the API key for display
+  const maskedKey = selectedApiKey
+    ? `${selectedApiKey.slice(0, 8)}...${selectedApiKey.slice(-4)}`
+    : '';
 
   return (
-    <button
-      onClick={handleClick}
-      className="fd-inline-code cursor-pointer underline decoration-dotted underline-offset-2 hover:text-fd-primary transition-colors"
-      title={title}
-    >
-      {displayText}
-    </button>
+    <span className="relative inline-block">
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="fd-inline-code cursor-pointer inline-flex items-center gap-1 hover:text-fd-primary transition-colors"
+        title={isZh ? '点击选择 API Key' : 'Click to select API Key'}
+      >
+        <span>{maskedKey || displayName}</span>
+        <ChevronDown className="size-3" />
+      </button>
+
+      {isOpen && (
+        <>
+          {/* Backdrop to close dropdown */}
+          <div
+            className="fixed inset-0 z-40"
+            onClick={() => setIsOpen(false)}
+          />
+          {/* Dropdown menu */}
+          <div className="absolute left-0 top-full mt-1 z-50 min-w-[200px] rounded-md border bg-fd-popover p-1 shadow-md">
+            {apiKeys.map((apiKey) => (
+              <button
+                key={apiKey.key}
+                onClick={() => {
+                  setSelectedApiKey(apiKey.key);
+                  setIsOpen(false);
+                }}
+                className={`w-full text-left px-3 py-2 text-sm rounded-sm hover:bg-fd-accent hover:text-fd-accent-foreground transition-colors ${
+                  selectedApiKey === apiKey.key ? 'bg-fd-accent/50' : ''
+                }`}
+              >
+                <div className="font-medium">{apiKey.comment || (isZh ? '未命名' : 'Unnamed')}</div>
+                <div className="text-xs text-fd-muted-foreground font-mono">
+                  {apiKey.key.slice(0, 8)}...{apiKey.key.slice(-4)}
+                </div>
+              </button>
+            ))}
+            <div className="border-t mt-1 pt-1">
+              <button
+                onClick={handleClick}
+                className="w-full text-left px-3 py-2 text-sm rounded-sm hover:bg-fd-accent hover:text-fd-accent-foreground transition-colors text-fd-muted-foreground"
+              >
+                {isZh ? '管理 API Keys →' : 'Manage API Keys →'}
+              </button>
+            </div>
+          </div>
+        </>
+      )}
+    </span>
   );
 }

src/components/mdx/api-key-link.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { ReactNode } from 'react';
+import { ReactNode, useRef, useState } from 'react';
+import { Check, Copy } from 'lucide-react';
+import { useApiKey } from './api-key-context';
 
 interface ConfigCodeProps {
   children: ReactNode;
@@ -19,10 +21,56 @@ interface ConfigCodeProps {
  * </ConfigCode>
  */
 export function ConfigCode({ children, lang }: ConfigCodeProps) {
+  const codeRef = useRef<HTMLElement>(null);
+  const [copied, setCopied] = useState(false);
+  const { selectedApiKey } = useApiKey();
+
+  const handleCopy = async () => {
+    if (!codeRef.current) return;
+
+    // Get the text content and replace API key placeholder
+    let text = codeRef.current.innerText || codeRef.current.textContent || '';
+
+    // If an API key is selected, the text should already contain it
+    // But we need to handle the case where the ApiKeyLink shows masked key
+    // We'll replace any masked API key pattern with the full key
+    if (selectedApiKey) {
+      // Replace masked key pattern (e.g., "ng-xxxxx...xxxx") with full key
+      const maskedPattern = new RegExp(
+        `${selectedApiKey.slice(0, 8)}\\.\\.\\.${selectedApiKey.slice(-4)}`,
+        'g'
+      );
+      text = text.replace(maskedPattern, selectedApiKey);
+
+      // Also replace the fallback text if present
+      text = text.replace(/点此查看 API Key/g, selectedApiKey);
+      text = text.replace(/Click to view API Key/g, selectedApiKey);
+    }
+
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error('Failed to copy:', err);
+    }
+  };
+
   return (
-    <figure className="fd-codeblock not-prose relative my-4">
+    <figure className="fd-codeblock not-prose relative my-4 group">
+      <button
+        onClick={handleCopy}
+        className="absolute right-2 top-2 p-2 rounded-md bg-fd-secondary/80 hover:bg-fd-secondary border border-fd-border opacity-0 group-hover:opacity-100 transition-opacity"
+        title={copied ? 'Copied!' : 'Copy to clipboard'}
+      >
+        {copied ? (
+          <Check className="size-4 text-green-500" />
+        ) : (
+          <Copy className="size-4 text-fd-muted-foreground" />
+        )}
+      </button>
       <pre className="p-4 overflow-x-auto rounded-lg border bg-fd-secondary/50 text-sm">
-        <code className={lang ? `language-${lang}` : undefined}>
+        <code ref={codeRef} className={lang ? `language-${lang}` : undefined}>
           {children}
         </code>
       </pre>

src/components/mdx/config-code.tsx

@@ -1,4 +1,5 @@
 export { ServerUrl } from './server-url';
 export { ApiKeyLink } from './api-key-link';
+export { ApiKeyProvider } from './api-key-context';
 export { InlineCode } from './inline-code';
 export { ConfigCode, CodeKeyword, CodeString, CodeComment, CodeLine } from './config-code';

src/components/mdx/index.ts

@@ -9,14 +9,18 @@ interface NavTitleProps {
 export function NavTitle({ locale }: NavTitleProps) {
   const isZh = locale === 'zh';
 
-  // Use relative path to go up from /docs/ to root /
+  const handleClick = () => {
+    // Navigate to root, bypassing the /docs/ base path
+    window.location.href = window.location.origin + '/';
+  };
+
   return (
-    <a
-      href="/"
+    <button
+      onClick={handleClick}
       className="flex items-center gap-2 text-sm font-medium text-fd-foreground transition-colors hover:text-fd-foreground/80"
     >
       <ArrowLeft className="size-4" />
       {isZh ? '返回控制台' : 'Back to Dashboard'}
-    </a>
+    </button>
   );
 }

src/components/nav-title.tsx

@@ -9,15 +9,19 @@ interface SidebarBannerProps {
 export function SidebarBanner({ locale }: SidebarBannerProps) {
   const isZh = locale === 'zh';
 
+  const handleClick = () => {
+    window.location.href = window.location.origin + '/';
+  };
+
   return (
     <div className="px-4 pb-2">
-      <a
-        href="/"
-        className="flex items-center justify-center gap-2 rounded-md border border-fd-border px-3 py-2 text-sm font-medium text-fd-foreground transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground"
+      <button
+        onClick={handleClick}
+        className="flex w-full items-center justify-center gap-2 rounded-md border border-fd-border px-3 py-2 text-sm font-medium text-fd-foreground transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground"
       >
         <ArrowLeft className="size-4" />
         {isZh ? '返回控制台' : 'Back to Dashboard'}
-      </a>
+      </button>
     </div>
   );
 }