@barodoc/theme-docs 5.0.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barodoc/theme-docs",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Documentation theme for Barodoc",
   "type": "module",
   "exports": {
@@ -28,9 +28,13 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.563.0",
+    "medium-zoom": "^1.1.0",
     "mermaid": "^11.12.2",
+    "reading-time": "^1.5.0",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0",
     "tailwind-merge": "^3.4.0",
-    "@barodoc/core": "5.0.0"
+    "@barodoc/core": "6.0.0"
   },
   "peerDependencies": {
     "astro": "^5.0.0",

package/src/components/Contributors.astro

@@ -0,0 +1,71 @@
+---
+import { execSync } from "node:child_process";
+
+interface Props {
+  filePath?: string;
+}
+
+interface Contributor {
+  name: string;
+  email: string;
+  avatarUrl: string;
+}
+
+const { filePath } = Astro.props;
+
+let contributors: Contributor[] = [];
+
+if (filePath) {
+  try {
+    const raw = execSync(
+      `git log --format='%aN|%aE' -- "${filePath}"`,
+      { encoding: "utf-8", timeout: 5000 }
+    ).trim();
+
+    if (raw) {
+      const seen = new Map<string, Contributor>();
+      for (const line of raw.split("\n")) {
+        const [name, email] = line.split("|");
+        if (!name || seen.has(email)) continue;
+        const hash = email.trim().toLowerCase();
+        seen.set(email, {
+          name: name.trim(),
+          email: email.trim(),
+          avatarUrl: `https://gravatar.com/avatar/${await computeHash(hash)}?s=64&d=mp`,
+        });
+      }
+      contributors = Array.from(seen.values());
+    }
+  } catch {
+    // git not available or file not tracked
+  }
+}
+
+async function computeHash(input: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+---
+
+{contributors.length > 0 && (
+  <div class="bd-contributors">
+    <span class="bd-contributors-label">Contributors</span>
+    <div class="bd-contributors-avatars">
+      {contributors.map((c) => (
+        <img
+          src={c.avatarUrl}
+          alt={c.name}
+          title={c.name}
+          class="bd-contributor-avatar"
+          loading="lazy"
+          width="28"
+          height="28"
+        />
+      ))}
+    </div>
+  </div>
+)}

package/src/components/KeyboardShortcuts.astro

@@ -0,0 +1,108 @@
+---
+// Keyboard shortcuts: Cmd/Ctrl+K → search, ←/→ → prev/next, ? → help modal
+---
+
+<script>
+  function initKeyboardShortcuts() {
+    if (window.__bdShortcutsInit) return;
+    window.__bdShortcutsInit = true;
+
+    const isMac = navigator.platform.toUpperCase().includes('MAC');
+    const modLabel = isMac ? '⌘' : 'Ctrl';
+
+    function isInputFocused(): boolean {
+      const el = document.activeElement;
+      if (!el) return false;
+      const tag = el.tagName;
+      return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || (el as HTMLElement).isContentEditable;
+    }
+
+    function showShortcutsModal() {
+      if (document.querySelector('.bd-shortcuts-overlay')) return;
+
+      const overlay = document.createElement('div');
+      overlay.className = 'bd-shortcuts-overlay';
+      overlay.addEventListener('click', (e) => {
+        if (e.target === overlay) overlay.remove();
+      });
+
+      overlay.innerHTML = `
+        <div class="bd-shortcuts-modal">
+          <h3>Keyboard Shortcuts</h3>
+          <div class="bd-shortcut-row">
+            <span class="bd-shortcut-desc">Search</span>
+            <span class="bd-shortcut-keys"><kbd class="bd-kbd">${modLabel}</kbd><kbd class="bd-kbd">K</kbd></span>
+          </div>
+          <div class="bd-shortcut-row">
+            <span class="bd-shortcut-desc">Previous page</span>
+            <span class="bd-shortcut-keys"><kbd class="bd-kbd">←</kbd></span>
+          </div>
+          <div class="bd-shortcut-row">
+            <span class="bd-shortcut-desc">Next page</span>
+            <span class="bd-shortcut-keys"><kbd class="bd-kbd">→</kbd></span>
+          </div>
+          <div class="bd-shortcut-row">
+            <span class="bd-shortcut-desc">Show shortcuts</span>
+            <span class="bd-shortcut-keys"><kbd class="bd-kbd">?</kbd></span>
+          </div>
+        </div>
+      `;
+
+      document.body.appendChild(overlay);
+    }
+
+    document.addEventListener('keydown', (e: KeyboardEvent) => {
+      // Close modal on Escape
+      if (e.key === 'Escape') {
+        const modal = document.querySelector('.bd-shortcuts-overlay');
+        if (modal) { modal.remove(); return; }
+      }
+
+      // Cmd/Ctrl+K → open search
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        const searchBtn = document.querySelector('[data-search-trigger]') as HTMLButtonElement;
+        if (searchBtn) searchBtn.click();
+        return;
+      }
+
+      if (isInputFocused()) return;
+
+      // ? → show shortcuts
+      if (e.key === '?' || (e.shiftKey && e.key === '/')) {
+        e.preventDefault();
+        showShortcutsModal();
+        return;
+      }
+
+      // ← → prev page
+      if (e.key === 'ArrowLeft' && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        const prev = document.querySelector('nav[aria-label="Page navigation"] a:first-of-type') as HTMLAnchorElement;
+        if (prev) { prev.click(); return; }
+      }
+
+      // → → next page
+      if (e.key === 'ArrowRight' && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        const links = document.querySelectorAll('nav[aria-label="Page navigation"] a');
+        const next = links[links.length - 1] as HTMLAnchorElement;
+        if (next && links.length > 1) { next.click(); return; }
+        if (next && links.length === 1) {
+          const parent = next.closest('.col-span-1');
+          if (parent && parent === parent.parentElement?.lastElementChild) { next.click(); }
+        }
+      }
+    });
+  }
+
+  initKeyboardShortcuts();
+  document.addEventListener('astro:page-load', () => {
+    window.__bdShortcutsInit = false;
+    initKeyboardShortcuts();
+  });
+
+  declare global {
+    interface Window {
+      __bdShortcutsInit?: boolean;
+    }
+  }
+</script>

package/src/components/VersionSwitcher.tsx

@@ -0,0 +1,79 @@
+import * as React from "react";
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+
+interface VersionConfig {
+  label: string;
+  path: string;
+}
+
+interface VersionSwitcherProps {
+  versions: VersionConfig[];
+  currentPath: string;
+}
+
+export function VersionSwitcher({ versions, currentPath }: VersionSwitcherProps) {
+  if (!versions || versions.length <= 1) return null;
+
+  const current = versions.find((v) => currentPath.includes(`/docs/${v.path}/`)) || versions[0];
+
+  function switchVersion(target: VersionConfig) {
+    const regex = /\/docs\/([^/]+)\//;
+    const match = currentPath.match(regex);
+    if (match) {
+      const newPath = currentPath.replace(`/docs/${match[1]}/`, `/docs/${target.path}/`);
+      window.location.href = newPath;
+    } else {
+      window.location.href = `/docs/${target.path}/`;
+    }
+  }
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <button className="bd-version-trigger">
+          {current.label}
+          <svg
+            width="12"
+            height="12"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="m6 9 6 6 6-6" />
+          </svg>
+        </button>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content className="bd-version-menu" sideOffset={4} align="start">
+          {versions.map((v) => (
+            <DropdownMenu.Item
+              key={v.path}
+              className={`bd-version-item ${v.path === current.path ? "bd-version-active" : ""}`}
+              onSelect={() => switchVersion(v)}
+            >
+              {v.label}
+              {v.path === current.path && (
+                <svg
+                  width="14"
+                  height="14"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2.5"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                >
+                  <polyline points="20 6 9 17 4 12" />
+                </svg>
+              )}
+            </DropdownMenu.Item>
+          ))}
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}

package/src/components/index.ts

@@ -24,6 +24,11 @@ export { Expandable, ExpandableList, ExpandableItem } from "./mdx/Expandable.tsx
 export { Icon, CheckIcon, XIcon, InfoIcon, WarningIcon } from "./mdx/Icon.tsx";
 export { Steps, Step } from "./mdx/Steps.tsx";
 export { Mermaid } from "./mdx/Mermaid.tsx";
+export { ImageZoom } from "./mdx/ImageZoom.tsx";
+export { Video } from "./mdx/Video.tsx";
+export { ApiPlayground } from "./mdx/ApiPlayground.tsx";
+
+export { VersionSwitcher } from "./VersionSwitcher.tsx";
 
 // Legacy exports for backwards compatibility
 export { Tabs, Tab } from "./mdx/Tabs.tsx";

package/src/components/mdx/ApiPlayground.tsx

@@ -0,0 +1,200 @@
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+
+interface ParamDef {
+  name: string;
+  in: "query" | "path" | "header" | "body";
+  type?: string;
+  required?: boolean;
+  defaultValue?: string;
+  description?: string;
+}
+
+interface ApiPlaygroundProps {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  url: string;
+  params?: ParamDef[];
+  body?: string;
+  headers?: Record<string, string>;
+  className?: string;
+}
+
+const methodColors: Record<string, string> = {
+  GET: "bg-green-100 text-green-800 dark:bg-green-950 dark:text-green-300",
+  POST: "bg-blue-100 text-blue-800 dark:bg-blue-950 dark:text-blue-300",
+  PUT: "bg-amber-100 text-amber-800 dark:bg-amber-950 dark:text-amber-300",
+  PATCH: "bg-orange-100 text-orange-800 dark:bg-orange-950 dark:text-orange-300",
+  DELETE: "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300",
+};
+
+export function ApiPlayground({
+  method = "GET",
+  url,
+  params = [],
+  body: initialBody,
+  headers: initialHeaders = {},
+  className,
+}: ApiPlaygroundProps) {
+  const [paramValues, setParamValues] = React.useState<Record<string, string>>(() => {
+    const vals: Record<string, string> = {};
+    for (const p of params) {
+      vals[p.name] = p.defaultValue || "";
+    }
+    return vals;
+  });
+  const [bodyValue, setBodyValue] = React.useState(initialBody || "");
+  const [response, setResponse] = React.useState<{
+    status: number;
+    statusText: string;
+    body: string;
+    time: number;
+  } | null>(null);
+  const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  function buildUrl(): string {
+    let finalUrl = url;
+    const queryParams = new URLSearchParams();
+
+    for (const p of params) {
+      const val = paramValues[p.name] || "";
+      if (p.in === "path") {
+        finalUrl = finalUrl.replace(`{${p.name}}`, encodeURIComponent(val));
+      } else if (p.in === "query" && val) {
+        queryParams.set(p.name, val);
+      }
+    }
+
+    const qs = queryParams.toString();
+    return qs ? `${finalUrl}?${qs}` : finalUrl;
+  }
+
+  async function sendRequest() {
+    setLoading(true);
+    setError(null);
+    setResponse(null);
+
+    const start = performance.now();
+    const reqUrl = buildUrl();
+
+    const headers: Record<string, string> = { ...initialHeaders };
+    for (const p of params) {
+      if (p.in === "header" && paramValues[p.name]) {
+        headers[p.name] = paramValues[p.name];
+      }
+    }
+
+    const hasBody = ["POST", "PUT", "PATCH"].includes(method) && bodyValue;
+    if (hasBody && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    try {
+      const res = await fetch(reqUrl, {
+        method,
+        headers,
+        body: hasBody ? bodyValue : undefined,
+      });
+
+      const elapsed = Math.round(performance.now() - start);
+      let text: string;
+      try {
+        const json = await res.json();
+        text = JSON.stringify(json, null, 2);
+      } catch {
+        text = await res.text();
+      }
+
+      setResponse({ status: res.status, statusText: res.statusText, body: text, time: elapsed });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Request failed");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className={cn("bd-playground", className)}>
+      {/* Header */}
+      <div className="bd-playground-header">
+        <span className={cn("bd-playground-method", methodColors[method])}>
+          {method}
+        </span>
+        <code className="bd-playground-url">{url}</code>
+        <button
+          className="bd-playground-send"
+          onClick={sendRequest}
+          disabled={loading}
+        >
+          {loading ? "Sending..." : "Send"}
+        </button>
+      </div>
+
+      {/* Parameters */}
+      {params.length > 0 && (
+        <div className="bd-playground-params">
+          {params.map((p) => (
+            <div key={p.name} className="bd-playground-param">
+              <label className="bd-playground-label">
+                <span>{p.name}</span>
+                <span className="bd-playground-param-meta">
+                  {p.in}
+                  {p.required && <span className="bd-playground-required">*</span>}
+                </span>
+              </label>
+              <input
+                type="text"
+                className="bd-playground-input"
+                value={paramValues[p.name] || ""}
+                placeholder={p.description || p.type || ""}
+                onChange={(e) =>
+                  setParamValues((prev) => ({ ...prev, [p.name]: e.target.value }))
+                }
+              />
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Body */}
+      {["POST", "PUT", "PATCH"].includes(method) && (
+        <div className="bd-playground-body-section">
+          <label className="bd-playground-label">Request Body</label>
+          <textarea
+            className="bd-playground-textarea"
+            value={bodyValue}
+            onChange={(e) => setBodyValue(e.target.value)}
+            rows={6}
+            placeholder='{ "key": "value" }'
+          />
+        </div>
+      )}
+
+      {/* Response */}
+      {(response || error) && (
+        <div className="bd-playground-response">
+          {error ? (
+            <div className="bd-playground-error">{error}</div>
+          ) : response ? (
+            <>
+              <div className="bd-playground-response-header">
+                <span
+                  className={cn(
+                    "bd-playground-status",
+                    response.status < 300 ? "bd-status-ok" : "bd-status-err"
+                  )}
+                >
+                  {response.status} {response.statusText}
+                </span>
+                <span className="bd-playground-time">{response.time}ms</span>
+              </div>
+              <pre className="bd-playground-pre">
+                <code>{response.body}</code>
+              </pre>
+            </>
+          ) : null}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/mdx/ImageZoom.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import mediumZoom from "medium-zoom";
+import type { Zoom } from "medium-zoom";
+
+interface ImageZoomProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  zoomSrc?: string;
+}
+
+export function ImageZoom({ zoomSrc, ...props }: ImageZoomProps) {
+  const imgRef = React.useRef<HTMLImageElement>(null);
+  const zoomRef = React.useRef<Zoom | null>(null);
+
+  React.useEffect(() => {
+    if (!imgRef.current) return;
+
+    zoomRef.current = mediumZoom(imgRef.current, {
+      margin: 24,
+      background: "var(--bd-bg)",
+      scrollOffset: 0,
+    });
+
+    return () => {
+      zoomRef.current?.detach();
+    };
+  }, []);
+
+  return (
+    <img
+      ref={imgRef}
+      data-zoom-src={zoomSrc}
+      className="bd-image-zoom"
+      {...props}
+    />
+  );
+}

package/src/components/mdx/Video.tsx

@@ -0,0 +1,71 @@
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+
+interface VideoProps {
+  url: string;
+  title?: string;
+  caption?: string;
+  className?: string;
+}
+
+function parseVideoUrl(url: string): { provider: string; embedUrl: string } | null {
+  // YouTube: youtube.com/watch?v=ID, youtu.be/ID, youtube.com/embed/ID
+  const ytMatch = url.match(
+    /(?:youtube\.com\/(?:watch\?v=|embed\/)|youtu\.be\/)([a-zA-Z0-9_-]{11})/
+  );
+  if (ytMatch) {
+    return {
+      provider: "youtube",
+      embedUrl: `https://www.youtube-nocookie.com/embed/${ytMatch[1]}?rel=0`,
+    };
+  }
+
+  // Vimeo: vimeo.com/ID, player.vimeo.com/video/ID
+  const vimeoMatch = url.match(/(?:vimeo\.com\/|player\.vimeo\.com\/video\/)(\d+)/);
+  if (vimeoMatch) {
+    return {
+      provider: "vimeo",
+      embedUrl: `https://player.vimeo.com/video/${vimeoMatch[1]}?dnt=1`,
+    };
+  }
+
+  // Loom: loom.com/share/ID, loom.com/embed/ID
+  const loomMatch = url.match(/loom\.com\/(?:share|embed)\/([a-f0-9]+)/);
+  if (loomMatch) {
+    return {
+      provider: "loom",
+      embedUrl: `https://www.loom.com/embed/${loomMatch[1]}`,
+    };
+  }
+
+  return null;
+}
+
+export function Video({ url, title, caption, className }: VideoProps) {
+  const parsed = parseVideoUrl(url);
+
+  if (!parsed) {
+    return (
+      <div className={cn("bd-video", className)} style={{ paddingTop: 0, padding: "2rem" }}>
+        <p style={{ color: "var(--bd-text-muted)", margin: 0, textAlign: "center" }}>
+          Unsupported video URL: {url}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <figure className={className}>
+      <div className="bd-video">
+        <iframe
+          src={parsed.embedUrl}
+          title={title || `${parsed.provider} video`}
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowFullScreen
+          loading="lazy"
+        />
+      </div>
+      {caption && <figcaption className="bd-video-caption">{caption}</figcaption>}
+    </figure>
+  );
+}

package/src/index.ts

@@ -3,6 +3,8 @@ import type { ThemeExport, ResolvedBarodocConfig } from "@barodoc/core";
 import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
+import remarkMath from "remark-math";
+import rehypeKatex from "rehype-katex";
 
 export interface DocsThemeOptions {
   customCss?: string[];
@@ -79,9 +81,33 @@ function createThemeIntegration(
           entrypoint: "@barodoc/theme-docs/pages/docs/[...slug].astro",
         });
 
+        // Blog routes
+        if (config?.blog?.enabled !== false) {
+          injectRoute({
+            pattern: "/blog",
+            entrypoint: "@barodoc/theme-docs/pages/blog/index.astro",
+          });
+          injectRoute({
+            pattern: "/blog/[...slug]",
+            entrypoint: "@barodoc/theme-docs/pages/blog/[...slug].astro",
+          });
+        }
+
+        // Changelog route
+        injectRoute({
+          pattern: "/changelog",
+          entrypoint: "@barodoc/theme-docs/pages/changelog/index.astro",
+        });
+
         // Update Astro config with integrations and Vite plugins
         updateConfig({
-          integrations: [mdx(), react()],
+          integrations: [
+            mdx({
+              remarkPlugins: [remarkMath],
+              rehypePlugins: [rehypeKatex],
+            }),
+            react(),
+          ],
           vite: {
             plugins: [tailwindcss()],
             optimizeDeps: {

package/src/layouts/BaseLayout.astro

@@ -45,6 +45,9 @@ const themeCSS = config.theme?.colors ? generateThemeCSS(config.theme.colors) :
     <meta name="twitter:description" content={description} />
     {ogImageUrl && <meta name="twitter:image" content={ogImageUrl} />}
 
+    <!-- KaTeX math rendering -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" crossorigin="anonymous" />
+
     <title>{title}</title>
     <ThemeScript />
     <ClientRouter />