@clidey/dory 0.47.0 → 0.49.0

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

@@ -1,6 +1,5 @@
 import type { Plugin } from 'vite';
-import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { readDoryConfig, escapeHtml, applyTitleTemplate } from './shared';
 
 /**
  * Vite plugin that injects site metadata from dory.json into index.html.
@@ -10,100 +9,161 @@ export function htmlMetadataInjector(): Plugin {
   return {
     name: 'html-metadata-injector',
     transformIndexHtml(html) {
-      const doryJsonPath = resolve(process.cwd(), 'docs', 'dory.json');
-
-      if (!existsSync(doryJsonPath)) {
+      const config = readDoryConfig();
+      if (!config) {
         console.warn('⚠️  dory.json not found, using default metadata');
         return html;
       }
 
       try {
-        const config = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
-        const siteName = config.name || 'Documentation';
-        const defaultTitle = config.title || siteName;
-        const defaultDescription = config.description || `${siteName} - Technical Documentation`;
-        const siteUrl = config.url || '';
-        const twitterHandle = config.twitter || '';
+        const seo = config.seo || {};
+        const siteName: string = config.name || 'Documentation';
+        const defaultTitle = applyTitleTemplate(config.title || siteName, seo.titleTemplate, siteName);
+        const defaultDescription: string = config.description || `${siteName} - Technical Documentation`;
+        const siteUrl: string = config.url || '';
+        const twitterHandle: string = config.twitter || '';
 
         // Resolve image to absolute URL
-        const rawImage = config.image || '';
+        const rawImage: string = config.image || '';
         const siteImage = rawImage && siteUrl && !rawImage.startsWith('http')
           ? `${siteUrl}${rawImage.startsWith('/') ? '' : '/'}${rawImage}`
           : rawImage;
 
-        // Replace title
-        html = html.replace(
-          /<title>.*?<\/title>/,
-          `<title>${defaultTitle}</title>`
-        );
+        // Favicon: config.favicon (copied to dist root by docs-assets), else
+        // fall back to the logo so sites without a dedicated favicon still
+        // get an icon instead of a broken link.
+        const rawFavicon: string = config.favicon || config.logo?.light || config.logo?.dark || '';
+        const faviconHref = rawFavicon ? `/${rawFavicon.replace(/^\.?\/*/, '')}` : '';
+
+        // Function replacements everywhere so `$&` etc. in config values
+        // cannot corrupt the output.
+        const setTag = (re: RegExp, replacement: string) => {
+          html = html.replace(re, () => replacement);
+        };
+        const removeTag = (re: RegExp) => {
+          html = html.replace(re, '');
+        };
+        const injectHeadTag = (tag: string) => {
+          html = html.replace('</head>', () => `  ${tag}\n  </head>`);
+        };
+
+        // Title
+        setTag(/<title>.*?<\/title>/, `<title>${escapeHtml(defaultTitle)}</title>`);
+
+        // Favicon (icon + apple-touch-icon); left as empty attributes in
+        // index.html and removed entirely when there's nothing to point at.
+        if (faviconHref) {
+          setTag(/<link rel="icon" href=".*?" \/>/, `<link rel="icon" href="${escapeHtml(faviconHref)}" />`);
+          setTag(
+            /<link rel="apple-touch-icon" href=".*?" \/>/,
+            `<link rel="apple-touch-icon" href="${escapeHtml(faviconHref)}" />`
+          );
+        } else {
+          removeTag(/[ \t]*<link rel="icon" href=".*?" \/>\n?/);
+          removeTag(/[ \t]*<link rel="apple-touch-icon" href=".*?" \/>\n?/);
+        }
 
-        // Replace meta description
-        html = html.replace(
+        // Description
+        setTag(
           /<meta name="description" content=".*?" \/>/,
-          `<meta name="description" content="${defaultDescription}" />`
+          `<meta name="description" content="${escapeHtml(defaultDescription)}" />`
         );
 
-        // Replace Open Graph tags
-        html = html.replace(
+        // Keywords / author — injected only when configured
+        if (Array.isArray(seo.keywords) && seo.keywords.length > 0) {
+          injectHeadTag(`<meta name="keywords" content="${escapeHtml(seo.keywords.join(', '))}" />`);
+        }
+        if (seo.author) {
+          injectHeadTag(`<meta name="author" content="${escapeHtml(seo.author)}" />`);
+        }
+
+        // Site-wide noindex (staging)
+        if (seo.noindex) {
+          injectHeadTag('<meta name="robots" content="noindex" />');
+        }
+
+        // Locale — html lang + og:locale
+        if (seo.locale) {
+          setTag(/<html lang=".*?">/, `<html lang="${escapeHtml(seo.locale.replace(/_/g, '-'))}">`);
+          setTag(
+            /<meta property="og:locale" content=".*?" \/>/,
+            `<meta property="og:locale" content="${escapeHtml(seo.locale)}" />`
+          );
+        }
+
+        // Open Graph tags
+        setTag(
           /<meta property="og:title" content=".*?" \/>/,
-          `<meta property="og:title" content="${defaultTitle}" />`
+          `<meta property="og:title" content="${escapeHtml(defaultTitle)}" />`
         );
-        html = html.replace(
+        setTag(
           /<meta property="og:description" content=".*?" \/>/,
-          `<meta property="og:description" content="${defaultDescription}" />`
+          `<meta property="og:description" content="${escapeHtml(defaultDescription)}" />`
         );
-        html = html.replace(
+        setTag(
           /<meta property="og:site_name" content=".*?" \/>/,
-          `<meta property="og:site_name" content="${siteName}" />`
+          `<meta property="og:site_name" content="${escapeHtml(siteName)}" />`
         );
         if (siteImage) {
-          html = html.replace(
+          setTag(
             /<meta property="og:image" content=".*?" \/>/,
-            `<meta property="og:image" content="${siteImage}" />`
+            `<meta property="og:image" content="${escapeHtml(siteImage)}" />`
           );
         }
+
+        // og:url and canonical — absolute when config.url is set, removed otherwise
         if (siteUrl) {
-          html = html.replace(
+          setTag(
             /<meta property="og:url" content=".*?" \/>/,
-            `<meta property="og:url" content="${siteUrl}" />`
+            `<meta property="og:url" content="${escapeHtml(siteUrl)}" />`
           );
+          setTag(
+            /<link rel="canonical" href=".*?" \/>/,
+            `<link rel="canonical" href="${escapeHtml(siteUrl)}" />`
+          );
+        } else {
+          removeTag(/[ \t]*<meta property="og:url" content=".*?" \/>\n?/);
+          removeTag(/[ \t]*<link rel="canonical" href=".*?" \/>\n?/);
         }
 
-        // Replace Twitter tags
-        html = html.replace(
+        // Twitter tags
+        if (seo.twitterCard) {
+          setTag(
+            /<meta name="twitter:card" content=".*?" \/>/,
+            `<meta name="twitter:card" content="${escapeHtml(seo.twitterCard)}" />`
+          );
+        }
+        setTag(
           /<meta name="twitter:title" content=".*?" \/>/,
-          `<meta name="twitter:title" content="${defaultTitle}" />`
+          `<meta name="twitter:title" content="${escapeHtml(defaultTitle)}" />`
         );
-        html = html.replace(
+        setTag(
           /<meta name="twitter:description" content=".*?" \/>/,
-          `<meta name="twitter:description" content="${defaultDescription}" />`
+          `<meta name="twitter:description" content="${escapeHtml(defaultDescription)}" />`
         );
         if (siteImage) {
-          html = html.replace(
+          setTag(
             /<meta name="twitter:image" content=".*?" \/>/,
-            `<meta name="twitter:image" content="${siteImage}" />`
+            `<meta name="twitter:image" content="${escapeHtml(siteImage)}" />`
           );
         }
-        html = html.replace(
-          /<meta name="twitter:site" content=".*?" \/>/,
-          `<meta name="twitter:site" content="${twitterHandle}" />`
-        );
-        html = html.replace(
-          /<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}" />`
+        if (twitterHandle) {
+          setTag(
+            /<meta name="twitter:site" content=".*?" \/>/,
+            `<meta name="twitter:site" content="${escapeHtml(twitterHandle)}" />`
+          );
+          setTag(
+            /<meta name="twitter:creator" content=".*?" \/>/,
+            `<meta name="twitter:creator" content="${escapeHtml(twitterHandle)}" />`
           );
+        } else {
+          removeTag(/[ \t]*<meta name="twitter:site" content=".*?" \/>\n?/);
+          removeTag(/[ \t]*<meta name="twitter:creator" content=".*?" \/>\n?/);
         }
 
         return html;
       } catch (error) {
-        console.error('❌ Failed to parse dory.json for metadata injection:', error);
+        console.error('❌ Failed to inject metadata from dory.json:', error);
         return html;
       }
     },

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

