@clidey/dory 1.0.8 → 1.10.0

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',
@@ -117,7 +117,8 @@ function hasMatchingClosingTag(code: string, tagName: string, openingTagOffset:
 }
 
 // Allow any <[a-z][a-z0-9]*> tag inside code blocks to be left as-is (not parsed as JSX).
-export function preprocessMdxTags() {
+export function preprocessMdxTags(importedComponents: readonly string[] = []) {
+  const knownComponents = new Set([...KNOWN_COMPONENTS, ...importedComponents]);
   return {
     name: 'preprocess-mdx-tags',
     enforce: 'pre' as const,
@@ -137,7 +138,7 @@ export function preprocessMdxTags() {
         }
 
         // If unknown component, treat as text
-        if (!KNOWN_COMPONENTS.includes(tag)) {
+        if (!knownComponents.has(tag)) {
           return `\`${match}\``;
         }
         return match;
@@ -152,7 +153,7 @@ export function preprocessMdxTags() {
         }
 
         // If known component, check if it has a closing tag
-        if (KNOWN_COMPONENTS.includes(tag)) {
+        if (knownComponents.has(tag)) {
           // If it doesn't have a matching closing tag, treat it as text
           if (!hasMatchingClosingTag(processed, tag, offset)) {
             return `\`<${tag}>\``;
@@ -173,7 +174,7 @@ export function preprocessMdxTags() {
         }
 
         // If known component, check if it has a closing tag (only for opening tags)
-        if (KNOWN_COMPONENTS.includes(tag)) {
+        if (knownComponents.has(tag)) {
           // Only check for matching closing tag for opening tags
           if (!match.startsWith('</')) {
             if (!hasMatchingClosingTag(processed, tag, offset)) {

package/src/plugins/shared.ts

@@ -1,7 +1,8 @@
 import matter from 'gray-matter';
 import fs from 'fs';
 import path from 'path';
-import { normalizeBasePath } from '../utils/base-path';
+import { normalizeBasePath } from '../utils/base-path.ts';
+export { stripMdxToText } from '../utils/search-content.ts';
 
 /**
  * Shared helpers for build plugins that read docs/*.mdx and docs/dory.json.
@@ -62,6 +63,8 @@ export function getNavigationOrder(docsDir: string): string[] {
     for (const page of pages) {
       if (typeof page === 'string') {
         order.push(page);
+      } else if (typeof page === 'object' && typeof page.page === 'string') {
+        order.push(page.page);
       } else if (typeof page === 'object' && page.pages) {
         walkPages(page.pages);
       }
@@ -87,12 +90,13 @@ export function getNavigationOrder(docsDir: string): string[] {
  * e.g. docs/getting-started/installation.mdx -> /getting-started/installation.
  */
 export function pathFromFilename(filename: string, docsDir: string): string {
-  return filename
+  const route = filename
     .replace(docsDir, '')
     .replace(/\/?index\.mdx$/, '/')
     .replace(/\.mdx$/, '')
     .replace(/\\/g, '/')
     .toLowerCase();
+  return route.length > 1 ? route.replace(/\/$/, '') : route;
 }
 
 /**
@@ -117,22 +121,6 @@ export function findMdxFilesMap(dir: string, baseDir: string): Record<string, st
   return files;
 }
 
-/**
- * Strips MDX/JSX syntax to extract plain text (for search indexing and
- * meta description fallbacks).
- */
-export function stripMdxToText(content: string): string {
-  return content
-    .replace(/^import\s+.*$/gm, '')           // import statements
-    .replace(/^export\s+.*$/gm, '')           // export statements
-    .replace(/```[\s\S]*?```/g, '')           // fenced code blocks
-    .replace(/<[^>]+>/g, '')                  // JSX/HTML tags
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')  // markdown links -> text
-    .replace(/[#*_~`>|]/g, '')                // markdown syntax chars
-    .replace(/\n{3,}/g, '\n\n')               // collapse blank lines
-    .trim();
-}
-
 /**
  * Escapes a string for safe use in HTML/XML text and attribute values.
  */

package/src/plugins/sitemap-generator.ts

@@ -8,7 +8,7 @@ import {
   parseFrontmatter,
   escapeHtml,
   getSiteUrl,
-} from './shared';
+} from './shared.ts';
 
 /**
  * Generates sitemap.xml at build time from all MDX files (not just those in

package/src/plugins/social-preview.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, expect, test } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { renderSocialPreview, socialPreviewPath, wrapSocialText } from './social-preview';
+
+const folders: string[] = [];
+afterEach(() => { for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }); });
+
+test('image paths distinguish nested routes and cannot escape the output directory', () => {
+  expect(socialPreviewPath('/guide/start')).not.toBe(socialPreviewPath('/reference/start'));
+  expect(socialPreviewPath('/../../private')).toMatch(/^\/_dory\/social\/page-[a-f0-9]+\.png$/);
+});
+
+test('long titles wrap into bounded lines without cutting Unicode characters', () => {
+  const lines = wrapSocialText('A'.repeat(200), 30, 3);
+  expect(lines).toHaveLength(3);
+  expect(lines.every(line => Array.from(line).length <= 30)).toBe(true);
+  expect(lines[2]).toMatch(/…$/);
+  expect(wrapSocialText('😀'.repeat(12), 6, 2)).toEqual(['😀'.repeat(6), '😀'.repeat(6)]);
+});
+
+test('renders distinct 1200 by 630 PNGs with no system font or browser dependency', () => {
+  const root = mkdtempSync(resolve(tmpdir(), 'dory-social-'));
+  folders.push(root);
+  const docsDir = resolve(root, 'docs');
+  mkdirSync(docsDir);
+  const options = { config: { name: 'Example & Docs' }, docsDir, outDir: root, description: 'A guide for your team.' };
+  const first = renderSocialPreview({ ...options, route: '/install', title: 'Installation' });
+  const second = renderSocialPreview({ ...options, route: '/start', title: 'Getting started <safely>' });
+  const png = readFileSync(resolve(root, first.slice(1)));
+  expect(png.subarray(0, 8)).toEqual(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  expect(png.readUInt32BE(16)).toBe(1200);
+  expect(png.readUInt32BE(20)).toBe(630);
+  expect(png).not.toEqual(readFileSync(resolve(root, second.slice(1))));
+});
+
+test('page overrides and shared-image opt-out produce correct base-prefixed metadata', async () => {
+  const { prerender } = await import('./prerender');
+  const { vi } = await import('vitest');
+  const { copyFileSync, writeFileSync } = await import('node:fs');
+  const root = mkdtempSync(resolve(tmpdir(), 'dory-social-metadata-'));
+  folders.push(root);
+  const dist = resolve(root, 'dist');
+  mkdirSync(resolve(root, 'docs'), { recursive: true });
+  mkdirSync(resolve(root, 'src/assets/fonts'), { recursive: true });
+  mkdirSync(dist);
+  copyFileSync(resolve('src/assets/fonts/HankenGrotesk.ttf'), resolve(root, 'src/assets/fonts/HankenGrotesk.ttf'));
+  const config = { name: 'Example', url: 'https://docs.example.com', basePath: '/manual', image: '/shared.png', navigation: { tabs: [] } };
+  const template = '<html lang="en"><head><title>Docs</title><meta name="description" content="" /><meta property="og:image" content="" /><meta name="twitter:image" content="" /><meta name="twitter:card" content="summary" /></head><body><div id="app"></div></body></html>';
+  writeFileSync(resolve(dist, 'frontmatter.json'), JSON.stringify([
+    { path: '/start', title: 'Start', description: 'Get started.' },
+    { path: '/custom', title: 'Custom', description: 'Custom page.', image: '/art/custom.png' },
+  ]));
+  const cwd = vi.spyOn(process, 'cwd').mockReturnValue(root);
+  try {
+    for (const enabled of [true, false]) {
+      writeFileSync(resolve(root, 'docs/dory.json'), JSON.stringify({ ...config, seo: { generateSocialImages: enabled } }));
+      writeFileSync(resolve(dist, 'index.html'), template);
+      const hooks = prerender() as { configResolved(config: unknown): void; closeBundle(): void };
+      hooks.configResolved({ build: { outDir: dist } });
+      hooks.closeBundle();
+      const start = readFileSync(resolve(dist, 'start/index.html'), 'utf8');
+      const custom = readFileSync(resolve(dist, 'custom/index.html'), 'utf8');
+      const image = enabled ? socialPreviewPath('/start') : '/shared.png';
+      expect(start).toContain(`content="https://docs.example.com/manual${image}"`);
+      expect(custom).toContain('content="https://docs.example.com/manual/art/custom.png"');
+      if (enabled) expect(readFileSync(resolve(dist, image.slice(1))).readUInt32BE(16)).toBe(1200);
+    }
+  } finally { cwd.mockRestore(); }
+});

package/src/plugins/social-preview.ts

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { Resvg } from '@resvg/resvg-js';
+import type { DoryConfig } from '../types/config.ts';
+import { escapeHtml } from './shared.ts';
+
+export function socialPreviewPath(route: string): string {
+  return route === '/' ? '/_dory/social/home.png' : `/_dory/social/page-${createHash('sha256').update(route).digest('hex').slice(0, 20)}.png`;
+}
+
+function localAsset(docsDir: string, source?: string): string | undefined {
+  if (!source || /^(?:[a-z]+:|\/\/)/i.test(source)) return;
+  const file = resolve(docsDir, source.replace(/^\//, ''));
+  if (!existsSync(file)) return;
+  const rel = relative(realpathSync(docsDir), realpathSync(file));
+  if (rel.startsWith('..') || isAbsolute(rel)) return;
+  return file;
+}
+
+/** Bounded lines, including long words and titles without spaces. */
+export function wrapSocialText(text: string, columns: number, maxLines: number): string[] {
+  const words = text.replace(/\s+/g, ' ').trim().split(' ');
+  const lines: string[] = [];
+  let line = '';
+  for (const word of words) {
+    if (line && Array.from(`${line} ${word}`).length > columns) { lines.push(line); line = ''; }
+    const characters = Array.from(word);
+    while (characters.length > columns) {
+      if (line) { lines.push(line); line = ''; }
+      lines.push(characters.splice(0, columns).join(''));
+    }
+    const tail = characters.join('');
+    if (tail) line = line ? `${line} ${tail}` : tail;
+  }
+  if (line) lines.push(line);
+  if (lines.length > maxLines) {
+    lines.length = maxLines;
+    lines[maxLines - 1] = `${Array.from(lines[maxLines - 1]).slice(0, columns - 1).join('').trimEnd()}…`;
+  }
+  return lines;
+}
+
+/** Build-only PNG generation: local files, bundled font, no browser or network. */
+export function renderSocialPreview({ route, title, description, config, docsDir, outDir }: {
+  route: string; title: string; description: string; config: Partial<DoryConfig>; docsDir: string; outDir: string;
+}): string {
+  const name = config.name || 'Documentation';
+  const hex = (value: string | undefined, fallback: string) => value && /^#[a-f\d]{3,8}$/i.test(value) ? value : fallback;
+  const background = hex(config.colors?.background, '#15243e');
+  const primary = hex(config.colors?.primary, '#5c8cf4');
+  const foreground = hex(config.colors?.foreground, '#f8f5ed');
+  const muted = hex(config.colors?.mutedForeground, '#b2bdd0');
+  const logo = localAsset(docsDir, config.logo?.dark ?? config.logo?.light);
+  const imageTypes: Record<string, string> = { '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+  const logoType = logo && imageTypes[extname(logo).toLowerCase()];
+  const logoData = logo && logoType ? `data:${logoType};base64,${readFileSync(logo).toString('base64')}` : undefined;
+  const font = localAsset(docsDir, config.fonts?.heading?.source ?? config.fonts?.source);
+  const customFont = font && /\.(ttf|otf)$/i.test(font) ? font : undefined;
+  const family = customFont ? config.fonts?.heading?.family ?? config.fonts?.family ?? 'Hanken Grotesk' : 'Hanken Grotesk';
+  const size = title.length > 85 ? 56 : 64;
+  const lines = wrapSocialText(title, Math.floor(1050 / (size * 0.62)), 3);
+  const text = (value: string, x: number, y: number, fontSize: number, color: string, weight = 400) => `<text x="${x}" y="${y}" font-size="${fontSize}" fill="${color}" font-weight="${weight}">${escapeHtml(value)}</text>`;
+  const subtitleY = Math.max(350, 225 + (lines.length - 1) * 76 + 65);
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+    <rect width="1200" height="630" fill="${background}"/><rect width="1200" height="8" fill="${primary}"/>
+    <circle cx="1170" cy="360" r="280" fill="${primary}" opacity="0.06"/>
+    <g font-family="${escapeHtml(family)}, sans-serif">
+      ${logoData ? `<image href="${logoData}" x="72" y="62" width="46" height="50"/>` : `<rect x="72" y="64" width="44" height="44" rx="10" fill="${primary}"/>`}
+      ${text(wrapSocialText(name, 55, 1)[0] ?? '', 136, 100, 32, foreground, 700)}
+      ${lines.map((line, i) => text(line, 72, 225 + i * 76, size, foreground, 700)).join('')}
+      ${wrapSocialText(description, 78, 2).map((line, i) => text(line, 76, subtitleY + i * 36, 26, muted)).join('')}
+      <path d="M76 518H1124" stroke="${foreground}" opacity="0.15"/>
+      ${text('DOCUMENTATION', 76, 565, 17, muted)}
+      <text x="1124" y="565" text-anchor="end" font-size="20" fill="${primary}">${escapeHtml(wrapSocialText(config.url?.replace(/^https?:\/\//, '') ?? name, 60, 1)[0] ?? '')}</text>
+    </g></svg>`;
+  const path = socialPreviewPath(route);
+  const file = resolve(outDir, path.slice(1));
+  mkdirSync(dirname(file), { recursive: true });
+  const renderer = new Resvg(svg, { font: {
+    loadSystemFonts: false,
+    fontFiles: [resolve(process.cwd(), 'src/assets/fonts/HankenGrotesk.ttf'), ...(customFont ? [customFont] : [])],
+    defaultFontFamily: family,
+  } });
+  writeFileSync(file, renderer.render().asPng());
+  return path;
+}

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

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { preprocessMdxContent } from '../mdx/processor';
+import { preprocessMdxContent } from '../mdx/processor.ts';
 
 /**
  * Unified MDX preprocessing plugin for Vite.