@clidey/dory 1.0.7 → 1.9.0

package/src/mdx/type-scale.tsx

@@ -1,9 +1,9 @@
 // Mirrors the heading scale in theme.scss (.dory-h1 to .dory-h4). Keep both in sync.
 const scale = [
-  { level: 'H1', size: 26, tracking: -0.025, weight: 700 },
-  { level: 'H2', size: 21, tracking: -0.02, weight: 700 },
-  { level: 'H3', size: 17, tracking: -0.01, weight: 700 },
-  { level: 'H4', size: 15, tracking: -0.005, weight: 600 },
+  { level: 'H1', size: 48, tracking: -0.035, weight: 700 },
+  { level: 'H2', size: 34, tracking: -0.03, weight: 700 },
+  { level: 'H3', size: 22, tracking: -0.02, weight: 700 },
+  { level: 'H4', size: 18, tracking: -0.01, weight: 600 },
 ]
 
 /** Shows each heading level with its size and letter-spacing, without emitting real headings. */

package/src/mdx/websocket-playground.tsx

@@ -1,5 +1,6 @@
+import { CatalogIcon } from '@clidey/ux'
 import classNames from 'classnames'
-import { ChevronsUpDown, X } from 'lucide-react'
+
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
 import { Tag } from './tag'
 