@@ -1,190 +1,37 @@
 import type { Plugin } from 'vite';
-import fs from 'fs';
 import path from 'path';
+import { generateLlmsIndex, generateLlmContent } from './llm-txt-generator';
 
-// Read dory.json to get navigation order (flat list, in order)
-function getNavigationOrder(docsDir: string): string[] {
-  const doryJsonPath = path.join(docsDir, 'dory.json');
-  if (!fs.existsSync(doryJsonPath)) return [];
-  let doryJson;
-  try {
-    doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
-  } catch (error) {
-    const detail = error instanceof SyntaxError ? error.message : String(error);
-    console.error(`Failed to parse ${doryJsonPath}: ${detail}`);
-    return [];
-  }
-  const order: string[] = [];
-
-  function walkPages(pages: any[]) {
-    for (const page of pages) {
-      if (typeof page === 'string') {
-        order.push(page);
-      } else if (typeof page === 'object' && page.pages) {
-        walkPages(page.pages);
+/**
+ * Dev server plugin that serves llms.txt and llms-full.txt on demand,
+ * generated fresh per request from the docs directory.
+ */
+export function llmTxtDevServer(): Plugin {
+  const serveText = (generate: (docsDir: string) => string) =>
+    (req: any, res: any, next: () => void) => {
+      if (req.method !== 'GET') {
+        return next();
       }
-    }
-  }
 
-  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);
-          }
-        }
+      try {
+        const docsDir = path.join(process.cwd(), 'docs');
+        const content = generate(docsDir);
+
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.setHeader('Content-Length', Buffer.byteLength(content));
+        res.end(content);
+      } catch (error) {
+        console.error('Error generating LLM text:', error);
+        res.statusCode = 500;
+        res.end('Internal Server Error');
       }
-    }
-  }
-  return order;
-}
-
-// Function to parse frontmatter from MDX content
-function parseFrontmatter(content: string) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
-  if (!frontmatterMatch) return { data: {}, content };
-
-  const frontmatter = frontmatterMatch[1];
-  const data: Record<string, string> = {};
-
-  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 and map by relative path (without .mdx)
-function findMdxFilesMap(dir: string, baseDir: string): Record<string, string> {
-  const files: Record<string, string> = {};
-  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;
-}
-
-// Function to clean MDX content for LLM consumption
-function cleanMdxContent(content: string): string {
-  // 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;
-}
+    };
 
