@clidey/dory 1.0.7 → 1.9.0

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.