@clidey/dory 0.9.0 → 0.11.0

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/sanitize.ts

@@ -13,3 +13,43 @@ export const remarkSafeVars = () => {
     });
   };
 };
+
+const KNOWN_COMPONENTS = [
+  // Text components
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'Row', 'Col', 'a', 'img',
+  // Code components  
+  'code', 'CodeGroup', 'pre',
+  // UI components
+  'Accordion', 'AccordionGroup', 'Icon', 'Card', 'CardGroup',
+  'Callout', 'Note', 'Warning', 'Info', 'Tip', 'Check',
+  'Latex', 'API', 'Expandable', 'ResponseField', 'Properties', 'Property',
+  'Steps', 'Step', 'table', 'th', 'td', 'ul', 'ol', 'li',
+  'APIPlayground', 'WebSocketPlayground', 'AsyncAPI', 'Source',
+  // Common HTML elements that should be preserved
+  'div', 'span', 'br', 'hr', 'strong', 'em', 'b', 'i', 'u', 's',
+  'blockquote', 'nav', 'section', 'article', 'header', 'footer', 'main',
+  'aside', 'figure', 'figcaption', 'details', 'summary', 'mark', 'small',
+  'del', 'ins', 'sub', 'sup', 'kbd', 'samp', 'var', 'time', 'abbr',
+  'address', 'cite', 'q', 'dfn'
+];
+
+export function preprocessMdxTags() {
+  return {
+    name: 'preprocess-mdx-tags',
+    enforce: 'pre' as const,
+    transform(code: string, id: string) {
+      if (!id.endsWith('.mdx')) return;
+
+      // Replace unrecognized <someTag> with `"<someTag>"`
+      const processed = code.replace(/<([a-z][a-z0-9]+)>/gi, (match, tag) => {
+        const known = KNOWN_COMPONENTS.includes(tag);
+        return known ? match : `\`<${tag}>\``; // wrap in backticks to keep as code
+      });
+
+      return {
+        code: processed,
+        map: null,
+      };
+    },
+  };
+}

package/src/ui/layout.tsx

@@ -2,8 +2,9 @@ import type { ComponentChildren } from 'preact';
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
 import { useLocation } from 'wouter-preact';
 import { Navigation } from '../components/navigation';
-import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename } from '../components/store';
+import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename, preloadFrontmatter, ALL_ASYNCAPI } from '../components/store';
 import { OpenAPI } from '../mdx/open-api';
+import { AsyncAPI } from '../mdx/async-api';
 import { Header } from './header';
 import { PrevNextLinks } from './prev-next-link';
 import { TableOfContents } from './table-of-content';
@@ -63,14 +64,21 @@ export default function Layout({ children }: LayoutProps) {
   ], [handleOpenMDX, handleCopyMDX, handleOpenChatGPT, handleOpenAnthropic]);
 
   useEffect(() => {
-    loadMDXFrontMatterForPath(pathname).then(() => {
-      loadAllMDXFrontMatter(pathname).then(() => {
-        setLoading(false);
+    // Try to preload frontmatter first (optimized approach)
+    preloadFrontmatter().then(() => {
+      // If preloading succeeds, we're done
+      setLoading(false);
+    }).catch(() => {
+      // Fallback to the original approach
+      loadMDXFrontMatterForPath(pathname).then(() => {
+        loadAllMDXFrontMatter(pathname).then(() => {
+          setLoading(false);
+        }).catch(() => {
+          setLoading(false);
+        });
       }).catch(() => {
         setLoading(false);
       });
-    }).catch(() => {
-      setLoading(false);
     });
   }, [pathname]);
 
@@ -116,6 +124,21 @@ export default function Layout({ children }: LayoutProps) {
     return { method: tab.openapi.split(' ')[0], path: tab.openapi.split(' ')[1] };
   }, [tab, loading]);
 
+  const asyncAPIJSON = useMemo(() => {
+    if (tab == null || tab.asyncapi == null) {
+      return null;
+    }
+    const firstDirectory = `/${tab.path.split('/')[1]}`;
+    return ALL_ASYNCAPI[`${firstDirectory}/asyncapi.json`].default;
+  }, [tab, loading]);
+  
+  const { operation, channel } = useMemo(() => {
+    if (tab == null || tab.asyncapi == null) {
+      return { operation: '', channel: '' };
+    }
+    return { operation: tab.asyncapi.split(' ')[0].toLowerCase(), channel: tab.asyncapi.split(' ')[1] };
+  }, [tab, loading]);
+
   if (loading) return <div className="h-[25vh] flex grow"><Loading /></div>;
 
   return (
@@ -144,20 +167,22 @@ export default function Layout({ children }: LayoutProps) {
                   )}
                 </header>
                 {
-                  openAPIJSON == null &&
+                  openAPIJSON == null && asyncAPIJSON == null &&
                   <Dropdown className='min-w-[120px]' buttonLabel="AI Actions" items={dropdownItems} />
                 }
               </div>
               <div className="flex-1 min-h-[calc(100vh-2rem)]">
                 {openAPIJSON && tab && "openapi" in tab && method && path ? 
                   <OpenAPI openAPIJson={JSON.parse(openAPIJSON)} method={method} path={path} />
+                 : asyncAPIJSON && tab && "asyncapi" in tab && operation && channel ?
+                  <AsyncAPI asyncAPIJson={JSON.parse(asyncAPIJSON)} operation={operation} channel={channel} />
                  : children}
               </div>
               <PrevNextLinks />
             </article>
           </div>
           {
-            openAPIJSON == null &&
+            openAPIJSON == null && asyncAPIJSON == null &&
             <TableOfContents />
           }
         </main>

package/vite.config.ts

@@ -3,12 +3,15 @@ import preact from '@preact/preset-vite';
 import mdx from '@mdx-js/rollup';
 import tailwindcss from '@tailwindcss/vite'
 import remarkGfm from 'remark-gfm';
-import { remarkSafeVars } from './src/plugins/sanitize';
+import { preprocessMdxTags, remarkSafeVars } from './src/plugins/sanitize';
 import { llmTxtGenerator } from './src/plugins/llm-txt-generator';
 import { llmTxtDevServer } from './src/plugins/llm-txt-dev-server';
+import { frontmatterGenerator } from './src/plugins/frontmatter-generator';
+import { frontmatterDevServer } from './src/plugins/frontmatter-dev-server';
 
 export default defineConfig({
   plugins: [
+    preprocessMdxTags(),
     preact(),
     mdx({
       providerImportSource: '@mdx-js/preact',
@@ -17,6 +20,8 @@ export default defineConfig({
     tailwindcss(),
     llmTxtGenerator(),
     llmTxtDevServer(),
+    frontmatterGenerator(),
+    frontmatterDevServer(),
   ],
   resolve: {
     alias: {