@opendocsdev/cli 0.2.0

package/src/engine/src/lib/utils.ts

@@ -0,0 +1,221 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Combines clsx and tailwind-merge for conditional class names.
+ * - clsx: Handles conditional classes
+ * - tailwind-merge: Resolves conflicting Tailwind classes (e.g., 'px-2 px-4' → 'px-4')
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+// =============================================================================
+// Color Utilities
+// =============================================================================
+
+interface HSL {
+  h: number;
+  s: number;
+  l: number;
+}
+
+/**
+ * Converts a hex color string to HSL values.
+ */
+export function hexToHSL(hex: string): HSL {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+        break;
+      case g:
+        h = ((b - r) / d + 2) / 6;
+        break;
+      case b:
+        h = ((r - g) / d + 4) / 6;
+        break;
+    }
+  }
+  return { h: h * 360, s: s * 100, l: l * 100 };
+}
+
+/**
+ * Converts HSL values to a hex color string.
+ */
+export function hslToHex(h: number, s: number, l: number): string {
+  s /= 100;
+  l /= 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => {
+    const k = (n + h / 30) % 12;
+    const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+    return Math.round(255 * color).toString(16).padStart(2, "0");
+  };
+  return `#${f(0)}${f(8)}${f(4)}`;
+}
+
+/**
+ * Generates theme color variants from a base hex color.
+ */
+export function generateColorVariants(hex: string) {
+  const hsl = hexToHSL(hex);
+  return {
+    base: hex,
+    light: hslToHex(hsl.h, Math.min(hsl.s, 30), 95),
+    lightDark: `rgba(${parseInt(hex.slice(1, 3), 16)}, ${parseInt(hex.slice(3, 5), 16)}, ${parseInt(hex.slice(5, 7), 16)}, 0.15)`,
+    dark: hslToHex(hsl.h, hsl.s, Math.max(hsl.l - 15, 25)),
+    darkMode: hslToHex(hsl.h, hsl.s, Math.min(hsl.l + 15, 70)),
+  };
+}
+
+// =============================================================================
+// Navigation Utilities
+// =============================================================================
+
+// Types for navigation - use loose types to match Zod schema inference
+export type PageWithChildren = { page: string; children: string[] };
+export type NestedGroup = { group: string; pages: readonly unknown[] };
+export type PageItem = string | PageWithChildren | NestedGroup;
+
+// Generic navigation group interface that accepts any pages array type
+export interface NavigationGroup {
+  group: string;
+  pages: readonly unknown[];
+}
+
+/**
+ * Type guard for PageWithChildren navigation items.
+ */
+export function isPageWithChildren(item: unknown): item is PageWithChildren {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "page" in item &&
+    "children" in item
+  );
+}
+
+/**
+ * Type guard for NestedGroup navigation items.
+ */
+export function isNestedGroup(item: unknown): item is NestedGroup {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "group" in item &&
+    "pages" in item
+  );
+}
+
+/**
+ * Converts a page path to a URL.
+ */
+export function pageToUrl(page: string): string {
+  const cleanPage = page.replace(/\.mdx?$/, "");
+  return `/${cleanPage}`;
+}
+
+/**
+ * Formats a page path for display (e.g., "getting-started" → "Getting Started").
+ */
+export function formatPageName(page: string): string {
+  const fileName = page.split("/").pop()?.replace(/\.mdx?$/, "") || page;
+  return fileName
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+/**
+ * Checks if a page path matches the current URL path.
+ */
+export function isPageActive(page: string, currentPath: string): boolean {
+  const pageUrl = pageToUrl(page);
+  return currentPath === pageUrl || currentPath === `${pageUrl}/`;
+}
+
+/**
+ * Recursively flattens navigation page items into a single array.
+ */
+function flattenPagesRecursive(items: readonly unknown[]): string[] {
+  const pages: string[] = [];
+  for (const item of items) {
+    if (typeof item === "string") {
+      pages.push(item);
+    } else if (isPageWithChildren(item)) {
+      pages.push(item.page);
+      pages.push(...item.children);
+    } else if (isNestedGroup(item)) {
+      pages.push(...flattenPagesRecursive(item.pages));
+    }
+  }
+  return pages;
+}
+
+/**
+ * Flattens all navigation groups into a single ordered array of page paths.
+ */
+export function flattenNavigation(navigation: readonly NavigationGroup[]): string[] {
+  const pages: string[] = [];
+  for (const group of navigation) {
+    pages.push(...flattenPagesRecursive(group.pages));
+  }
+  return pages;
+}
+
+/**
+ * Gets all navigation slugs for static path generation.
+ * Returns paths with .md/.mdx extensions stripped.
+ */
+export function getNavigationSlugs(navigation: readonly NavigationGroup[]): string[] {
+  return flattenNavigation(navigation).map((page) => page.replace(/\.mdx?$/, ""));
+}
+
+/**
+ * Gets previous and next page links for pagination.
+ */
+export function getPageNavigation(
+  navigation: readonly NavigationGroup[],
+  currentPath: string
+): {
+  previous: { title: string; url: string } | null;
+  next: { title: string; url: string } | null;
+} {
+  const allPages = flattenNavigation(navigation);
+  const currentIndex = allPages.findIndex((page) => {
+    const pageUrl = pageToUrl(page);
+    return currentPath === pageUrl || currentPath === `${pageUrl}/`;
+  });
+
+  let previous: { title: string; url: string } | null = null;
+  let next: { title: string; url: string } | null = null;
+
+  if (currentIndex > 0) {
+    const prevPagePath = allPages[currentIndex - 1];
+    previous = {
+      title: formatPageName(prevPagePath),
+      url: pageToUrl(prevPagePath),
+    };
+  }
+
+  if (currentIndex >= 0 && currentIndex < allPages.length - 1) {
+    const nextPagePath = allPages[currentIndex + 1];
+    next = {
+      title: formatPageName(nextPagePath),
+      url: pageToUrl(nextPagePath),
+    };
+  }
+
+  return { previous, next };
+}

package/src/engine/src/pages/[...slug].astro

@@ -0,0 +1,115 @@
+---
+/**
+ * [...slug] - Dynamic documentation page route
+ * Renders MDX content with custom components
+ */
+import DocsLayout from "../layouts/DocsLayout.astro";
+import { getProjectDir, loadConfig } from "../lib/config.js";
+import { parseFrontmatter, extractHeadings } from "../lib/markdown.js";
+import { loadMDX } from "../lib/mdx-loader.js";
+import { getNavigationSlugs } from "../lib/utils";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// MDX components
+import Callout from "../components/Callout.astro";
+import Card from "../components/Card.astro";
+import CardGroup from "../components/CardGroup.astro";
+import CodeGroup from "../components/CodeGroup.astro";
+import Steps from "../components/Steps.astro";
+import Tabs from "../components/Tabs.astro";
+import Tab from "../components/Tab.astro";
+import ApiPlayground from "../components/ApiPlayground.astro";
+
+const components = {
+  Callout,
+  Card,
+  CardGroup,
+  CodeGroup,
+  Steps,
+  Tabs,
+  Tab,
+  ApiPlayground,
+};
+
+export async function getStaticPaths() {
+  const config = await loadConfig();
+  const slugs = getNavigationSlugs(config.navigation || []);
+  return slugs.map((slug) => ({ params: { slug } }));
+}
+
+const { slug } = Astro.params;
+const projectDir = getProjectDir();
+
+let title = slug || "Documentation";
+let description = "";
+let headings: { depth: number; slug: string; text: string }[] = [];
+let Content: any = null;
+let loadError = false;
+
+try {
+  // Load the MDX module using dynamic imports via @content alias
+  const mdxModule = await loadMDX(slug || "");
+
+  if (mdxModule) {
+    Content = mdxModule.Content;
+    title = (mdxModule.frontmatter.title as string) || title;
+    description = (mdxModule.frontmatter.description as string) || "";
+
+    // Read the raw file to extract headings for table of contents
+    // Try .mdx first, then .md
+    const mdxPath = path.join(projectDir, `${slug}.mdx`);
+    const mdPath = path.join(projectDir, `${slug}.md`);
+
+    let filePath = mdxPath;
+    try {
+      await fs.access(mdxPath);
+    } catch {
+      // .mdx not found, fall back to .md extension
+      filePath = mdPath;
+    }
+
+    const rawContent = await fs.readFile(filePath, "utf-8");
+    const { body } = parseFrontmatter(rawContent);
+    headings = extractHeadings(body);
+  } else {
+    loadError = true;
+  }
+} catch (error) {
+  console.error("Error loading page:", error);
+  loadError = true;
+}
+---
+
+<DocsLayout title={title} description={description} headings={headings}>
+  {loadError ? (
+    <article class="prose dark:prose-invert max-w-none">
+      <h1>Page Not Found</h1>
+      <p>The page "{slug}" could not be found.</p>
+      <div class="mt-6 p-4 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700">
+        <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100 mt-0">What you can do:</h3>
+        <ul class="mt-2 space-y-2">
+          <li>
+            <a href="/" class="text-blue-600 hover:underline">Go to the homepage</a>
+          </li>
+          <li>
+            Use the search feature to find what you're looking for
+          </li>
+          <li>
+            Check the sidebar navigation for available pages
+          </li>
+          <li>
+            Verify the URL is spelled correctly
+          </li>
+        </ul>
+      </div>
+      <p class="mt-4 text-sm text-gray-500 dark:text-gray-400">
+        If you believe this page should exist, please check your <code class="bg-gray-100 dark:bg-gray-700 px-1 py-0.5 rounded text-sm">docs.json</code> configuration.
+      </p>
+    </article>
+  ) : (
+    <article class="prose dark:prose-invert max-w-none">
+      <Content components={components} />
+    </article>
+  )}
+</DocsLayout>

package/src/engine/src/pages/index.astro

@@ -0,0 +1,71 @@
+---
+/**
+ * Index page - Redirects to first documentation page or shows welcome
+ */
+import DocsLayout from "../layouts/DocsLayout.astro";
+import { loadConfig } from "../lib/config.js";
+import { pageToUrl } from "../lib/utils";
+
+const config = await loadConfig();
+const navigation = config.navigation || [];
+
+// Find the first page from navigation to redirect to, or show welcome
+const firstGroup = navigation[0];
+const firstPage = firstGroup?.pages?.[0];
+const redirectUrl = typeof firstPage === "string" ? pageToUrl(firstPage) : null;
+---
+
+{redirectUrl ? (
+  <html>
+    <head>
+      <meta charset="utf-8" />
+      <meta http-equiv="refresh" content={`0;url=${redirectUrl}`} />
+      <link rel="canonical" href={redirectUrl} />
+      <script is:inline define:vars={{ redirectUrl }}>
+        window.location.replace(redirectUrl);
+      </script>
+    </head>
+    <body>
+      <p>Redirecting to <a href={redirectUrl}>{redirectUrl}</a>...</p>
+    </body>
+  </html>
+) : (
+
+<DocsLayout title="Welcome" description="Welcome to your documentation site">
+  <h1>Welcome to {config.name || "Your Documentation"}</h1>
+  <p>
+    Your documentation site is ready. Add pages to your <code>docs.json</code>
+    navigation to get started.
+  </p>
+
+  <h2>Getting Started</h2>
+  <p>
+    Create MDX files in your project directory and add them to the{" "}
+    <code>navigation</code> array in your <code>docs.json</code> file.
+  </p>
+
+  <h3>Example docs.json</h3>
+  <pre><code>{`{
+  "name": "My Documentation",
+  "navigation": [
+    {
+      "group": "Getting Started",
+      "pages": ["introduction", "quickstart"]
+    }
+  ]
+}`}</code></pre>
+
+  <h3>Example MDX file</h3>
+  <p>
+    Create an <code>introduction.mdx</code> file with frontmatter:
+  </p>
+  <pre><code>{`---
+title: Introduction
+description: Learn about our product
+---
+
+# Introduction
+
+Welcome to the documentation!`}</code></pre>
+</DocsLayout>
+)}

package/src/engine/src/scripts/mobile-sidebar.ts

@@ -0,0 +1,56 @@
+/**
+ * Mobile sidebar toggle functionality.
+ * Handles opening/closing the mobile navigation drawer.
+ */
+
+function initMobileSidebar(): void {
+  const hamburger =
+    document.querySelector<HTMLButtonElement>("[data-hamburger]");
+  const mobileSidebar = document.querySelector<HTMLElement>(
+    "[data-mobile-sidebar]",
+  );
+  const backdrop = document.querySelector<HTMLElement>("[data-backdrop]");
+
+  if (!hamburger || !mobileSidebar || !backdrop) return;
+
+  function openSidebar(): void {
+    if (!mobileSidebar || !backdrop) return;
+    mobileSidebar.classList.remove("-translate-x-full");
+    mobileSidebar.classList.add("translate-x-0");
+    backdrop.classList.remove("opacity-0", "pointer-events-none");
+    backdrop.classList.add("opacity-100", "pointer-events-auto");
+    document.body.classList.add("overflow-hidden");
+  }
+
+  function closeSidebarFn(): void {
+    if (!mobileSidebar || !backdrop) return;
+    mobileSidebar.classList.add("-translate-x-full");
+    mobileSidebar.classList.remove("translate-x-0");
+    backdrop.classList.add("opacity-0", "pointer-events-none");
+    backdrop.classList.remove("opacity-100", "pointer-events-auto");
+    document.body.classList.remove("overflow-hidden");
+  }
+
+  // Open sidebar on hamburger click
+  hamburger.addEventListener("click", openSidebar);
+
+  // Close sidebar on backdrop click
+  backdrop.addEventListener("click", closeSidebarFn);
+
+  // Close sidebar on Escape key
+  document.addEventListener("keydown", (e: KeyboardEvent) => {
+    if (
+      e.key === "Escape" &&
+      mobileSidebar &&
+      !mobileSidebar.classList.contains("-translate-x-full")
+    ) {
+      closeSidebarFn();
+    }
+  });
+}
+
+// Initialize on page load
+initMobileSidebar();
+
+// Re-initialize after View Transitions (Astro navigation)
+document.addEventListener("astro:after-swap", initMobileSidebar);

package/src/engine/src/scripts/theme-init.ts

@@ -0,0 +1,25 @@
+/**
+ * Theme initialization script.
+ * This script should be inlined in the <head> to prevent flash of wrong theme.
+ * It reads the user's preference from localStorage or system preference.
+ */
+
+// Immediately invoked to run before paint
+(function () {
+  // Check localStorage first
+  const storedTheme = localStorage.getItem("theme");
+
+  if (storedTheme === "dark") {
+    document.documentElement.classList.add("dark");
+  } else if (storedTheme === "light") {
+    document.documentElement.classList.remove("dark");
+  } else {
+    // No stored preference - check system preference
+    const prefersDark = window.matchMedia(
+      "(prefers-color-scheme: dark)",
+    ).matches;
+    if (prefersDark) {
+      document.documentElement.classList.add("dark");
+    }
+  }
+})();