@clidey/dory 0.34.1 → 0.35.0

package/src/plugins/docs-assets.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { cpSync, existsSync, readdirSync, statSync, mkdirSync } from 'fs';
+import { cpSync, existsSync, readdirSync, statSync } from 'fs';
 import { resolve, extname } from 'path';
 
 /**
@@ -31,7 +31,6 @@ export function docsAssetsPlugin(): Plugin {
       const skipPatterns = new Set([
         'dory.json',
         'node_modules',
-        'dist',
         '.DS_Store',
       ]);
 
@@ -57,10 +56,6 @@ export function docsAssetsPlugin(): Plugin {
             const stats = statSync(srcPath);
 
             if (stats.isDirectory()) {
-              // Create destination directory if it doesn't exist
-              if (!existsSync(destPath)) {
-                mkdirSync(destPath, { recursive: true });
-              }
               // Recursively copy directories
               copyAssets(srcPath, destPath, itemRelativePath);
             } else if (stats.isFile()) {

package/src/plugins/frontmatter-dev-server.ts

@@ -6,7 +6,14 @@ import path from 'path';
 function getNavigationOrder(docsDir: string): string[] {
   const doryJsonPath = path.join(docsDir, 'dory.json');
   if (!fs.existsSync(doryJsonPath)) return [];
-  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  let doryJson;
+  try {
+    doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  } catch (error) {
+    const detail = error instanceof SyntaxError ? error.message : String(error);
+    console.error(`Failed to parse ${doryJsonPath}: ${detail}`);
+    return [];
+  }
   const order: string[] = [];
 
   function walkPages(pages: any[]) {

package/src/plugins/frontmatter-generator.ts

@@ -11,7 +11,14 @@ interface FrontmatterGeneratorOptions {
 function getNavigationOrder(docsDir: string): string[] {
   const doryJsonPath = path.join(docsDir, 'dory.json');
   if (!fs.existsSync(doryJsonPath)) return [];
-  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  let doryJson;
+  try {
+    doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  } catch (error) {
+    const detail = error instanceof SyntaxError ? error.message : String(error);
+    console.error(`Failed to parse ${doryJsonPath}: ${detail}`);
+    return [];
+  }
   const order: string[] = [];
 
   function walkPages(pages: any[]) {
@@ -109,13 +116,12 @@ function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
 
     const filePath = mdxFilesMap[fileKey];
     const rawContent = fs.readFileSync(filePath, 'utf-8');
-    const { data, content } = parseFrontmatter(rawContent);
+    const { data } = parseFrontmatter(rawContent);
     const pathname = pathFromFilename(filePath, docsDir);
 
     frontmatterArray.push({
       ...data,
-      path: pathname,
-      content: content.trim()
+      path: pathname
     });
   }
 
@@ -124,13 +130,12 @@ function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
   for (const fileKey of extraKeys) {
     const filePath = mdxFilesMap[fileKey];
     const rawContent = fs.readFileSync(filePath, 'utf-8');
-    const { data, content } = parseFrontmatter(rawContent);
+    const { data } = parseFrontmatter(rawContent);
     const pathname = pathFromFilename(filePath, docsDir);
 
     frontmatterArray.push({
       ...data,
-      path: pathname,
-      content: content.trim()
+      path: pathname
     });
   }
 

package/src/plugins/llm-txt-dev-server.ts

@@ -6,7 +6,14 @@ import path from 'path';
 function getNavigationOrder(docsDir: string): string[] {
   const doryJsonPath = path.join(docsDir, 'dory.json');
   if (!fs.existsSync(doryJsonPath)) return [];
-  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  let doryJson;
+  try {
+    doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  } catch (error) {
+    const detail = error instanceof SyntaxError ? error.message : String(error);
+    console.error(`Failed to parse ${doryJsonPath}: ${detail}`);
+    return [];
+  }
   const order: string[] = [];
 
   function walkPages(pages: any[]) {

package/src/plugins/llm-txt-generator.ts

@@ -11,7 +11,14 @@ interface LlmTxtGeneratorOptions {
 function getNavigationOrder(docsDir: string): string[] {
   const doryJsonPath = path.join(docsDir, 'dory.json');
   if (!fs.existsSync(doryJsonPath)) return [];
-  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  let doryJson;
+  try {
+    doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  } catch (error) {
+    const detail = error instanceof SyntaxError ? error.message : String(error);
+    console.error(`Failed to parse ${doryJsonPath}: ${detail}`);
+    return [];
+  }
   const order: string[] = [];
 
   function walkPages(pages: any[]) {

package/src/plugins/prerender.ts

@@ -0,0 +1,119 @@
+import type { Plugin, ResolvedConfig } from 'vite';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Generates per-route HTML files with page-specific meta tags at build time.
+ * This is NOT full SSR — the Preact app still hydrates client-side.
+ * It provides correct <title>, <meta>, canonical, and JSON-LD per route
+ * so crawlers see unique, meaningful HTML for each documentation page.
+ */
+export function prerender(): Plugin {
+  let config: ResolvedConfig;
+
+  return {
+    name: 'prerender',
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+
+    closeBundle() {
+      const outDir = config.build.outDir;
+      const frontmatterPath = resolve(outDir, 'frontmatter.json');
+      const indexHtmlPath = resolve(outDir, 'index.html');
+
+      if (!existsSync(frontmatterPath) || !existsSync(indexHtmlPath)) {
+        console.warn('prerender: frontmatter.json or index.html not found, skipping');
+        return;
+      }
+
+      try {
+        const frontmatter: Array<Record<string, any>> = JSON.parse(readFileSync(frontmatterPath, 'utf-8'));
+        const baseHtml = readFileSync(indexHtmlPath, 'utf-8');
+
+        // Read dory.json for site-level config
+        const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
+        let siteConfig: Record<string, any> = {};
+        if (existsSync(doryJsonPath)) {
+          siteConfig = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
+        }
+
+        const baseUrl = siteConfig.url || '';
+        const siteName = siteConfig.name || 'Documentation';
+        let count = 0;
+
+        for (const page of frontmatter) {
+          const routePath = page.path;
+          if (!routePath || routePath === '/') continue;
+
+          const title = page.title || siteName;
+          const description = page.description || `${siteName} - ${title}`;
+          const fullUrl = `${baseUrl}${routePath}`;
+
+          let html = baseHtml;
+
+          // Replace title
+          html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(title)}</title>`);
+
+          // Replace meta description
+          html = html.replace(
+            /<meta name="description" content=".*?" \/>/,
+            `<meta name="description" content="${escapeAttr(description)}" />`
+          );
+
+          // Replace OG tags
+          html = html.replace(
+            /<meta property="og:title" content=".*?" \/>/,
+            `<meta property="og:title" content="${escapeAttr(title)}" />`
+          );
+          html = html.replace(
+            /<meta property="og:description" content=".*?" \/>/,
+            `<meta property="og:description" content="${escapeAttr(description)}" />`
+          );
+          if (fullUrl) {
+            html = html.replace(
+              /<meta property="og:url" content=".*?" \/>/,
+              `<meta property="og:url" content="${escapeAttr(fullUrl)}" />`
+            );
+          }
+
+          // Replace Twitter tags
+          html = html.replace(
+            /<meta name="twitter:title" content=".*?" \/>/,
+            `<meta name="twitter:title" content="${escapeAttr(title)}" />`
+          );
+          html = html.replace(
+            /<meta name="twitter:description" content=".*?" \/>/,
+            `<meta name="twitter:description" content="${escapeAttr(description)}" />`
+          );
+
+          // Add canonical link
+          if (!html.includes('rel="canonical"')) {
+            html = html.replace(
+              '</head>',
+              `  <link rel="canonical" href="${escapeAttr(fullUrl)}" />\n  </head>`
+            );
+          }
+
+          // Write to route directory
+          const routeDir = resolve(outDir, routePath.replace(/^\//, ''));
+          mkdirSync(routeDir, { recursive: true });
+          writeFileSync(resolve(routeDir, 'index.html'), html, 'utf-8');
+          count++;
+        }
+
+        console.log(`✅ Prerendered ${count} routes with page-specific meta tags`);
+      } catch (error) {
+        console.error('prerender failed:', error);
+      }
+    }
+  };
+}
+
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function escapeAttr(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/src/plugins/robots-generator.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vite';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Generates robots.txt with a sitemap reference at build time.
+ */
+export function robotsGenerator(): Plugin {
+  return {
+    name: 'robots-generator',
+    generateBundle() {
+      const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
+
+      let sitemapLine = '';
+      if (existsSync(doryJsonPath)) {
+        try {
+          const config = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
+          if (config.url) {
+            sitemapLine = `\nSitemap: ${config.url}/sitemap.xml\n`;
+          }
+        } catch {
+          // Non-critical, continue without sitemap reference
+        }
+      }
+
+      const robots = `User-agent: *\nAllow: /\n${sitemapLine}`;
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'robots.txt',
+        source: robots
+      });
+
+      console.log('✅ Generated robots.txt');
+    }
+  };
+}

package/src/plugins/sitemap-generator.ts

@@ -0,0 +1,73 @@
+import type { Plugin } from 'vite';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Generates sitemap.xml from dory.json navigation structure at build time.
+ * Uses the `url` field from dory.json as the base URL.
+ */
+export function sitemapGenerator(): Plugin {
+  return {
+    name: 'sitemap-generator',
+    generateBundle() {
+      const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
+      if (!existsSync(doryJsonPath)) {
+        console.warn('sitemap-generator: dory.json not found, skipping');
+        return;
+      }
+
+      try {
+        const config = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
+        const baseUrl = config.url || '';
+
+        // Extract all routes from navigation
+        const routes: string[] = [];
+        function walkPages(pages: any[]) {
+          for (const page of pages) {
+            if (typeof page === 'string') {
+              routes.push(`/${page}`);
+            } else if (typeof page === 'object' && page.pages) {
+              walkPages(page.pages);
+            }
+          }
+        }
+
+        if (config.navigation?.tabs) {
+          for (const tab of config.navigation.tabs) {
+            if (tab.groups) {
+              for (const group of tab.groups) {
+                if (group.pages) {
+                  walkPages(group.pages);
+                }
+              }
+            }
+          }
+        }
+
+        const now = new Date().toISOString().split('T')[0];
+        let sitemap = '<?xml version="1.0" encoding="UTF-8"?>\n';
+        sitemap += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+
+        for (const route of routes) {
+          sitemap += '  <url>\n';
+          sitemap += `    <loc>${baseUrl}${route}</loc>\n`;
+          sitemap += `    <lastmod>${now}</lastmod>\n`;
+          sitemap += '  </url>\n';
+        }
+
+        sitemap += '</urlset>';
+
+        this.emitFile({
+          type: 'asset',
+          fileName: 'sitemap.xml',
+          source: sitemap
+        });
+
+        console.log(`✅ Generated sitemap.xml with ${routes.length} URLs`);
+      } catch (error) {
+        const detail = error instanceof SyntaxError ? error.message : String(error);
+        console.error(`Failed to generate sitemap: ${detail}`);
+      }
+    }
+  };
+}

package/src/types/config.ts

@@ -78,12 +78,21 @@ export interface DoryEmbedConfig {
   };
 }
 
+export interface DoryAnalytics {
+  posthog?: {
+    token: string;
+    apiHost?: string;
+  };
+}
+
 export interface DoryConfig {
   name: string;
   favicon: string;
+  url?: string;
   colors?: DoryColors;
   fonts?: DoryFonts;
   navigation: DoryNavigation;
   logo: DoryLogo;
   embed?: DoryEmbedConfig;
+  analytics?: DoryAnalytics;
 }

package/src/ui/header.tsx

@@ -36,12 +36,7 @@ export function Header({ className }: { className?: string }) {
   const isEmbedded = useIsEmbedded();
 
   const { light, dark } = useMemo(() => {
-    // Remove leading ./ from paths to avoid /./path issues
-    const normalizePath = (path: string) => path.replace(/^\.\//, '');
-    return {
-      light: normalizePath(config.logo.light),
-      dark: normalizePath(config.logo.dark)
-    };
+    return { light: config.logo.light, dark: config.logo.dark };
   }, []);
 
   useEffect(() => {
@@ -68,8 +63,8 @@ export function Header({ className }: { className?: string }) {
     >
       <div className="relative flex justify-between gap-6 sm:gap-8 md:grow items-center w-full px-4">
         <div className="flex items-center grow gap-2">
-          <img src={`${import.meta.env.BASE_URL}${light}`} alt="logo" className="w-8 hidden dark:block" />
-          <img src={`${import.meta.env.BASE_URL}${dark}`} alt="logo" className="w-8 block dark:hidden" />
+          <img src={`/${light}`} alt="logo" className="w-8 hidden dark:block" />
+          <img src={`/${dark}`} alt="logo" className="w-8 block dark:hidden" />
           <h1 className="text-base lg:text-2xl font-bold">{config.name}</h1>
         </div>
         <nav className="hidden md:block">

package/src/ui/layout.tsx

@@ -13,6 +13,7 @@ import Dropdown from '../components/dropdown';
 import { useNotification } from '../components/notification';
 import { SparkleIcon } from 'lucide-react';
 import { useIsEmbedded } from '../components/hooks';
+import { ErrorBoundary } from '../components/error-boundary';
 import { cn } from '@clidey/ux';
 
 interface LayoutProps {
@@ -140,6 +141,52 @@ export default function Layout({ children }: LayoutProps) {
     if (ogUrl) {
       ogUrl.setAttribute('content', window.location.href);
     }
+
+    // Add/update canonical link
+    let canonical = document.querySelector('link[rel="canonical"]') as HTMLLinkElement | null;
+    if (!canonical) {
+      canonical = document.createElement('link');
+      canonical.setAttribute('rel', 'canonical');
+      document.head.appendChild(canonical);
+    }
+    canonical.setAttribute('href', `${window.location.origin}${window.location.pathname}`);
+
+    // Add/update JSON-LD structured data
+    const structuredData = {
+      '@context': 'https://schema.org',
+      '@graph': [
+        {
+          '@type': 'Article',
+          'headline': page?.title || document.title,
+          'description': page?.description || '',
+        },
+        {
+          '@type': 'BreadcrumbList',
+          'itemListElement': [
+            {
+              '@type': 'ListItem',
+              'position': 1,
+              'name': 'Home',
+              'item': window.location.origin
+            },
+            ...(page?.title ? [{
+              '@type': 'ListItem',
+              'position': 2,
+              'name': page.title,
+              'item': window.location.href
+            }] : [])
+          ]
+        }
+      ]
+    };
+
+    let ldScript = document.querySelector('script[type="application/ld+json"]');
+    if (!ldScript) {
+      ldScript = document.createElement('script');
+      ldScript.setAttribute('type', 'application/ld+json');
+      document.head.appendChild(ldScript);
+    }
+    ldScript.textContent = JSON.stringify(structuredData);
   }, [page]);
 
   const tab = useMemo(() => {
@@ -217,11 +264,22 @@ export default function Layout({ children }: LayoutProps) {
                 }
               </div>
               <div className="flex-1 min-h-[calc(100vh-2rem)]">
-                {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} />
-                 : children}
+                <ErrorBoundary fallback={(error) => (
+                  <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
+                    <p className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
+                      This page failed to render
+                    </p>
+                    <pre className="text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md overflow-auto">
+                      {error.message}
+                    </pre>
+                  </div>
+                )}>
+                  {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} />
+                   : children}
+                </ErrorBoundary>
               </div>
               <PrevNextLinks />
             </article>

package/vite.config.embed-widget.ts

@@ -3,14 +3,11 @@ import { resolve } from 'path';
 
 export default defineConfig({
   build: {
-    rollupOptions: {
-      input: resolve(__dirname, 'src/embed/widget-iframe.ts'),
-      output: {
-        entryFileNames: 'embed-widget.js',
-        format: 'iife',
-        name: '__DoryWidget__',
-        inlineDynamicImports: true,
-      },
+    lib: {
+      entry: resolve(__dirname, 'src/embed/widget-iframe.ts'),
+      name: '__DoryWidget__',
+      fileName: () => 'embed-widget.js',
+      formats: ['es'],
     },
     outDir: 'dist',
     emptyOutDir: false,
@@ -24,5 +21,11 @@ export default defineConfig({
         safari10: true,
       },
     },
+    rollupOptions: {
+      output: {
+        format: 'es',
+        inlineDynamicImports: false,
+      },
+    },
   },
 });

package/vite.config.ts

@@ -10,11 +10,14 @@ 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 { manifestGenerator } from './src/plugins/manifest-generator';
+import { analyticsInjector } from './src/plugins/analytics-injector';
+import { cspGenerator } from './src/plugins/csp-generator';
+import { sitemapGenerator } from './src/plugins/sitemap-generator';
+import { robotsGenerator } from './src/plugins/robots-generator';
+import { prerender } from './src/plugins/prerender';
 import { getMdxConfig } from './src/config/mdx';
 
 export default defineConfig(({ command }) => ({
-  base: process.env.VITE_BASE || '/',
   plugins: [
     // SINGLE SOURCE OF TRUTH: All MDX preprocessing happens in src/mdx/processor.ts
     htmlFilesMiddleware(), // Must be first to intercept HTML file requests
@@ -26,9 +29,13 @@ export default defineConfig(({ command }) => ({
     llmTxtDevServer(),
     frontmatterGenerator(),
     frontmatterDevServer(),
-    manifestGenerator(),
     docsAssetsPlugin(),
     htmlMetadataInjector(),
+    analyticsInjector(),
+    cspGenerator(),
+    sitemapGenerator(),
+    robotsGenerator(),
+    prerender(),
   ],
   resolve: {
     alias: {
@@ -37,11 +44,23 @@ export default defineConfig(({ command }) => ({
     }
   },
   publicDir: false, // Don't use a public directory since we need to import from docs
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'vendor-preact': ['preact', 'preact/compat', 'preact/hooks'],
+          'vendor-ui': ['@clidey/ux', '@headlessui/react'],
+          'vendor-icons': ['lucide-react'],
+          'katex': ['katex'],
+          'flexsearch': ['flexsearch'],
+        }
+      }
+    }
+  },
   server: {
     allowedHosts: true,
     port: 3000,
     strictPort: false,
-    cors: true,
   },
   json: {
     stringify: false

package/bin/dist/dory.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=dory.d.ts.map

package/bin/dist/dory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dory.d.ts","sourceRoot":"","sources":["../dory.ts"],"names":[],"mappings":""}