@clidey/dory 0.29.0 → 0.31.0

package/src/sdk/vue.ts

@@ -0,0 +1,107 @@
+/**
+ * Vue SDK for Dory Embedded Documentation
+ * Usage: npm install @clidey/dory-embedded
+ */
+
+// @ts-ignore - Vue is an optional peer dependency
+import { ref, onMounted, onUnmounted, computed } from 'vue';
+import type { DoryDocsAPI } from '../embed/types';
+
+interface DoryDocsConfig {
+  docsUrl: string;
+  position?: 'left' | 'right' | 'bottom';
+  width?: number | string;
+  height?: string;
+  theme?: 'light' | 'dark' | 'inherit';
+  initialPath?: string;
+  showOverlay?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOverlayClick?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onNavigate?: (path: string) => void;
+  onReady?: () => void;
+}
+
+/**
+ * Composable to use Dory Documentation in Vue components
+ */
+export function useDoryDocs(config: DoryDocsConfig) {
+  const docsInstance = ref<any>(null);
+  const isReady = ref(false);
+
+  const initDocs = () => {
+    if (window.DoryDocs) {
+      docsInstance.value = window.DoryDocs.init(config);
+      isReady.value = true;
+    } else {
+      console.warn('[useDoryDocs] DoryDocs not loaded. Make sure to include the embed script.');
+    }
+  };
+
+  onMounted(() => {
+    if (document.readyState === 'loading') {
+      window.addEventListener('dory:ready', initDocs);
+    } else {
+      initDocs();
+    }
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener('dory:ready', initDocs);
+    if (docsInstance.value) {
+      docsInstance.value.destroy();
+    }
+  });
+
+  const open = async (path?: string) => {
+    if (docsInstance.value) {
+      await docsInstance.value.open(path);
+    }
+  };
+
+  const close = async () => {
+    if (docsInstance.value) {
+      await docsInstance.value.close();
+    }
+  };
+
+  const toggle = async () => {
+    if (docsInstance.value) {
+      await docsInstance.value.toggle();
+    }
+  };
+
+  const navigate = async (path: string) => {
+    if (docsInstance.value) {
+      await docsInstance.value.navigate(path);
+    }
+  };
+
+  const setTheme = async (theme: 'light' | 'dark') => {
+    if (docsInstance.value) {
+      await docsInstance.value.setTheme(theme);
+    }
+  };
+
+  const isOpen = computed(() => {
+    return docsInstance.value?.isOpen() || false;
+  });
+
+  return {
+    open,
+    close,
+    toggle,
+    navigate,
+    setTheme,
+    isOpen: isOpen.value,
+    isReady,
+  };
+}
+
+// Type declarations
+declare global {
+  interface Window {
+    DoryDocs: DoryDocsAPI;
+  }
+}

package/src/types/config.ts

@@ -37,6 +37,47 @@ export interface DoryNavigation {
   tabs: DoryNavigationTab[];
 }
 
