@clidey/dory 0.30.0 → 0.31.0

package/src/plugins/docs-assets.ts

@@ -0,0 +1,79 @@
+import type { Plugin } from 'vite';
+import { cpSync, existsSync, readdirSync, statSync } from 'fs';
+import { resolve, extname } from 'path';
+
+/**
+ * Plugin to copy docs assets to the build output
+ * Since we can't use publicDir for docs (we need to import from it),
+ * this plugin manually copies asset files during build
+ */
+export function docsAssetsPlugin(): Plugin {
+  return {
+    name: 'docs-assets',
+    apply: 'build', // Only run during build
+    closeBundle() {
+      const docsDir = resolve(process.cwd(), 'docs');
+      const outDir = resolve(process.cwd(), 'dist');
+
+      if (!existsSync(docsDir)) {
+        console.warn('[docs-assets] docs directory not found, skipping asset copy');
+        return;
+      }
+
+      // Define asset extensions to copy
+      const assetExtensions = new Set([
+        '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico',
+        '.pdf', '.mp4', '.webm', '.mp3', '.wav',
+        '.woff', '.woff2', '.ttf', '.eot',
+      ]);
+
+      // Define file/folder patterns to skip
+      const skipPatterns = new Set([
+        'dory.json',
+        'node_modules',
+        '.DS_Store',
+      ]);
+
+      const shouldSkip = (name: string) => {
+        if (skipPatterns.has(name)) return true;
+        const ext = extname(name).toLowerCase();
+        // Skip MDX and JSON files (they're processed by Vite)
+        if (ext === '.mdx' || ext === '.md' || ext === '.json') return true;
+        return false;
+      };
+
+      const copyAssets = (srcDir: string, destDir: string, relativePath: string = '') => {
+        const items = readdirSync(srcDir);
+
+        for (const item of items) {
+          if (shouldSkip(item)) continue;
+
+          const srcPath = resolve(srcDir, item);
+          const destPath = resolve(destDir, item);
+          const itemRelativePath = relativePath ? `${relativePath}/${item}` : item;
+
+          try {
+            const stats = statSync(srcPath);
+
+            if (stats.isDirectory()) {
+              // Recursively copy directories
+              copyAssets(srcPath, destPath, itemRelativePath);
+            } else if (stats.isFile()) {
+              const ext = extname(item).toLowerCase();
+              // Copy if it's an asset file
+              if (assetExtensions.has(ext)) {
+                cpSync(srcPath, destPath, { force: true });
+                console.log(`[docs-assets] Copied ${itemRelativePath}`);
+              }
+            }
+          } catch (error) {
+            console.warn(`[docs-assets] Failed to copy ${itemRelativePath}:`, error);
+          }
+        }
+      };
+
+      console.log('[docs-assets] Copying assets from docs to dist...');
+      copyAssets(docsDir, outDir);
+    },
+  };
+}

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

@@ -0,0 +1,158 @@
+import type { Plugin } from 'vite';
+import fs from 'fs';
+import path from 'path';
+
+// 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 [];
+  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  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);
+      }
+    }
+  }
+
+  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: string) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return { data: {}, content };
+
+  const frontmatter = frontmatterMatch[1];
+  const data: Record<string, any> = {};
+
+  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: string, docsDir: string): string {
+  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: 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 generate frontmatter JSON in dory.json order, then append any extra files
+function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
+  const navOrder = getNavigationOrder(docsDir);
+  const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+  const usedKeys = new Set<string>();
+  const frontmatterArray: Array<Record<string, any>> = [];
+
+  // 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
+    });
+  }
+
+  return frontmatterArray;
+}
+
+export function frontmatterDevServer(): Plugin {
+  return {
+    name: 'frontmatter-dev-server',
+    configureServer(server) {
+      server.middlewares.use('/frontmatter.json', (req, res, next) => {
+        if (req.method !== 'GET') {
+          return next();
+        }
+
+        try {
+          const docsDir = path.join(process.cwd(), 'docs');
+          const frontmatterArray = generateFrontmatterJson(docsDir);
+          const jsonContent = JSON.stringify(frontmatterArray, null, 2);
+
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          res.setHeader('Content-Length', Buffer.byteLength(jsonContent));
+          res.end(jsonContent);
+        } catch (error) {
+          console.error('Error generating frontmatter JSON:', error);
+          res.statusCode = 500;
+          res.end('Internal Server Error');
+        }
+      });
+    }
+  };
+}