@@ -45,7 +46,7 @@ function MonoLabel({ children }: { children: string }) {
 function RemoveButton({ onClick, label }: { onClick: () => void; label: string }) {
   return (
     <button type="button" onClick={onClick} aria-label={label} className="rounded-md p-1.5 text-muted-foreground transition hover:bg-muted hover:text-foreground">
-      <X className="h-3.5 w-3.5" />
+      <CatalogIcon name="close" className="h-3.5 w-3.5" />
     </button>
   )
 }
@@ -119,16 +120,18 @@ function Select({ value, onChange, children, label }: { value: string; onChange:
       >
         {children}
       </select>
-      <ChevronsUpDown aria-hidden="true" className="pointer-events-none absolute right-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+      <CatalogIcon name="up-down" aria-hidden="true" className="pointer-events-none absolute right-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
     </div>
   )
 }
 
 function AuthTab({ auth, setAuth }: { auth: AuthState; setAuth: (auth: AuthState) => void }) {
-  const field = (key: keyof AuthState, placeholder: string, type = 'text') => (
-    <input className={inputClass} type={type} value={auth[key] as string} placeholder={placeholder} aria-label={placeholder}
-      onInput={(e) => setAuth({ ...auth, [key]: (e.target as HTMLInputElement).value })} />
-  )
+  const field = (key: keyof AuthState, placeholder: string, password = false) => {
+    const onInput = (e: Event) => setAuth({ ...auth, [key]: (e.target as HTMLInputElement).value })
+    return password
+      ? <input className={inputClass} type="password" value={auth[key] as string} placeholder={placeholder} aria-label={placeholder} onInput={onInput} />
+      : <input className={inputClass} value={auth[key] as string} placeholder={placeholder} aria-label={placeholder} onInput={onInput} />
+  }
   return (
     <div className="flex flex-col gap-3">
       <Select label="Authentication type" value={auth.type} onChange={(type) => setAuth({ ...auth, type: type as AuthState['type'] })}>
@@ -137,9 +140,9 @@ function AuthTab({ auth, setAuth }: { auth: AuthState; setAuth: (auth: AuthState
         <option value="apiKey">API key</option>
         <option value="basic">Basic auth</option>
       </Select>
-      {auth.type === 'bearer' && <div className="flex">{field('token', 'Bearer token', 'password')}</div>}
-      {auth.type === 'apiKey' && <div className="flex">{field('apiKey', 'API key', 'password')}</div>}
-      {auth.type === 'basic' && <div className="flex gap-2">{field('username', 'Username')}{field('password', 'Password', 'password')}</div>}
+      {auth.type === 'bearer' && <div className="flex">{field('token', 'Bearer token', true)}</div>}
+      {auth.type === 'apiKey' && <div className="flex">{field('apiKey', 'API key', true)}</div>}
+      {auth.type === 'basic' && <div className="flex gap-2">{field('username', 'Username')}{field('password', 'Password', true)}</div>}
     </div>
   )
 }
@@ -148,7 +151,7 @@ const statusDot: Record<ConnectionState, string> = {
   connected: 'bg-green-600',
   connecting: 'bg-[var(--highlight)]',
   error: 'bg-[var(--destructive)]',
-  disconnected: 'bg-muted-foreground',
+  disconnected: 'bg-[var(--muted-foreground)]',
 }
 
 const statusText: Record<ConnectionState, string> = {
@@ -254,7 +257,8 @@ export function WebSocketPanel({
         </button>
       </div>
 
-      <div className="flex flex-col gap-4 px-4 pt-4 pb-5">
+      <div className="grid lg:grid-cols-[minmax(0,1fr)_minmax(0,1.4fr)]">
+      <div className="flex flex-col gap-4 border-b border-[var(--border)] px-4 pt-4 pb-5 lg:border-b-0 lg:border-r">
         {servers.length > 0 && (
           <div className="flex flex-col gap-2">
             <MonoLabel>Server</MonoLabel>
@@ -286,11 +290,12 @@ export function WebSocketPanel({
         </div>
       </div>
 
-      <div className="flex items-center justify-between border-t border-[var(--border)] px-4 py-2.5">
+      <div className="flex flex-col">
+      <div className="flex items-center justify-between px-4 py-2.5">
         <MonoLabel>Messages</MonoLabel>
         <button type="button" onClick={() => setMessages([])} className="text-sm text-muted-foreground hover:text-foreground">Clear</button>
       </div>
-      <div className="max-h-72 min-h-56 overflow-y-auto border-t border-[var(--border)] bg-background px-4 py-3">
+      <div className="max-h-96 min-h-64 flex-1 overflow-y-auto border-t border-[var(--border)] bg-background px-4 py-3">
         {messages.length === 0 ? (
           <p className="flex h-48 items-center justify-center text-sm text-muted-foreground">Connect to start receiving messages</p>
         ) : (
@@ -327,6 +332,8 @@ export function WebSocketPanel({
           Send
         </button>
       </div>
+      </div>
+      </div>
     </div>
   )
 }

package/src/plugins/analytics-injector.ts

@@ -7,9 +7,14 @@ import { resolve } from 'path';
  * PostHog is only injected if `analytics.posthog.token` is configured.
  */
 export function analyticsInjector(): Plugin {
+  let isProductionBuild = false;
   return {
     name: 'analytics-injector',
+    configResolved(config) {
+      isProductionBuild = config.command === 'build';
+    },
     transformIndexHtml(html) {
+      if (!isProductionBuild) return html;
       const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
       if (!existsSync(doryJsonPath)) return html;
 
@@ -28,6 +33,9 @@ export function analyticsInjector(): Plugin {
         posthog.init(${token}, {
             api_host: ${apiHost},
             person_profiles: 'identified_only',
+            autocapture: false,
+            capture_pageview: 'history_change',
+            capture_pageleave: 'if_capture_pageview',
         })
     </script>`;
 

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

@@ -0,0 +1,32 @@
+import { loadEnv, type Plugin } from 'vite';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { handleChatRequest } from '../../bin/chat-server.ts';
+
+/** Development-only same-origin chat endpoint. Production uses `dory preview`. */
+export function chatDevServer(): Plugin {
+  return {
+    name: 'dory-chat-dev-server',
+    configResolved(config) {
+      if (config.command !== 'serve') return;
+      // Vite parses .env for its own client env, but does not populate process.env.
+      // The chat handler reads these values only on the dev server.
+      const env = loadEnv(config.mode, config.root, '');
+      for (const name of [
+        'DORY_CHAT_API_KEY', 'OPENAI_API_KEY', 'DORY_CHAT_MODEL', 'DORY_CHAT_BASE_URL',
+        'DORY_CHAT_PER_MINUTE', 'DORY_CHAT_PER_IP_DAY', 'DORY_CHAT_GLOBAL_DAY',
+        'DORY_CHAT_MAX_CONCURRENT', 'DORY_CHAT_MAX_OUTPUT_TOKENS',
+      ]) {
+        if (!process.env[name] && env[name]) process.env[name] = env[name];
+      }
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const root = resolve(process.cwd(), 'docs');
+        handleChatRequest(req, res, { docsDir: existsSync(root) ? root : process.cwd(), localDevelopment: true })
+          .then(handled => { if (!handled) next(); })
+          .catch(next);
+      });
+    },
+  };
+}

package/src/plugins/docs-assets.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { docsAssetsPlugin } from './docs-assets';
+
+describe('docs assets', () => {
+  it('copies regular assets and excludes symlinks to files outside docs', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dory-assets-'));
+    try {
+      mkdirSync(join(root, 'docs'));
+      writeFileSync(join(root, 'secret'), 'private');
+      writeFileSync(join(root, 'docs', 'safe.svg'), '<svg />');
+      symlinkSync(join(root, 'secret'), join(root, 'docs', 'leak.svg'));
+      vi.spyOn(process, 'cwd').mockReturnValue(root);
+      const closeBundle = docsAssetsPlugin().closeBundle as () => void;
+      closeBundle();
+      expect(existsSync(join(root, 'dist', 'safe.svg'))).toBe(true);
+      expect(existsSync(join(root, 'dist', 'leak.svg'))).toBe(false);
+    } finally {
+      vi.restoreAllMocks();
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/plugins/docs-assets.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { cpSync, existsSync, readdirSync, statSync } from 'fs';
+import { cpSync, existsSync, lstatSync, readdirSync } from 'fs';
 import { resolve, extname } from 'path';
 
 /**
@@ -54,7 +54,11 @@ export function docsAssetsPlugin(): Plugin {
           const itemRelativePath = relativePath ? `${relativePath}/${item}` : item;
 
           try {
-            const stats = statSync(srcPath);
+            const stats = lstatSync(srcPath);
+
+            // Do not copy symlinks: they can point outside docs and leak files
+            // from the build machine through the generated static site.
+            if (stats.isSymbolicLink()) continue;
 
             if (stats.isDirectory()) {
               // Recursively copy directories

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

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 import path from 'path';
-import { generateFrontmatterJson, generateSearchContentJson } from './frontmatter-generator';
-import { getBasePath, readDoryConfig } from './shared';
+import { generateFrontmatterJson, generateSearchContentJson } from './frontmatter-generator.ts';
+import { getBasePath, readDoryConfig } from './shared.ts';
 
 /**
  * Dev server plugin that serves frontmatter.json and search-content.json

package/src/plugins/frontmatter-generator.ts

@@ -7,7 +7,7 @@ import {
   pathFromFilename,
   findMdxFilesMap,
   stripMdxToText,
-} from './shared';
+} from './shared.ts';
 
 interface FrontmatterGeneratorOptions {
   docsDir?: string;

package/src/plugins/html-files-middleware.test.ts

@@ -1,6 +1,9 @@
 import { describe, it, expect } from 'vitest';
 import { resolve } from 'path';
-import { isPathInside } from './html-files-middleware';
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { isPathInside, isRealPathInside } from './html-files-middleware';
 
 describe('isPathInside', () => {
   const root = resolve('/srv/app/dist');
@@ -19,3 +22,20 @@ describe('isPathInside', () => {
     expect(isPathInside(root, resolve('/srv/app/dist-other/file'))).toBe(false);
   });
 });
+
+describe('isRealPathInside', () => {
+  it('rejects a symlink that escapes the served directory', () => {
+    const parent = mkdtempSync(join(tmpdir(), 'dory-assets-'));
+    try {
+      const docs = join(parent, 'docs');
+      mkdirSync(docs);
+      writeFileSync(join(parent, 'secret'), 'private');
+      writeFileSync(join(docs, 'safe.svg'), '<svg />');
+      symlinkSync(join(parent, 'secret'), join(docs, 'leak.svg'));
+      expect(isRealPathInside(docs, join(docs, 'safe.svg'))).toBe(true);
+      expect(isRealPathInside(docs, join(docs, 'leak.svg'))).toBe(false);
+    } finally {
+      rmSync(parent, { recursive: true, force: true });
+    }
+  });
+});

package/src/plugins/html-files-middleware.ts

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
-import { readFileSync, existsSync, statSync } from 'fs';
+import { readFileSync, existsSync, realpathSync, statSync } from 'fs';
 import { resolve, extname, sep } from 'path';
-import { getBasePath, readDoryConfig } from './shared';
+import { getBasePath, readDoryConfig } from './shared.ts';
 
 /**
  * Returns true if `target` is the `root` path itself or is contained within it.
@@ -11,6 +11,15 @@ export function isPathInside(root: string, target: string): boolean {
   return target === root || target.startsWith(root + sep);
 }
 
+/** Resolve symlinks before serving a file so a path inside docs cannot point outside it. */
+export function isRealPathInside(root: string, target: string): boolean {
+  try {
+    return isPathInside(realpathSync(root), realpathSync(target));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Vite plugin to serve HTML files and assets directly from the docs directory
  * and static files from the dist directory without routing them through the SPA
@@ -46,6 +55,7 @@ export function htmlFilesMiddleware(): Plugin {
     '.woff2': 'font/woff2',
     '.ttf': 'font/ttf',
     '.eot': 'application/vnd.ms-fontobject',
+    '.mdx': 'text/markdown; charset=utf-8',
   };
 
   return {
@@ -80,7 +90,12 @@ export function htmlFilesMiddleware(): Plugin {
 
           if (existsSync(distPath)) {
             try {
-              const content = readFileSync(distPath);
+              if (!isRealPathInside(distRoot, distPath)) {
+                res.statusCode = 403;
+                res.end('Forbidden');
+                return;
+              }
+              const content = readFileSync(realpathSync(distPath));
               const ext = extname(url).toLowerCase();
               const contentType = mimeTypes[ext] || 'application/octet-stream';
 
@@ -108,15 +123,20 @@ export function htmlFilesMiddleware(): Plugin {
 
         if (existsSync(docsPath)) {
           try {
+            if (!isRealPathInside(docsRoot, docsPath)) {
+              res.statusCode = 403;
+              res.end('Forbidden');
+              return;
+            }
             const stats = statSync(docsPath);
 
             // If it's a file, serve it
             if (stats.isFile()) {
               const ext = extname(url).toLowerCase();
 
-              // Only serve HTML files and assets, not MDX files
-              if (url.endsWith('.html') || assetExtensions.has(ext)) {
-                const content = readFileSync(docsPath);
+              // HTML, assets, and MDX sources (the build copies these too, for Open MDX / Copy page)
+              if (url.endsWith('.html') || ext === '.mdx' || assetExtensions.has(ext)) {
+                const content = readFileSync(realpathSync(docsPath));
                 const contentType = mimeTypes[ext] || 'application/octet-stream';
 
                 res.setHeader('Content-Type', contentType);

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

@@ -1,5 +1,6 @@
 import type { Plugin } from 'vite';
-import { readDoryConfig, escapeHtml, applyTitleTemplate, getBasePath, getSiteUrl } from './shared';
+import { readDoryConfig, escapeHtml, applyTitleTemplate, getBasePath, getSiteUrl } from './shared.ts';
+import { socialPreviewPath } from './social-preview.ts';
 
 /**
  * Vite plugin that injects site metadata from dory.json into index.html.
@@ -25,7 +26,8 @@ export function htmlMetadataInjector(): Plugin {
         const twitterHandle: string = config.twitter || '';
 
         // Resolve image to absolute URL
-        const rawImage: string = config.image || '';
+        const generateImages = seo.generateSocialImages !== false;
+        const rawImage: string = generateImages ? socialPreviewPath('/') : seo.ogImage || config.image || '';
         const siteImage = rawImage && siteUrl && !rawImage.startsWith('http')
           ? `${siteUrl}${rawImage.startsWith('/') ? '' : '/'}${rawImage}`
           : rawImage;
@@ -48,6 +50,24 @@ export function htmlMetadataInjector(): Plugin {
           html = html.replace('</head>', () => `  ${tag}\n  </head>`);
         };
 
+        // A single site URL is enough for clients to find the MDX index.
+        injectHeadTag(`<link rel="alternate" type="text/plain" title="LLM documentation index" href="${escapeHtml(basePath)}/llms.txt" />`);
+
+        const siteSchema = JSON.stringify({
+          '@context': 'https://schema.org',
+          '@graph': [
+            {
+              '@type': 'WebSite', name: siteName, description: defaultDescription,
+              ...(siteUrl ? { '@id': `${siteUrl}/#website`, url: `${siteUrl}/` } : {}),
+            },
+            {
+              '@type': 'WebPage', name: defaultTitle, description: defaultDescription,
+              ...(siteUrl ? { url: `${siteUrl}/`, isPartOf: { '@id': `${siteUrl}/#website` } } : {}),
+            },
+          ],
+        }).replace(/</g, '\\u003c');
+        injectHeadTag(`<script type="application/ld+json" data-dory-site-schema>${siteSchema}</script>`);
+
         // Title
         setTag(/<title>.*?<\/title>/, `<title>${escapeHtml(defaultTitle)}</title>`);
 
@@ -128,10 +148,10 @@ export function htmlMetadataInjector(): Plugin {
         }
 
         // Twitter tags
-        if (seo.twitterCard) {
+        if (generateImages || seo.twitterCard) {
           setTag(
             /<meta name="twitter:card" content=".*?" \/>/,
-            `<meta name="twitter:card" content="${escapeHtml(seo.twitterCard)}" />`
+            `<meta name="twitter:card" content="${generateImages ? 'summary_large_image' : escapeHtml(seo.twitterCard)}" />`
           );
         }
         setTag(

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

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 import path from 'path';
-import { generateLlmsIndex, generateLlmContent } from './llm-txt-generator';
-import { getBasePath, readDoryConfig } from './shared';
+import { generateLlmsIndex, generateLlmContent } from './llm-txt-generator.ts';
+import { getBasePath, readDoryConfig } from './shared.ts';
 
 /**
  * Dev server plugin that serves llms.txt and llms-full.txt on demand,

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

@@ -8,7 +8,7 @@ import {
   findMdxFilesMap,
   pathFromFilename,
   getSiteUrl,
-} from './shared';
+} from './shared.ts';
 
 interface LlmTxtGeneratorOptions {
   docsDir?: string;
@@ -44,28 +44,34 @@ export function generateLlmsIndex(docsDir: string): string {
   const siteName: string = config.name || 'Documentation';
   const baseUrl: string = getSiteUrl(config);
   const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+  const listed = new Set<string>();
 
   let output = `# ${siteName}\n`;
   if (config.description) {
     output += `\n> ${config.description}\n`;
   }
 
+  output += `\nThis site publishes its MDX source. Fetch the .mdx links below for individual pages, or ${baseUrl || ''}/llms-full.txt for one combined text file. Start from this URL to discover documentation without guessing repository paths.\n`;
+  output += `\nIf this site is served by Dory's Node preview server, a read-only MCP endpoint is available at ${baseUrl || ''}/mcp. MCP clients require a one-time connection to that endpoint; the page URL alone is sufficient for clients that can browse these links.\n`;
+
   const tabs: any[] = config.navigation?.tabs || [];
   for (const tab of tabs) {
     const links: string[] = [];
     const walkPages = (pages: any[]) => {
-      for (const page of pages) {
+      for (const entry of pages) {
+        const page = typeof entry === 'object' && entry && typeof entry.page === 'string' ? entry.page : entry;
         if (typeof page === 'string') {
           const fileKey = resolveFileKey(page, mdxFilesMap);
           if (!fileKey) continue;
+          listed.add(fileKey);
           const raw = fs.readFileSync(mdxFilesMap[fileKey], 'utf-8');
           const { data } = parseFrontmatter(raw);
           const routePath = pathFromFilename(mdxFilesMap[fileKey], docsDir);
           const url = `${baseUrl}${routePath}.mdx`;
           const title = data.title || page;
           links.push(data.description ? `- [${title}](${url}): ${data.description}` : `- [${title}](${url})`);
-        } else if (typeof page === 'object' && page.pages) {
-          walkPages(page.pages);
+        } else if (typeof entry === 'object' && entry.pages) {
+          walkPages(entry.pages);
         }
       }
     };
@@ -77,6 +83,17 @@ export function generateLlmsIndex(docsDir: string): string {
     }
   }
 
+  const additional = Object.keys(mdxFilesMap).filter(key => !listed.has(key)).sort();
+  if (additional.length > 0) {
+    output += '\n## Other pages and translations\n\n';
+    for (const fileKey of additional) {
+      const raw = fs.readFileSync(mdxFilesMap[fileKey], 'utf-8');
+      const { data } = parseFrontmatter(raw);
+      const routePath = pathFromFilename(mdxFilesMap[fileKey], docsDir);
+      output += `- [${data.title || fileKey}](${baseUrl}${routePath}.mdx)${data.description ? `: ${data.description}` : ''}\n`;
+    }
+  }
+
   return output.trim() + '\n';
 }
 

package/src/plugins/prerender.ts

@@ -11,7 +11,10 @@ import {
   applyTitleTemplate,
   getBasePath,
   getSiteUrl,
-} from './shared';
+} from './shared.ts';
+import { contentScope, scopedPath } from '../utils/content-scope.ts';
+import type { DoryConfig } from '../types/config.ts';
+import { renderSocialPreview } from './social-preview.ts';
 
 /**
  * Generates per-route HTML files with page-specific meta tags and JSON-LD
@@ -42,6 +45,7 @@ export function prerender(): Plugin {
         const baseHtml = readFileSync(indexHtmlPath, 'utf-8');
 
         const siteConfig = readDoryConfig() || {};
+        const typedConfig = siteConfig as DoryConfig;
         const seo = siteConfig.seo || {};
         const baseUrl: string = getSiteUrl(siteConfig);
         const siteName: string = siteConfig.name || 'Documentation';
@@ -57,7 +61,6 @@ export function prerender(): Plugin {
         const ogImage = rawOgImage && baseUrl && !rawOgImage.startsWith('http')
           ? `${baseUrl}${rawOgImage.startsWith('/') ? '' : '/'}${rawOgImage}`
           : rawOgImage;
-        const hasImage = Boolean(ogImage || siteConfig.image);
 
         // Map route paths to MDX source files for description fallbacks
         const docsDir = resolve(process.cwd(), 'docs');
@@ -69,6 +72,9 @@ export function prerender(): Plugin {
 
         const missingDescriptions: string[] = [];
         let count = 0;
+        if (seo.generateSocialImages !== false) {
+          renderSocialPreview({ route: '/', title: siteConfig.title || siteName, description: siteConfig.description || '', config: typedConfig, docsDir, outDir });
+        }
 
         for (const page of frontmatter) {
           const routePath = page.path;
@@ -80,8 +86,21 @@ export function prerender(): Plugin {
             missingDescriptions.push(routePath);
           }
           const fullUrl = baseUrl ? `${baseUrl}${routePath}` : '';
+          const scope = contentScope(typedConfig, routePath);
+          const customImage = typeof page.image === 'string' ? page.image : typeof page.ogImage === 'string' ? page.ogImage : '';
+          let image = customImage;
+          if (!image && seo.generateSocialImages !== false) {
+            image = renderSocialPreview({ route: routePath, title: page.title || siteName, description, config: typedConfig, docsDir, outDir });
+          }
+          image ||= ogImage || siteConfig.image || '';
+          if (image && !/^https?:\/\//i.test(image)) image = `${baseUrl || getBasePath(siteConfig)}/${image.replace(/^\.?\//, '')}`;
 
-          let html = baseHtml;
+          // Route-specific structured data replaces the homepage graph.
+          let html = baseHtml.replace(/<script type="application\/ld\+json" data-dory-site-schema>[\s\S]*?<\/script>/, '');
+          html = html.replace(/<html\b([^>]*)>/, (_match, attrs: string) => {
+            const withoutLang = attrs.replace(/\s+lang="[^"]*"/, '');
+            return `<html${withoutLang} lang="${escapeHtml(scope.locale)}">`;
+          });
           // Function replacements so `$&` etc. in values cannot corrupt output
           const setTag = (re: RegExp, replacement: string) => {
             html = html.replace(re, () => replacement);
@@ -105,27 +124,30 @@ export function prerender(): Plugin {
             /<meta property="og:description" content=".*?" \/>/,
             `<meta property="og:description" content="${escapeHtml(description)}" />`
           );
+          if (typedConfig.i18n) {
+            setTag(
+              /<meta property="og:locale" content=".*?" \/>/,
+              `<meta property="og:locale" content="${escapeHtml(scope.locale.replace(/-/g, '_'))}" />`
+            );
+          }
           setTag(
             /<meta property="og:type" content=".*?" \/>/,
             '<meta property="og:type" content="article" />'
           );
-          if (ogImage) {
+          if (image) {
             setTag(
               /<meta property="og:image" content=".*?" \/>/,
-              `<meta property="og:image" content="${escapeHtml(ogImage)}" />`
+              `<meta property="og:image" content="${escapeHtml(image)}" />`
             );
             setTag(
               /<meta name="twitter:image" content=".*?" \/>/,
-              `<meta name="twitter:image" content="${escapeHtml(ogImage)}" />`
-            );
-          }
-          if (!hasImage) {
-            // No shareable image — a large-image card would render broken
-            setTag(
-              /<meta name="twitter:card" content=".*?" \/>/,
-              '<meta name="twitter:card" content="summary" />'
+              `<meta name="twitter:image" content="${escapeHtml(image)}" />`
             );
           }
+          setTag(
+            /<meta name="twitter:card" content=".*?" \/>/,
+            `<meta name="twitter:card" content="${image ? escapeHtml(seo.twitterCard || 'summary_large_image') : 'summary'}" />`
+          );
 
           // Twitter tags
           setTag(
@@ -150,6 +172,14 @@ export function prerender(): Plugin {
             );
           }
 
+          if (baseUrl && typedConfig.i18n) {
+            for (const locale of typedConfig.i18n.locales) {
+              const alternate = scopedPath(typedConfig, routePath, locale.code, scope.version);
+              if (!fileByRoute[alternate]) continue;
+              injectHeadTag(`<link rel="alternate" hreflang="${escapeHtml(locale.code)}" href="${escapeHtml(`${baseUrl}${alternate}`)}" />`);
+            }
+          }
+
           // Per-page robots directive from frontmatter
           if (page.robots) {
             injectHeadTag(`<meta name="robots" content="${escapeHtml(String(page.robots))}" />`);
@@ -253,14 +283,11 @@ function write404(
   let html = baseHtml;
   html = html.replace(/<title>.*?<\/title>/, () => `<title>Page not found — ${escapeHtml(siteName)}</title>`);
   html = html.replace('</head>', () => '  <meta name="robots" content="noindex" />\n  </head>');
+  // Leave #app empty so the client renders the same UX NotFoundPage used for unknown routes.
+  // A separate noscript fallback keeps the static 404 useful without JavaScript.
   html = html.replace(
-    '<div id="app"></div>',
-    () =>
-      '<div id="app"><main style="max-width:36rem;margin:6rem auto;padding:0 1.5rem;font-family:sans-serif;text-align:center">' +
-      '<h1>Page not found</h1>' +
-      '<p>The page you are looking for does not exist.</p>' +
-      `<p><a href="${escapeHtml(firstHref)}">Go to ${escapeHtml(firstTitle)}</a></p>` +
-      '</main></div>'
+    '<noscript>You need to enable JavaScript to run this app.</noscript>',
+    () => `<noscript><main><h1>Page not found</h1><p>The page you are looking for does not exist.</p><p><a href="${escapeHtml(firstHref)}">Go to ${escapeHtml(firstTitle)}</a></p></main></noscript>`
   );
   writeFileSync(resolve(outDir, '404.html'), html, 'utf-8');
 }

package/src/plugins/robots-generator.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { readDoryConfig, getBasePath, getSiteUrl } from './shared';
+import { readDoryConfig, getBasePath, getSiteUrl } from './shared.ts';
 
 /**
  * Generates robots.txt at build time. Emits `Disallow: /` when seo.noindex

package/src/plugins/sanitize.ts

@@ -26,7 +26,7 @@ const KNOWN_COMPONENTS = [
   'Steps', 'Step', 'table', 'th', 'td', 'ul', 'ol', 'li',
   'UnorderedList', 'OrderedList', 'ListItem',
   'APIPlayground', 'WebSocketPlayground', 'AsyncAPI', 'Source', 'Tag',
-  'Specimen', 'SpecimenProps', 'Chip', 'ChipGroup', 'Tabs', 'Tab', 'IconGrid', 'TypeScale',
+  'Specimen', 'SpecimenProps', 'Prop', 'Chip', 'ChipGroup', 'Tabs', 'Tab', 'IconGrid', 'TypeScale',
   // Common HTML elements that should be preserved
   'div', 'span', 'br', 'hr', 'strong', 'em', 'b', 'i', 'u', 's',
   'blockquote', 'nav', 'section', 'article', 'header', 'footer', 'main',