-// Function to generate LLM text content in dory.json order, then append any extra files
-function generateLlmContent(docsDir: string): string {
-  const navOrder = getNavigationOrder(docsDir);
-  const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
-  const usedKeys = new Set<string>();
-  let aggregatedContent = '';
-
-  // Output files in navigation order, in order as in dory.json
-  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, content } = parseFrontmatter(rawContent);
-    const cleanedContent = cleanMdxContent(content);
-
-    // Add file header
-    aggregatedContent += `\n# ${fileKey}.mdx\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';
-  }
-
-  // Output 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, content } = parseFrontmatter(rawContent);
-    const cleanedContent = cleanMdxContent(content);
-
-    aggregatedContent += `\n# ${fileKey}.mdx\n`;
-    if (data.title) {
-      aggregatedContent += `## ${data.title}\n\n`;
-    }
-    if (data.description) {
-      aggregatedContent += `${data.description}\n\n`;
-    }
-    aggregatedContent += cleanedContent + '\n\n';
-    aggregatedContent += '---\n\n';
-  }
-
-  // Remove leading newlines for the very first file, so the first file is at the very top
-  return aggregatedContent.replace(/^\n+/, '').trim();
-}
-
-export function llmTxtDevServer(): Plugin {
   return {
     name: 'llm-txt-dev-server',
     configureServer(server) {
-      server.middlewares.use('/llms.txt', (req, res, next) => {
-        if (req.method !== 'GET') {
-          return next();
-        }
-
-        try {
-          const docsDir = path.join(process.cwd(), 'docs');
-          const llmContent = generateLlmContent(docsDir);
-
-          res.setHeader('Content-Type', 'text/plain; charset=utf-8');
-          res.setHeader('Content-Length', Buffer.byteLength(llmContent));
-          res.end(llmContent);
-        } catch (error) {
-          console.error('Error generating LLM text:', error);
-          res.statusCode = 500;
-          res.end('Internal Server Error');
-        }
-      });
+      server.middlewares.use('/llms.txt', serveText(generateLlmsIndex));
+      server.middlewares.use('/llms-full.txt', serveText(generateLlmContent));
     }
   };
-}
+}