@clidey/dory 0.41.0 → 0.43.0

package/index.html

@@ -26,12 +26,13 @@
     <meta name="twitter:title" content="Docucod: Generate and Maintain Documentation With No Work" />
     <meta name="twitter:description" content="Docucod auto-generates and maintains up-to-date documentation from your codebase so your team can move fast, onboard quickly, and stay focused on building." />
     <meta name="twitter:image" content="./docs/favicon.svg" />
-    <meta name="twitter:site" content="@ClideyOfficial" />
-    <meta name="twitter:creator" content="@ClideyOfficial" />
+    <meta name="twitter:site" content="" />
+    <meta name="twitter:creator" content="" />
 
+    <link rel="canonical" href="" />
     <link rel="apple-touch-icon" href="./docs/favicon.svg" />
     <link rel="manifest" href="/manifest.json" />
-    
+
     <title>Docucod - Instantly Generate and Maintain Your Documentation</title>
 
     <link rel="preconnect" href="https://fonts.googleapis.com" />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "0.41.0",
+  "version": "0.43.0",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [
@@ -17,8 +17,10 @@
   "files": [
     "bin/dist",
     "src",
+    "scripts",
     "index.html",
     "vite.config.ts",
+    "vite.config.ssr.ts",
     "vite.config.embed-loader.ts",
     "vite.config.embed-widget.ts"
   ],
@@ -34,9 +36,9 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "npm run build:cli && tsc -b && vite build",
+    "build": "npm run build:cli && tsc -b && npm run build:docs",
     "build:cli": "tsc -p tsconfig.bin.json",
-    "build:docs": "vite build",
+    "build:docs": "vite build && vite build --config vite.config.ssr.ts && node scripts/render-routes.mjs",
     "build:embed": "npm run build:embed:loader && npm run build:embed:widget",
     "build:embed:loader": "vite build -c vite.config.embed-loader.ts",
     "build:embed:widget": "vite build -c vite.config.embed-widget.ts",
@@ -69,6 +71,7 @@
     "mermaid": "11.12.2",
     "motion": "12.34.0",
     "preact": "10.28.3",
+    "preact-render-to-string": "6.6.5",
     "prism-react-renderer": "2.4.1",
     "react-highlight-words": "0.21.0",
     "remark-gfm": "4.0.1",

package/scripts/generate-frontmatter-json.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Read dory.json to get navigation order (flat list, in order)
+function getNavigationOrder(docsDir) {
+  const doryJsonPath = path.join(docsDir, 'dory.json');
+  if (!fs.existsSync(doryJsonPath)) return [];
+  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  const order = [];
+
+  function walkPages(pages) {
+    for (const page of pages) {
+      if (typeof page === 'string') {
+        order.push(page);
+      } else if (typeof page === 'object' && page.pages) {
+        walkPages(page.pages);
+      }
+    }
+  }
+
+  if (doryJson.navigation && Array.isArray(doryJson.navigation.tabs)) {
+    for (const tab of doryJson.navigation.tabs) {
+      if (tab.groups && Array.isArray(tab.groups)) {
+        for (const group of tab.groups) {
+          if (group.pages && Array.isArray(group.pages)) {
+            walkPages(group.pages);
+          }
+        }
+      }
+    }
+  }
+  return order;
+}
+
+// Function to parse frontmatter from MDX content
+function parseFrontmatter(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return { data: {}, content };
+  
+  const frontmatter = frontmatterMatch[1];
+  const data = {};
+  
+  frontmatter.split('\n').forEach(line => {
+    const [key, ...valueParts] = line.split(':');
+    if (key && valueParts.length) {
+      const value = valueParts.join(':').trim();
+      data[key.trim()] = value.replace(/^["']|["']$/g, '');
+    }
+  });
+
+  return { data, content: content.slice(frontmatterMatch[0].length) };
+}
+
+// Convert filename to path format used by the store
+function pathFromFilename(filename, docsDir) {
+  return filename
+    .replace(docsDir, '')
+    .replace(/\/?index\.mdx$/, '/')
+    .replace(/\.mdx$/, '')
+    .replace(/\\/g, '/')
+    .toLowerCase();
+}
+
+// Function to recursively find all MDX files and map by relative path (without .mdx)
+function findMdxFilesMap(dir, baseDir) {
+  const files = {};
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      Object.assign(files, findMdxFilesMap(fullPath, baseDir));
+    } else if (item.isFile() && item.name.endsWith('.mdx')) {
+      // Key: relative path without .mdx, with forward slashes
+      let rel = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+      if (rel.endsWith('.mdx')) rel = rel.slice(0, -4);
+      files[rel] = fullPath;
+    }
+  }
+
+  return files;
+}
+
+// Main function to generate frontmatter JSON
+async function generateFrontmatterJson() {
+  const docsDir = path.join(__dirname, '..', 'docs');
+  const outputDir = path.join(__dirname, '..', 'dist');
+  
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  const navOrder = getNavigationOrder(docsDir);
+  const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+  const usedKeys = new Set();
+  const frontmatterArray = [];
+
+  // Process files in navigation order first
+  for (const navKey of navOrder) {
+    // Try both with and without "index"
+    let fileKey = navKey;
+    if (mdxFilesMap[fileKey]) {
+      usedKeys.add(fileKey);
+    } else if (mdxFilesMap[`${fileKey}/index`]) {
+      fileKey = `${fileKey}/index`;
+      usedKeys.add(fileKey);
+    } else {
+      continue;
+    }
+
+    const filePath = mdxFilesMap[fileKey];
+    const rawContent = fs.readFileSync(filePath, 'utf-8');
+    const { data } = parseFrontmatter(rawContent);
+    const pathname = pathFromFilename(filePath, docsDir);
+
+    frontmatterArray.push({
+      ...data,
+      path: pathname
+    });
+  }
+
+  // Process any extra files not in navigation order, sorted
+  const extraKeys = Object.keys(mdxFilesMap).filter(k => !usedKeys.has(k)).sort();
+  for (const fileKey of extraKeys) {
+    const filePath = mdxFilesMap[fileKey];
+    const rawContent = fs.readFileSync(filePath, 'utf-8');
+    const { data } = parseFrontmatter(rawContent);
+    const pathname = pathFromFilename(filePath, docsDir);
+
+    frontmatterArray.push({
+      ...data,
+      path: pathname
+    });
+  }
+
+  // Write to output file
+  const jsonContent = JSON.stringify(frontmatterArray, null, 2);
+  const outputPath = path.join(outputDir, 'frontmatter.json');
+  fs.writeFileSync(outputPath, jsonContent);
+  
+  console.log(`✅ Generated frontmatter JSON file: ${outputPath}`);
+  console.log(`📄 Processed ${frontmatterArray.length} MDX files`);
+  console.log(`📝 Total JSON size: ${jsonContent.length} characters`);
+}
+
+// Run the script
+generateFrontmatterJson().catch(console.error);

package/scripts/generate-llm-txt.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Function to parse frontmatter from MDX content
+function parseFrontmatter(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!frontmatterMatch) return { data: {}, content };
+  
+  const frontmatter = frontmatterMatch[1];
+  const data = {};
+  
+  frontmatter.split('\n').forEach(line => {
+    const [key, ...valueParts] = line.split(':');
+    if (key && valueParts.length) {
+      const value = valueParts.join(':').trim();
+      data[key.trim()] = value.replace(/^["']|["']$/g, '');
+    }
+  });
+
+  return { data, content: content.slice(frontmatterMatch[0].length) };
+}
+
+// Function to recursively find all MDX files
+function findMdxFiles(dir) {
+  const files = [];
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+  
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      files.push(...findMdxFiles(fullPath));
+    } else if (item.isFile() && item.name.endsWith('.mdx')) {
+      files.push(fullPath);
+    }
+  }
+  
+  return files;
+}
+
+// Function to clean MDX content for LLM consumption
+function cleanMdxContent(content) {
+  // Remove JSX components but keep their content
+  let cleaned = content
+    // Remove JSX opening/closing tags but keep content
+    .replace(/<(\w+)([^>]*?)>/g, '')
+    .replace(/<\/\w+>/g, '')
+    // Remove code block language specifiers
+    .replace(/```(\w+)/g, '```')
+    // Remove HTML comments
+    .replace(/<!--[\s\S]*?-->/g, '')
+    // Remove excessive whitespace
+    .replace(/\n\s*\n\s*\n/g, '\n\n')
+    // Remove leading/trailing whitespace
+    .trim();
+    
+  return cleaned;
+}
+
+// Main function to generate LLM text
+async function generateLlmTxt() {
+  const docsDir = path.join(__dirname, '..', 'docs');
+  const outputDir = path.join(__dirname, '..', 'dist');
+  
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  const mdxFiles = findMdxFiles(docsDir);
+  let aggregatedContent = '';
+  
+  // Sort files for consistent output
+  mdxFiles.sort();
+  
+  for (const filePath of mdxFiles) {
+    const rawContent = fs.readFileSync(filePath, 'utf-8');
+    const { data, content } = parseFrontmatter(rawContent);
+    const cleanedContent = cleanMdxContent(content);
+    
+    // Add file header
+    const relativePath = path.relative(docsDir, filePath);
+    aggregatedContent += `\n# ${relativePath}\n`;
+    
+    // Add title if available
+    if (data.title) {
+      aggregatedContent += `## ${data.title}\n\n`;
+    }
+    
+    // Add description if available
+    if (data.description) {
+      aggregatedContent += `${data.description}\n\n`;
+    }
+    
+    // Add cleaned content
+    aggregatedContent += cleanedContent + '\n\n';
+    aggregatedContent += '---\n\n';
+  }
+  
+  // Write to output file
+  const outputPath = path.join(outputDir, 'llms.txt');
+  fs.writeFileSync(outputPath, aggregatedContent.trim());
+  
+  console.log(`✅ Generated LLM text file: ${outputPath}`);
+  console.log(`📄 Processed ${mdxFiles.length} MDX files`);
+  console.log(`📝 Total content size: ${aggregatedContent.length} characters`);
+}
+
+// Run the script
+generateLlmTxt().catch(console.error);

package/scripts/render-routes.mjs

@@ -0,0 +1,94 @@
+/**
+ * Post-build SSR rendering script.
+ * Reads the SSR bundle from dist-ssr/, renders each route to HTML,
+ * and injects the content into the prerendered HTML files in dist/.
+ */
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distDir = resolve(__dirname, '..', 'dist');
+const ssrDir = resolve(__dirname, '..', 'dist-ssr');
+
+// Check prerequisites
+const frontmatterPath = resolve(distDir, 'frontmatter.json');
+if (!existsSync(frontmatterPath)) {
+  console.warn('⚠️  frontmatter.json not found, skipping SSR rendering');
+  process.exit(0);
+}
+
+const ssrEntryPath = resolve(ssrDir, 'entry-server.js');
+if (!existsSync(ssrEntryPath)) {
+  console.warn('⚠️  SSR bundle not found, skipping SSR rendering');
+  process.exit(0);
+}
+
+// Import SSR bundle
+const { render } = await import(ssrEntryPath);
+const frontmatter = JSON.parse(readFileSync(frontmatterPath, 'utf-8'));
+
+let count = 0;
+let failed = 0;
+
+function injectSSR(htmlPath, ssrHtml) {
+  let html = readFileSync(htmlPath, 'utf-8');
+
+  html = html.replace(
+    '<div id="app"></div>',
+    `<div id="app">${ssrHtml}</div>`
+  );
+
+  html = html.replace(
+    '<noscript>You need to enable JavaScript to run this app.</noscript>',
+    '<noscript>JavaScript enhances this page with interactive features.</noscript>'
+  );
+
+  writeFileSync(htmlPath, html, 'utf-8');
+}
+
+// Render each route
+for (const page of frontmatter) {
+  const routePath = page.path;
+  if (!routePath || routePath === '/') continue;
+
+  const htmlPath = resolve(distDir, routePath.replace(/^\//, ''), 'index.html');
+  if (!existsSync(htmlPath)) continue;
+
+  try {
+    const ssrHtml = await render(routePath);
+    if (!ssrHtml) continue;
+
+    injectSSR(htmlPath, ssrHtml);
+    count++;
+  } catch (error) {
+    console.warn(`⚠️  SSR failed for ${routePath}: ${error.message}`);
+    failed++;
+  }
+}
+
+// Also render the root index.html with the first page's content
+try {
+  const rootHtmlPath = resolve(distDir, 'index.html');
+  if (existsSync(rootHtmlPath) && frontmatter.length > 0) {
+    const firstRoute = frontmatter[0].path;
+    if (firstRoute) {
+      const ssrHtml = await render(firstRoute);
+      if (ssrHtml) {
+        injectSSR(rootHtmlPath, ssrHtml);
+        count++;
+      }
+    }
+  }
+} catch (error) {
+  console.warn(`⚠️  SSR failed for root: ${error.message}`);
+}
+
+// Cleanup SSR build artifacts
+try {
+  rmSync(ssrDir, { recursive: true, force: true });
+} catch {
+  // Non-fatal: dist-ssr will be overwritten on next build
+}
+
+console.log(`✅ SSR rendered ${count} routes${failed > 0 ? ` (${failed} failed)` : ''}`);

package/src/components/hooks.tsx

@@ -2,18 +2,38 @@ import { useEffect, useState } from 'preact/hooks';
 import { useLocation } from 'wouter-preact';
 
 /**
- * Custom hook to get the current pathname
+ * Strips trailing slash from a pathname (except root "/").
+ */
+function normalizePathname(pathname: string): string {
+  if (pathname !== '/' && pathname.endsWith('/')) {
+    return pathname.slice(0, -1);
+  }
+  return pathname;
+}
+
+/**
+ * Custom hook to get the current pathname, normalized to strip trailing slashes.
  */
 export const usePathname = () => {
   const [pathname] = useLocation();
-  return pathname;
+  const normalized = normalizePathname(pathname);
+
+  useEffect(() => {
+    if (pathname !== normalized) {
+      window.history.replaceState(null, '', normalized + window.location.search + window.location.hash);
+    }
+  }, [pathname, normalized]);
+
+  return normalized;
 };
 
 /**
  * Custom hook to get the URL search params as a URLSearchParams instance
  */
 export const useSearchParams = () => {
-  const [searchParams, setSearchParams] = useState(new URLSearchParams(window.location.search));
+  const [searchParams, setSearchParams] = useState(
+    typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : new URLSearchParams()
+  );
 
   useEffect(() => {
     const handlePopState = () => {

package/src/entry-server.tsx

@@ -0,0 +1,106 @@
+import {renderToString} from 'preact-render-to-string';
+import {Router} from 'wouter-preact';
+import {MDXProvider} from '@mdx-js/preact';
+import * as mdxComponents from './mdx/mdx';
+
+function pathFromFilename(filename: string): string {
+  return filename
+    .replace(/^.*?docs/, '')
+    .replace(/\/?index\.mdx$/, '/')
+    .replace(/\.mdx$/, '')
+    .toLowerCase();
+}
+
+const pages = import.meta.glob('../docs/**/*.mdx');
+const allPages = Object.fromEntries(
+  Object.entries(pages).map(([path, loader]) => [pathFromFilename(path), loader])
+);
+
+// SSR-safe Pre: renders code blocks without syntax highlighting.
+// The client-side Fence component uses useTheme() from @clidey/ux which
+// requires ThemeProvider (localStorage access). Plain pre/code is sufficient
+// for crawlers — syntax highlighting is a visual enhancement.
+function SSRPre(props: any) {
+  const child = props.children?.props;
+  const className = child?.className || '';
+  const code = child?.children || '';
+  return (
+    <pre class="overflow-x-auto p-4 text-xs">
+      <code class={className}>{code}</code>
+    </pre>
+  );
+}
+
+// SSR-safe Latex: renders the raw expression as text.
+// The client-side Latex component lazy-loads KaTeX in useEffect.
+function SSRLatex({ children }: { children: any }) {
+  return (
+    <div class="my-4">
+      <code>{children}</code>
+    </div>
+  );
+}
+
+// SSR-safe table: @clidey/ux's Table component renders a vaul Drawer
+// (Preview drawer) alongside every table. vaul's useScaleBackground
+// accesses document.body at render time, crashing in Node.js.
+function SSRTable(props: any) {
+  return (
+    <div class="overflow-x-auto rounded-lg my-8">
+      <table class="table-auto border-collapse min-w-full" {...props} />
+    </div>
+  );
+}
+function SSRTh(props: any) {
+  return <th class="px-4 py-2 text-left text-sm font-medium" {...props} />;
+}
+function SSRTd(props: any) {
+  return <td class="px-4 py-2 text-sm" {...props} />;
+}
+
+// SSR-safe placeholders for interactive components that use Suspense/lazy.
+// renderToString cannot handle Suspense boundaries — these components are
+// interactive-only anyway (playgrounds, diagrams) and not meaningful for crawlers.
+function SSRPlaceholder() {
+  return null;
+}
+
+const ssrComponents: Record<string, any> = {
+  ...mdxComponents,
+  pre: SSRPre,
+  Latex: SSRLatex,
+  table: SSRTable,
+  th: SSRTh,
+  td: SSRTd,
+  APIPlayground: SSRPlaceholder,
+  WebSocketPlayground: SSRPlaceholder,
+};
+
+export async function render(routePath: string): Promise<string> {
+  const loader = allPages[routePath];
+  if (!loader) return '';
+
+  try {
+    const module = await loader() as any;
+    const Content = module.default;
+
+    return renderToString(
+        <Router ssrPath={routePath}>
+          <MDXProvider components={ssrComponents}>
+            <div class="flex w-full flex-col">
+              <main class="flex grow max-w-full px-4 py-16 sm:px-6 lg:px-8">
+                <div class="min-w-0 w-full">
+                  <article class="h-full flex flex-1 flex-col">
+                    <Content/>
+                  </article>
+                </div>
+              </main>
+            </div>
+          </MDXProvider>
+        </Router>
+    );
+  } catch (error) {
+    console.warn(`SSR render failed for ${routePath}:`, error);
+    return '';
+  }
+}

package/src/mdx/fence.tsx

@@ -15,7 +15,7 @@ export function Fence({
   language: string
 }) {
   const { theme } = useTheme();
-  const isDark = theme === 'dark' || (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+  const isDark = theme === 'dark' || (theme === 'system' && typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches);
 
   if (language === 'mermaid') {
     return (

package/src/mdx/mdx.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'preact/hooks';
 import { lazy, Suspense } from 'preact/compat';
-import { usePathname } from 'wouter-preact/use-browser-location';
+import { usePathname } from '../components/hooks';
 import { completeFrontMatter } from '../components/store';
 import { Loading } from '../components/loading';
 

package/src/mdx/processor.ts

@@ -25,12 +25,28 @@ export async function preprocessMdxContent(
   error?: Error;
 }> {
   try {
+    // Step 0: Strip YAML frontmatter before any processing.
+    // Frontmatter is parsed separately by the frontmatter-generator plugin.
+    let processedContent = content;
+    const frontMatterMatch = processedContent.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (frontMatterMatch) {
+      processedContent = processedContent.slice(frontMatterMatch[0].length);
+    }
+
+    // Step 0b: Strip stray ```yaml metadata blocks that follow frontmatter.
+    // Some content generators produce a second YAML block (```yaml...---) after
+    // the frontmatter. This is a broken code fence (closed with --- instead of ```)
+    // that leaks metadata into the rendered page.
+    const yamlBlockMatch = processedContent.match(/^```yaml\n([\s\S]*?)\n---\n?/);
+    if (yamlBlockMatch) {
+      processedContent = processedContent.slice(yamlBlockMatch[0].length);
+    }
+
     // Step 1: Apply preprocessor (handles MDX tags, code blocks, etc.)
     const preprocessor = preprocessMdxTags();
-    let processedContent = content;
     
     if (preprocessor.transform) {
-      const result = preprocessor.transform(content, fileName);
+      const result = preprocessor.transform(processedContent, fileName);
       if (result && typeof result === 'object' && result.code) {
         processedContent = result.code;
       } else if (typeof result === 'string') {

package/src/plugins/html-metadata-injector.ts

@@ -3,14 +3,13 @@ import { readFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
 
 /**
- * Vite plugin that injects site metadata from dory.json into index.html
- * This provides proper defaults before JavaScript hydrates the page
+ * Vite plugin that injects site metadata from dory.json into index.html.
+ * Provides proper defaults before JavaScript hydrates the page.
  */
 export function htmlMetadataInjector(): Plugin {
   return {
     name: 'html-metadata-injector',
     transformIndexHtml(html) {
-      // Read dory.json configuration
       const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
 
       if (!existsSync(doryJsonPath)) {
@@ -24,7 +23,13 @@ export function htmlMetadataInjector(): Plugin {
         const defaultTitle = config.title || siteName;
         const defaultDescription = config.description || `${siteName} - Technical Documentation`;
         const siteUrl = config.url || '';
-        const siteImage = config.image || './docs/favicon.svg';
+        const twitterHandle = config.twitter || '';
+
+        // Resolve image to absolute URL
+        const rawImage = config.image || '';
+        const siteImage = rawImage && siteUrl && !rawImage.startsWith('http')
+          ? `${siteUrl}${rawImage.startsWith('/') ? '' : '/'}${rawImage}`
+          : rawImage;
 
         // Replace title
         html = html.replace(
@@ -38,31 +43,25 @@ export function htmlMetadataInjector(): Plugin {
           `<meta name="description" content="${defaultDescription}" />`
         );
 
-        // Replace Open Graph title
+        // Replace Open Graph tags
         html = html.replace(
           /<meta property="og:title" content=".*?" \/>/,
           `<meta property="og:title" content="${defaultTitle}" />`
         );
-
-        // Replace Open Graph description
         html = html.replace(
           /<meta property="og:description" content=".*?" \/>/,
           `<meta property="og:description" content="${defaultDescription}" />`
         );
-
-        // Replace Open Graph site name
         html = html.replace(
           /<meta property="og:site_name" content=".*?" \/>/,
           `<meta property="og:site_name" content="${siteName}" />`
         );
-
-        // Replace Open Graph image
-        html = html.replace(
-          /<meta property="og:image" content=".*?" \/>/,
-          `<meta property="og:image" content="${siteImage}" />`
-        );
-
-        // Replace Open Graph URL
+        if (siteImage) {
+          html = html.replace(
+            /<meta property="og:image" content=".*?" \/>/,
+            `<meta property="og:image" content="${siteImage}" />`
+          );
+        }
         if (siteUrl) {
           html = html.replace(
             /<meta property="og:url" content=".*?" \/>/,
@@ -70,24 +69,38 @@ export function htmlMetadataInjector(): Plugin {
           );
         }
 
-        // Replace Twitter title
+        // Replace Twitter tags
         html = html.replace(
           /<meta name="twitter:title" content=".*?" \/>/,
           `<meta name="twitter:title" content="${defaultTitle}" />`
         );
-
-        // Replace Twitter description
         html = html.replace(
           /<meta name="twitter:description" content=".*?" \/>/,
           `<meta name="twitter:description" content="${defaultDescription}" />`
         );
-
-        // Replace Twitter image
+        if (siteImage) {
+          html = html.replace(
+            /<meta name="twitter:image" content=".*?" \/>/,
+            `<meta name="twitter:image" content="${siteImage}" />`
+          );
+        }
+        html = html.replace(
+          /<meta name="twitter:site" content=".*?" \/>/,
+          `<meta name="twitter:site" content="${twitterHandle}" />`
+        );
         html = html.replace(
-          /<meta name="twitter:image" content=".*?" \/>/,
-          `<meta name="twitter:image" content="${siteImage}" />`
+          /<meta name="twitter:creator" content=".*?" \/>/,
+          `<meta name="twitter:creator" content="${twitterHandle}" />`
         );
 
+        // Set canonical URL for the base page
+        if (siteUrl) {
+          html = html.replace(
+            /<link rel="canonical" href=".*?" \/>/,
+            `<link rel="canonical" href="${siteUrl}" />`
+          );
+        }
+
         return html;
       } catch (error) {
         console.error('❌ Failed to parse dory.json for metadata injection:', error);

package/src/plugins/prerender.ts

@@ -3,10 +3,9 @@ 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.
+ * Generates per-route HTML files with page-specific meta tags and JSON-LD
+ * at build time. The SSR step (render-routes.mjs) later injects rendered
+ * content into these files.
  */
 export function prerender(): Plugin {
   let config: ResolvedConfig;
@@ -70,12 +69,10 @@ export function prerender(): Plugin {
             /<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)}" />`
-            );
-          }
+          html = html.replace(
+            /<meta property="og:url" content=".*?" \/>/,
+            `<meta property="og:url" content="${escapeAttr(fullUrl)}" />`
+          );
 
           // Replace Twitter tags
           html = html.replace(
@@ -87,14 +84,55 @@ export function prerender(): Plugin {
             `<meta name="twitter:description" content="${escapeAttr(description)}" />`
           );
 
-          // Add canonical link
-          if (!html.includes('rel="canonical"')) {
+          // Update canonical link (always replace, never skip)
+          html = html.replace(
+            /<link rel="canonical" href=".*?" \/>/,
+            `<link rel="canonical" href="${escapeAttr(fullUrl)}" />`
+          );
+
+          // Inject per-page robots directive if specified in frontmatter
+          if (page.robots) {
             html = html.replace(
               '</head>',
-              `  <link rel="canonical" href="${escapeAttr(fullUrl)}" />\n  </head>`
+              `  <meta name="robots" content="${escapeAttr(page.robots)}" />\n  </head>`
             );
           }
 
+          // Inject JSON-LD structured data
+          const jsonLd = JSON.stringify({
+            '@context': 'https://schema.org',
+            '@graph': [
+              {
+                '@type': 'Article',
+                'headline': title,
+                'description': description,
+                ...(fullUrl ? { 'url': fullUrl } : {}),
+              },
+              {
+                '@type': 'BreadcrumbList',
+                'itemListElement': [
+                  {
+                    '@type': 'ListItem',
+                    'position': 1,
+                    'name': 'Home',
+                    ...(baseUrl ? { 'item': baseUrl } : {}),
+                  },
+                  {
+                    '@type': 'ListItem',
+                    'position': 2,
+                    'name': title,
+                    ...(fullUrl ? { 'item': fullUrl } : {}),
+                  }
+                ]
+              }
+            ]
+          });
+
+          html = html.replace(
+            '</head>',
+            `  <script type="application/ld+json">${jsonLd}</script>\n  </head>`
+          );
+
           // Write to route directory
           const routeDir = resolve(outDir, routePath.replace(/^\//, ''));
           mkdirSync(routeDir, { recursive: true });

package/src/plugins/sitemap-generator.ts

@@ -1,16 +1,18 @@
 import type { Plugin } from 'vite';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, statSync } 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.
+ * Uses actual file modification times for lastmod and calculates priority
+ * based on route depth.
  */
 export function sitemapGenerator(): Plugin {
   return {
     name: 'sitemap-generator',
     generateBundle() {
-      const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
+      const docsDir = resolve(process.cwd(), 'docs');
+      const doryJsonPath = resolve(docsDir, 'dory.json');
       if (!existsSync(doryJsonPath)) {
         console.warn('sitemap-generator: dory.json not found, skipping');
         return;
@@ -25,7 +27,7 @@ export function sitemapGenerator(): Plugin {
         function walkPages(pages: any[]) {
           for (const page of pages) {
             if (typeof page === 'string') {
-              routes.push(`/${page}`);
+              routes.push(page);
             } else if (typeof page === 'object' && page.pages) {
               walkPages(page.pages);
             }
@@ -44,14 +46,26 @@ export function sitemapGenerator(): Plugin {
           }
         }
 
-        const now = new Date().toISOString().split('T')[0];
+        const fallbackDate = 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) {
+          // Get actual file modification time
+          const mdxPath = resolve(docsDir, `${route}.mdx`);
+          let lastmod = fallbackDate;
+          if (existsSync(mdxPath)) {
+            lastmod = statSync(mdxPath).mtime.toISOString().split('T')[0];
+          }
+
+          // Priority based on route depth: fewer segments = higher priority
+          const depth = route.split('/').length;
+          const priority = Math.max(0.3, 1.0 - (depth - 1) * 0.2).toFixed(1);
+
           sitemap += '  <url>\n';
-          sitemap += `    <loc>${baseUrl}${route}</loc>\n`;
-          sitemap += `    <lastmod>${now}</lastmod>\n`;
+          sitemap += `    <loc>${baseUrl}/${route}</loc>\n`;
+          sitemap += `    <lastmod>${lastmod}</lastmod>\n`;
+          sitemap += `    <priority>${priority}</priority>\n`;
           sitemap += '  </url>\n';
         }
 

package/src/plugins/unified-mdx-plugin.ts

@@ -27,7 +27,7 @@ export function unifiedMdxPreprocessor(): Plugin {
       // Return the preprocessed content
       // The actual MDX compilation will be handled by @mdx-js/rollup plugin
       return {
-        code: result.processedContent || code,
+        code: result.processedContent ?? code,
         map: null
       };
     }

package/src/types/config.ts

@@ -91,6 +91,7 @@ export interface DoryConfig {
   description?: string;
   image?: string;
   url?: string;
+  twitter?: string;
   favicon: string;
   colors?: DoryColors;
   fonts?: DoryFonts;

package/src/ui/header.tsx

@@ -1,7 +1,7 @@
 import classNames from 'classnames';
 import { useEffect, useMemo, useState } from 'preact/hooks';
 import { Link } from 'wouter-preact';
-import { usePathname } from 'wouter-preact/use-browser-location';
+import { usePathname } from '../components/hooks';
 import docsConfig from '../../docs/dory.json' with { type: 'json' };
 import type { DoryConfig } from '../types/config';
 import { MobileSearch, Search } from '../components/search';

package/src/ui/layout.tsx

@@ -1,8 +1,8 @@
 import type { ComponentChildren } from 'preact';
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
-import { useLocation } from 'wouter-preact';
 import { Navigation } from '../components/navigation';
 import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename, preloadFrontmatter, ALL_ASYNCAPI } from '../components/store';
+import { usePathname } from '../components/hooks';
 import { OpenAPI } from '../mdx/open-api';
 import { AsyncAPI } from '../mdx/async-api';
 import { Header } from './header';
@@ -26,7 +26,7 @@ const prompt = (pathname: string) => `Please read and analyze the content from t
 
 export default function Layout({ children }: LayoutProps) {
   const [loading, setLoading] = useState(true);
-  const [pathname] = useLocation();
+  const pathname = usePathname();
   const { showNotification } = useNotification();
   const isEmbedded = useIsEmbedded();
 

package/vite.config.ssr.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from 'vite';
+import preact from '@preact/preset-vite';
+import mdx from '@mdx-js/rollup';
+import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin';
+import { getMdxConfig } from './src/config/mdx';
+
+// Minimal Vite config for the SSR build.
+// Only includes plugins needed for MDX compilation — no sitemap, prerender,
+// analytics, or other build-time plugins that target the client output.
+export default defineConfig({
+  plugins: [
+    unifiedMdxPreprocessor(),
+    preact(),
+    mdx(getMdxConfig(false)),
+  ],
+  resolve: {
+    alias: {
+      react: 'preact/compat',
+      'react-dom': 'preact/compat'
+    }
+  },
+  build: {
+    ssr: 'src/entry-server.tsx',
+    outDir: 'dist-ssr',
+  },
+  ssr: {
+    // Bundle all dependencies so preact/compat aliases resolve correctly.
+    // Without this, externalized imports like @headlessui/react would
+    // import 'react' directly, bypassing the preact alias.
+    noExternal: true,
+  },
+});

package/vite.config.ts

@@ -11,7 +11,6 @@ import { docsAssetsPlugin } from './src/plugins/docs-assets';
 import { htmlMetadataInjector } from './src/plugins/html-metadata-injector';
 import { htmlFilesMiddleware } from './src/plugins/html-files-middleware';
 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';
@@ -32,7 +31,6 @@ export default defineConfig(({ command }) => ({
     docsAssetsPlugin(),
     htmlMetadataInjector(),
     analyticsInjector(),
-    cspGenerator(),
     sitemapGenerator(),
     robotsGenerator(),
     prerender(),

package/src/plugins/csp-generator.ts

@@ -1,68 +0,0 @@
-import type { Plugin } from 'vite';
-import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
-
-/**
- * Generates a Content-Security-Policy meta tag based on dory.json config.
- * Dynamically adds font sources and analytics domains as needed.
- */
-export function cspGenerator(): Plugin {
-  return {
-    name: 'csp-generator',
-    transformIndexHtml(html) {
-      const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
-      if (!existsSync(doryJsonPath)) return html;
-
-      try {
-        const config = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
-
-        const scriptSrc = ["'self'", "'unsafe-inline'", "'unsafe-eval'"];
-        const styleSrc = ["'self'", "'unsafe-inline'"];
-        const fontSrc = ["'self'", "data:"];
-        const connectSrc = ["'self'"];
-        const imgSrc = ["'self'", "data:", "https:"];
-
-        // Add Google Fonts if fonts are configured with external source
-        if (config.fonts?.source) {
-          try {
-            const fontUrl = new URL(config.fonts.source);
-            fontSrc.push(fontUrl.origin);
-          } catch {
-            // Not a URL, skip
-          }
-        }
-        styleSrc.push("https://fonts.googleapis.com");
-        fontSrc.push("https://fonts.gstatic.com");
-
-        // Add PostHog if analytics configured
-        if (config.analytics?.posthog?.token) {
-          const apiHost = config.analytics.posthog.apiHost || 'https://us.i.posthog.com';
-          const assetsHost = apiHost.replace('.i.posthog.com', '-assets.i.posthog.com');
-          scriptSrc.push(apiHost);
-          scriptSrc.push(assetsHost);
-          connectSrc.push(apiHost);
-        }
-
-        // Note: frame-ancestors is omitted because it's ignored in <meta> CSP tags.
-        // Clickjacking protection is handled via X-Frame-Options in nginx config.
-        const csp = [
-          `default-src 'self'`,
-          `script-src ${scriptSrc.join(' ')}`,
-          `style-src ${styleSrc.join(' ')}`,
-          `font-src ${fontSrc.join(' ')}`,
-          `img-src ${imgSrc.join(' ')}`,
-          `connect-src ${connectSrc.join(' ')}`,
-        ].join('; ');
-
-        return html.replace(
-          '</head>',
-          `  <meta http-equiv="Content-Security-Policy" content="${csp}">\n  </head>`
-        );
-      } catch (error) {
-        const detail = error instanceof SyntaxError ? error.message : String(error);
-        console.error(`Failed to generate CSP: ${detail}`);
-        return html;
-      }
-    },
-  };
-}