+export interface DoryEmbedConfig {
+  enabled?: boolean;
+  version?: string;
+  defaults?: {
+    position?: 'left' | 'right' | 'bottom';
+    width?: number;
+    height?: string;
+    theme?: 'light' | 'dark' | 'inherit';
+    showOverlay?: boolean;
+    closeOnEscape?: boolean;
+    closeOnOverlayClick?: boolean;
+  };
+  branding?: {
+    showLogo?: boolean;
+    showName?: boolean;
+    customCSS?: string;
+  };
+  features?: {
+    search?: boolean;
+    toc?: boolean;
+    codeBlocks?: boolean;
+    mermaid?: boolean;
+    katex?: boolean;
+    apiPlayground?: boolean;
+    darkMode?: boolean;
+  };
+  analytics?: {
+    enabled?: boolean;
+    trackEvents?: string[];
+  };
+  security?: {
+    allowedOrigins?: string[];
+    corsEnabled?: boolean;
+  };
+  performance?: {
+    lazyLoadImages?: boolean;
+    prefetchPages?: boolean;
+    cacheStrategy?: 'cache-first' | 'network-first';
+  };
+}
+
 export interface DoryConfig {
   name: string;
   favicon: string;
@@ -44,4 +85,5 @@ export interface DoryConfig {
   fonts?: DoryFonts;
   navigation: DoryNavigation;
   logo: DoryLogo;
+  embed?: DoryEmbedConfig;
 }

package/src/ui/header.tsx

@@ -8,6 +8,7 @@ import { MobileSearch, Search } from '../components/search';
 import { ALL_NAVIGATION } from '../components/store';
 import { MobileNavigation } from './mobile-navigation';
 import { ModeToggle } from '@clidey/ux';
+import { useIsEmbedded } from '../components/hooks';
 
 const config = docsConfig as DoryConfig;
 
@@ -32,6 +33,7 @@ function TopLevelNavItem({ href, children, isActive }: { href: string; children:
 export function Header({ className }: { className?: string }) {
   const [isScrolled, setIsScrolled] = useState(false);
   const pathname = usePathname();
+  const isEmbedded = useIsEmbedded();
 
   const { light, dark } = useMemo(() => {
     return { light: config.logo.light, dark: config.logo.dark };
@@ -82,7 +84,10 @@ export function Header({ className }: { className?: string }) {
         <div className="flex items-center gap-3" data-testid="header-actions">
           <MobileSearch />
           <Search />
-          <ModeToggle data-testid="mode-toggle" />
+          {
+            !isEmbedded &&
+            <ModeToggle data-testid="mode-toggle" />
+          }
           <MobileNavigation />
         </div>
       </div>

package/src/ui/layout.tsx

@@ -12,6 +12,8 @@ import { Loading } from '../components/loading';
 import Dropdown from '../components/dropdown';
 import { useNotification } from '../components/notification';
 import { SparkleIcon } from 'lucide-react';
+import { useIsEmbedded } from '../components/hooks';
+import { cn } from '@clidey/ux';
 
 interface LayoutProps {
   children: ComponentChildren;
@@ -25,6 +27,7 @@ export default function Layout({ children }: LayoutProps) {
   const [loading, setLoading] = useState(true);
   const [pathname] = useLocation();
   const { showNotification } = useNotification();
+  const isEmbedded = useIsEmbedded();
 
   const handleOpenMDX = useCallback(() => {
     window.open(`${window.location.origin}${pathname}.mdx`, '_blank');
@@ -178,13 +181,21 @@ export default function Layout({ children }: LayoutProps) {
   return (
     <div className="flex w-full flex-col">
       <Header />
-      <div id="container" className="relative flex w-full max-w-8xl sm:px-2 lg:px-8">
-        <div className="hidden lg:relative lg:block lg:flex-none">
+      <div id="container" className={cn("relative flex w-full", {
+        "max-w-8xl sm:px-2 lg:px-8": !isEmbedded,
+        "px-0": isEmbedded,
+      })}>
+        <div className={cn("hidden lg:relative lg:block lg:flex-none", {
+          "lg:hidden": isEmbedded,
+        })}>
           <div className="sticky top-[4.75rem] -ml-0.5 h-[calc(100vh-4.75rem)] w-64 overflow-x-hidden overflow-y-auto py-16 pr-8 pl-0.5 xl:w-72 xl:pr-16">
             <Navigation />
           </div>
         </div>
-        <main className="flex px-4 py-16 sm:px-6 lg:px-8 grow">
+        <main className={cn("flex grow max-w-full", {
+          "px-4 py-16 sm:px-6 lg:px-8": !isEmbedded,
+          "p-8": isEmbedded,
+        })}>
           <div className="min-w-0 w-full">
             <article className="h-full flex flex-1 flex-col">
               <div className="flex justify-between items-start">
@@ -206,7 +217,7 @@ export default function Layout({ children }: LayoutProps) {
                 }
               </div>
               <div className="flex-1 min-h-[calc(100vh-2rem)]">
-                {openAPIJSON && tab && "openapi" in tab && method && path ? 
+                {openAPIJSON && tab && "openapi" in tab && method && path ?
                   <OpenAPI openAPIJson={JSON.parse(openAPIJSON)} method={method} path={path} />
                  : asyncAPIJSON && tab && "asyncapi" in tab && operation && channel ?
                   <AsyncAPI asyncAPIJson={JSON.parse(asyncAPIJSON)} operation={operation} channel={channel} />
@@ -216,7 +227,7 @@ export default function Layout({ children }: LayoutProps) {
             </article>
           </div>
           {
-            openAPIJSON == null && asyncAPIJSON == null &&
+            openAPIJSON == null && asyncAPIJSON == null && !isEmbedded &&
             <TableOfContents />
           }
         </main>

package/src/ui/mobile-navigation.tsx

@@ -1,10 +1,11 @@
 'use client'
 
-import { Sheet, SheetContent, Button } from '@clidey/ux'
+import { Sheet, SheetContent, Button, ModeToggle } from '@clidey/ux'
 import { createContext, Suspense, useCallback, useContext, useRef, useState } from 'react'
 
 import { Bars3Icon, XMarkIcon } from '@heroicons/react/24/outline'
 import { Navigation } from '../components/navigation'
+import { useIsEmbedded } from '../components/hooks'
 
 const IsInsideMobileNavigationContext = createContext(false)
 
@@ -31,9 +32,10 @@ export function useMobileNavigation() {
 }
 
 export function MobileNavigation() {
-  const isInsideMobileNavigation = useIsInsideMobileNavigation()
-  const { isOpen, open, close } = useMobileNavigation()
+  const isInsideMobileNavigation = useIsInsideMobileNavigation();
+  const { isOpen, open, close } = useMobileNavigation();
   const ToggleIcon = isOpen ? XMarkIcon : Bars3Icon;
+  const isEmbedded = useIsEmbedded();
 
   return (
     <IsInsideMobileNavigationContext.Provider value={true}>
@@ -55,6 +57,12 @@ export function MobileNavigation() {
           <Suspense fallback={null}>
             <SheetContent side="left" className="w-full sm:max-w-sm p-8 overflow-y-auto flex flex-col justify-between">
               <Navigation />
+              {
+                isEmbedded &&
+                <div className="flex items-center justify-end">
+                  <ModeToggle data-testid="mode-toggle" />
+                </div>
+              }
             </SheetContent>
           </Suspense>
         )}

package/src/ui/table-of-content.tsx

@@ -28,7 +28,8 @@ export function TableOfContents() {
       let currentSection: Section | null = null
 
       headings.forEach((heading) => {
-        // Check if heading is visible
+        // Check if heading is a valid Element and is visible
+        if (!(heading instanceof Element)) return
         const style = window.getComputedStyle(heading)
         if (style.display === 'none' || style.visibility === 'hidden') return
 

package/tsconfig.bin.json

@@ -4,6 +4,7 @@
     "lib": ["ES2023"],
     "module": "ESNext",
     "moduleResolution": "node",
+    "types": ["node"],
     "skipLibCheck": true,
     "strict": true,
     "esModuleInterop": true,

package/vite.config.embed-loader.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      input: resolve(__dirname, 'src/embed/loader.ts'),
+      output: {
+        entryFileNames: 'embed.js',
+        format: 'iife',
+        inlineDynamicImports: true,
+      },
+    },
+    outDir: 'dist',
+    emptyOutDir: false,
+    minify: 'terser',
+    terserOptions: {
+      compress: {
+        drop_console: false, // Keep console for user feedback
+        drop_debugger: true,
+        pure_funcs: ['console.debug'],
+      },
+      mangle: {
+        safari10: true,
+      },
+    },
+  },
+});

package/vite.config.embed-widget.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/embed/widget-iframe.ts'),
+      name: '__DoryWidget__',
+      fileName: () => 'embed-widget.js',
+      formats: ['es'],
+    },
+    outDir: 'dist',
+    emptyOutDir: false,
+    minify: 'terser',
+    terserOptions: {
+      compress: {
+        drop_console: false,
+        drop_debugger: true,
+      },
+      mangle: {
+        safari10: true,
+      },
+    },
+    rollupOptions: {
+      output: {
+        format: 'es',
+        inlineDynamicImports: false,
+      },
+    },
+  },
+});

package/vite.config.ts

@@ -9,11 +9,13 @@ import { frontmatterGenerator } from './src/plugins/frontmatter-generator';
 import { frontmatterDevServer } from './src/plugins/frontmatter-dev-server';
 import { docsAssetsPlugin } from './src/plugins/docs-assets';
 import { htmlMetadataInjector } from './src/plugins/html-metadata-injector';
+import { htmlFilesMiddleware } from './src/plugins/html-files-middleware';
 import { getMdxConfig } from './src/config/mdx';
 
 export default defineConfig(({ command }) => ({
   plugins: [
     // SINGLE SOURCE OF TRUTH: All MDX preprocessing happens in src/mdx/processor.ts
+    htmlFilesMiddleware(), // Must be first to intercept HTML file requests
     unifiedMdxPreprocessor(),
     preact(),
     mdx(getMdxConfig(command === 'serve')),

package/.dockerignore

@@ -1,4 +0,0 @@
-.git
-*Dockerfile*
-node_modules
-k8s/Dockerfile

package/CLAUDE.md

@@ -1,178 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Communication Style
-- Maintain a professional, neutral tone in all communications
-- Use exclamation points sparingly and only when genuinely necessary
-- Approach problems with the measured perspective of an experienced software engineer
-- Keep a level head when discussing technical challenges and solutions
-- Focus on clear, factual explanations without unnecessary enthusiasm
-
-## Development requirements
-To develop Dory, follow the below requirements every time you do a task:
-1. Clean code is paramount—make sure it is easy to understand and follow
-2. Do not overengineer if you can help it—only add what is required.
-3. Do not remove or modify existing functionally UNLESS you have to and UNLESS you can justify it.
-4. Do not change existing variable names UNLESS absolutely necessary.
-5. Do not leave unused code lying around.
-6. Ask as many questions as you have to in order to understand your task.
-7. You MUST use multiple subagents wherever possible to help you accomplish your task faster.
-
-## Project Overview
-
-Dory is a lightweight static site generator for technical documentation, published as `@clidey/dory` on npm. It uses Preact, Vite, TypeScript, and Tailwind CSS.
-
-## Essential Commands
-
-```bash
-# Install dependencies
-pnpm install
-
-# Development server with hot reload
-pnpm run dev
-
-# Build the project (includes TypeScript checking)
-pnpm run build
-
-# Preview built site
-pnpm run preview
-
-# Publish to npm
-pnpm run publish
-
-# CLI commands (after build)
-node bin/dory.js build    # Build documentation site
-node bin/dory.js preview  # Serve built site
-```
-
-## High-Level Architecture
-
-### Core Technologies
-- **Frontend**: Preact (React-compatible)
-- **Build**: Vite with custom plugins
-- **Styling**: Tailwind CSS v4 + SCSS
-- **Content**: MDX (Markdown + JSX)
-- **Language**: TypeScript (strict mode)
-
-### Key Directories
-- `bin/` - CLI tool implementation
-- `src/components/` - UI components (Header, Footer, Search, etc.)
-- `src/mdx/` - MDX-specific components (Code, Tabs, Mermaid)
-- `src/plugins/` - Custom Vite plugins for LLM support
-- `docs/` - Documentation content (MDX files)
-
-### Important Files
-- `dory.json` - Site configuration (navigation, branding)
-- `vite.config.ts` - Build configuration with custom plugins
-- `src/main.tsx` - Application entry point
-- `src/store.ts` - Global state management
-
-### Custom Vite Plugins
-1. **llm-txt-generator**: Generates `llms.txt` files for AI consumption
-2. **llm-txt-dev-server**: Serves LLM-friendly content in development
-3. **remarkSafeVars**: Sanitizes MDX content for security
-
-### Development Patterns
-- Functional components with hooks
-- MDX Provider pattern for content rendering
-- Custom store for state management (dark mode, search)
-- Tailwind utilities for styling
-- No test framework currently configured
-
-### Key Features to Maintain
-- MDX support with custom components
-- Client-side search with FlexSearch
-- API Playground for OpenAPI specs
-- Mermaid diagram rendering
-- LaTeX math with KaTeX
-- Dark mode toggle
-- Responsive navigation
-
-When making changes:
-- Ensure TypeScript strict mode compliance
-- Follow existing component patterns in `src/components/`
-- Update `dory.json` for navigation changes
-- Test both light and dark modes
-- Verify MDX content renders correctly
-
-## Common Command Guidelines
-
-### Git Commands
-```bash
-# Check current status before making changes
-git status
-
-# View uncommitted changes
-git diff
-git diff --staged  # for staged changes
-
-# Stage and commit changes
-git add -A  # Stage all changes
-git commit -m "feat(component): add new feature"  # Use conventional commits
-
-# Branch operations
-git checkout -b feature/new-feature  # Create and switch to new branch
-git push -u origin feature/new-feature  # Push new branch to remote
-
-# View recent commits
-git log --oneline -10  # Last 10 commits
-```
-
-### npm/pnpm Commands
-```bash
-# Always use pnpm in this project (not npm or yarn)
-pnpm install  # Install dependencies
-pnpm add <package>  # Add new dependency
-pnpm add -D <package>  # Add dev dependency
-pnpm remove <package>  # Remove dependency
-
-# Check for outdated packages
-pnpm outdated
-
-# Run scripts from package.json
-pnpm run <script-name>
-```
-
-### Bash/Shell Commands
-```bash
-# Navigate directories
-cd src/components  # Change to components directory
-pwd  # Show current directory
-
-# File operations
-ls -la  # List all files with details
-mkdir -p src/new-feature  # Create directories recursively
-rm -rf dist  # Remove build directory (be careful!)
-
-# Search and find
-grep -r "searchTerm" src/  # Search in source files
-find . -name "*.tsx" -type f  # Find all TSX files
-
-# Process management
-lsof -i :5173  # Check what's using the dev server port
-kill -9 <PID>  # Force kill a process if needed
-```
-
-### Development Workflow Commands
-```bash
-# Start fresh development session
-git pull origin main
-pnpm install
-pnpm run dev
-
-# Before committing
-pnpm run build  # Ensure build passes
-git status  # Review changes
-git diff  # Check modifications
-
-# After making changes
-git add -A
-git commit -m "type(scope): description"
-git push
-
-# Publishing new version
-pnpm version patch/minor/major
-pnpm run build
-pnpm run publish
-```