package/src/plugins/frontmatter-generator.ts

@@ -0,0 +1,157 @@
+import type { Plugin } from 'vite';
+import fs from 'fs';
+import path from 'path';
+
+interface FrontmatterGeneratorOptions {
+  docsDir?: string;
+  outputPath?: string;
+}
+
+// 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 [];
+  const doryJson = JSON.parse(fs.readFileSync(doryJsonPath, 'utf-8'));
+  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);
+      }
+    }
+  }
+
+  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: string) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return { data: {}, content };
+
+  const frontmatter = frontmatterMatch[1];
+  const data: Record<string, any> = {};
+
+  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: string, docsDir: string): string {
+  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: 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 generate frontmatter JSON in dory.json order, then append any extra files
+function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
+  const navOrder = getNavigationOrder(docsDir);
+  const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+  const usedKeys = new Set<string>();
+  const frontmatterArray: Array<Record<string, any>> = [];
+
+  // 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
+    });
+  }
+
+  return frontmatterArray;
+}
+
+export function frontmatterGenerator(options: FrontmatterGeneratorOptions = {}): Plugin {
+  return {
+    name: 'frontmatter-generator',
+    generateBundle() {
+      const docsDir = options.docsDir || path.join(process.cwd(), 'docs');
+      const frontmatterArray = generateFrontmatterJson(docsDir);
+      const jsonContent = JSON.stringify(frontmatterArray, null, 2);
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'frontmatter.json',
+        source: jsonContent
+      });
+
+      console.log(`✅ Generated frontmatter JSON file`);
+      console.log(`📄 Processed ${frontmatterArray.length} MDX files`);
+      console.log(`📝 Total JSON size: ${jsonContent.length} characters`);
+    }
+  };
+}

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

@@ -0,0 +1,108 @@
+import type { Plugin } from 'vite';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { resolve, extname } from 'path';
+
+/**
+ * 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
+ */
+export function htmlFilesMiddleware(): Plugin {
+  // Define asset extensions
+  const assetExtensions = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico',
+    '.pdf', '.mp4', '.webm', '.mp3', '.wav', '.mov',
+    '.woff', '.woff2', '.ttf', '.eot',
+  ]);
+
+  // Map extensions to MIME types
+  const mimeTypes: Record<string, string> = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject',
+  };
+
+  return {
+    name: 'html-files-middleware',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (!req.url) {
+          next();
+          return;
+        }
+
+        // Remove query params
+        const url = req.url.split('?')[0];
+
+        // Check if the request is for a file in the dist directory
+        if (url.startsWith('/dist/')) {
+          const distPath = resolve(process.cwd(), url.slice(1));
+
+          if (existsSync(distPath)) {
+            try {
+              const content = readFileSync(distPath, 'utf-8');
+              const ext = extname(url).toLowerCase();
+              const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+              res.setHeader('Content-Type', contentType);
+              res.setHeader('Cache-Control', 'no-cache');
+              res.setHeader('Access-Control-Allow-Origin', '*');
+              res.end(content);
+              return;
+            } catch (error) {
+              console.error(`Error reading ${distPath}:`, error);
+            }
+          }
+        }
+
+        // Check if the request is for a file in the docs directory
+        // This handles both direct file requests and directory requests
+        const docsPath = resolve(process.cwd(), 'docs', url.slice(1));
+
+        if (existsSync(docsPath)) {
+          try {
+            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);
+                const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+                res.setHeader('Content-Type', contentType);
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.end(content);
+                return;
+              }
+            }
+          } catch (error) {
+            console.error(`Error reading ${docsPath}:`, error);
+          }
+        }
+
+        next();
+      });
+    },
+  };
+}

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

@@ -0,0 +1,76 @@
+import type { Plugin } from 'vite';
+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
+ */
+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)) {
+        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`;
+
+        // Replace title
+        html = html.replace(
+          /<title>.*?<\/title>/,
+          `<title>${defaultTitle}</title>`
+        );
+
+        // Replace meta description
+        html = html.replace(
+          /<meta name="description" content=".*?" \/>/,
+          `<meta name="description" content="${defaultDescription}" />`
+        );
+
+        // Replace Open Graph title
+        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 Twitter title
+        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}" />`
+        );
+
+        return html;
+      } catch (error) {
+        console.error('❌ Failed to parse dory.json for metadata injection:', error);
+        return html;
+      }
+    },
+  };
+}