@clidey/dory 0.21.1 → 0.21.2

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm add:*)",
+      "Bash(mv:*)",
+      "Bash(pnpm exec tsx:*)",
+      "Bash(npx tsx:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/CLAUDE.md

@@ -2,6 +2,23 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Communication Style
+- Maintain a professional, neutral tone in all communications
+- Use exclamation points sparingly and only when genuinely necessary
+- Approach problems with the measured perspective of an experienced software engineer
+- Keep a level head when discussing technical challenges and solutions
+- Focus on clear, factual explanations without unnecessary enthusiasm
+
+## Development requirements
+To develop Dory, follow the below requirements every time you do a task:
+1. Clean code is paramount—make sure it is easy to understand and follow
+2. Do not overengineer if you can help it—only add what is required.
+3. Do not remove or modify existing functionally UNLESS you have to and UNLESS you can justify it.
+4. Do not change existing variable names UNLESS absolutely necessary.
+5. Do not leave unused code lying around.
+6. Ask as many questions as you have to in order to understand your task.
+7. You MUST use multiple subagents wherever possible to help you accomplish your task faster.
+
 ## Project Overview
 
 Dory is a lightweight static site generator for technical documentation, published as `@clidey/dory` on npm. It uses Preact, Vite, TypeScript, and Tailwind CSS.

package/README.md

@@ -10,7 +10,6 @@ Dory is a lightweight static site generator built for developers who want fast,
 
 Built with [Preact](https://preactjs.com/), [Vite](https://vitejs.dev/), [Tailwind CSS](https://tailwindcss.com/), [Mermaid](https://mermaid.js.org/), and [TypeScript](https://www.typescriptlang.org/).
 
----
 
 ## 🚀 Why Dory?
 
@@ -23,7 +22,10 @@ Dory is:
 - 🌐 **Portable** — No SSR, no lock-in, deploy anywhere.
 - 🧩 **Flexible** — Hackable theme, readable codebase, minimal magic.
 
----
+
+## 🎬 Quick Demo
+
+https://github.com/user-attachments/assets/5a2840ce-a0b9-41fd-8d15-3ee1d2356f07
 
 ## ✨ Features
 
@@ -36,7 +38,6 @@ Dory is:
 - 🌍 Deploy to Netlify, Vercel, S3, GitHub Pages — your call
 - 🌐 HTTP client for testing API endpoints (automatic inference from openapi.json)
 
----
 
 ## 📦 CLI Installation
 
@@ -71,6 +72,24 @@ Previews the built documentation site:
 dory preview
 ```
 
+#### `dory verify:content`
+Verifies that MDX content compiles without errors:
+- Silent on success (no output means no errors)
+- Shows detailed error messages on failure
+- Uses the same preprocessing as the main build
+- Perfect for automated testing and debugging
+
+```bash
+# Verify content directly
+dory verify:content --content "# Hello World\n\nThis is a test."
+
+# Verify content from file (recommended for complex content)
+dory verify:content --file content.mdx
+
+# Development repository usage:
+pnpm exec tsx bin/dory.ts verify:content --file content.mdx
+```
+
 #### `dory help`
 Shows CLI usage information:
 
@@ -78,7 +97,6 @@ Shows CLI usage information:
 dory help
 ```
 
----
 
 ## 🧑‍💻 Development Setup
 
@@ -93,7 +111,6 @@ git clone https://github.com/clidey/dory.git
 cd dory
 ````
 
----
 
 ### 2️⃣ Install Dependencies
 
@@ -146,7 +163,6 @@ pnpm run build
 
 This will create a `dist` directory containing the fully built static site, ready to be served.
 
----
 
 ## 🐳 Docker Deployment (Optional)
 
@@ -176,8 +192,6 @@ docker run -it -p 8080:80 docs:1.0.0
 
 > The site will be available at `http://localhost:8080` inside your browser.
 
----
-
 ## 📂 Notes
 
 * `pnpm run build` creates the static site inside the `dist` folder, which can be served using any static file server.
@@ -192,4 +206,3 @@ We’re actively improving Dory. Here’s what’s on deck:
 * [ ] 🎨 **Themes** — full theming support with a flexible theme API
 * [ ] 🌐 **Multi-language Support** — internationalization (i18n) & localization (l10n)
 * [ ] 🚀 **GraphQL Client** — integrated GraphQL playground and client support
-* [ ] 🔄 **WebSocket Client** — built-in WebSocket utilities for real-time API demos

package/bin/{dory.js → dory.ts}

@@ -1,10 +1,11 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S npx tsx
 
+// @ts-nocheck - gang
 import { execSync } from 'child_process';
 import { existsSync, rmSync, mkdirSync, cpSync, readFileSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url'
-import http from 'http';
+import { fileURLToPath } from 'url';
+import { createServer } from 'http';
 import sirv from 'sirv';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -108,7 +109,7 @@ const commands = {
       brotli: true,
     });
 
-    const server = http.createServer((req, res) => {
+    const server = createServer((req, res) => {
       serve(req, res);
     });
 
@@ -117,6 +118,61 @@ const commands = {
     });
   },
 
+  'verify:content': async () => {
+    const args = process.argv.slice(3);
+    let content = '';
+    let fileName = '';
+    
+    // Parse arguments
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--content' && i + 1 < args.length) {
+        content = args[i + 1];
+        break;
+      } else if (args[i] === '--file' && i + 1 < args.length) {
+        const filePath = args[i + 1];
+        if (!existsSync(filePath)) {
+          console.error(`❌ Error: File not found: ${filePath}`);
+          process.exit(1);
+        }
+        content = readFileSync(filePath, 'utf8');
+        fileName = filePath;
+        break;
+      }
+    }
+    
+    if (!content) {
+      console.error('❌ Error: --content or --file argument is required');
+      console.log('Usage: dory verify:content --content "<mdx-content>" | --file <path-to-mdx-file>');
+      process.exit(1);
+    }
+    
+    try {
+      // Use the shared MDX processor that matches the main build exactly
+      const { verifyMdxContent } = await import('../src/mdx/processor.ts');
+      const result = await verifyMdxContent(content, fileName);
+      
+      if (!result.valid) {
+        throw result.error;
+      }
+      
+      // Silent success - no output means no errors
+      
+    } catch (error) {
+      console.error('❌ MDX compilation failed:');
+      console.error(error.message);
+      
+      // Provide more detailed error information if available
+      if (error.line !== undefined && error.column !== undefined) {
+        console.error(`   at line ${error.line}, column ${error.column}`);
+      }
+      if (error.source) {
+        console.error('   Source:', error.source);
+      }
+      
+      process.exit(1);
+    }
+  },
+
   help: () => {
     console.log(`
 🐟 Dory CLI - Your Friendly Documentation Builder
@@ -125,19 +181,26 @@ Usage:
   dory <command>
 
 Commands:
-  build     Build your documentation site
-            - Needs dory.json in your project
-            - Creates a beautiful dist folder
-            
-  preview   Preview your built documentation
-            - Shows your docs in the browser
-            - Run build first!
-            
-  help      Show this help message
+  build         Build your documentation site
+                - Needs dory.json in your project
+                - Creates a beautiful dist folder
+                
+  verify:content  Verify that MDX content compiles without errors
+                  - Silent on success, shows errors on failure
+                  - Uses the same preprocessing as the main build
+                  - Accepts --content or --file arguments
+                
+  preview       Preview your built documentation
+                - Shows your docs in the browser
+                - Run build first!
+                
+  help          Show this help message
 
 Examples:
-  dory build    # Build your docs
-  dory preview  # Preview your docs
+  dory build                                      # Build your docs
+  dory verify:content --content "# Hello World"  # Verify MDX content
+  dory verify:content --file content.mdx         # Verify MDX from file
+  dory preview                                    # Preview your docs
 `);
   }
 };
@@ -145,12 +208,19 @@ Examples:
 // Parse command line arguments
 const command = process.argv[2];
 
-if (!command || command === 'help' || command === '--help' || command === '-h') {
-  commands.help();
-} else if (commands[command]) {
-  commands[command]();
-} else {
-  console.error(`❌ Unknown command: ${command}`);
-  console.log('Run "dory help" for usage information');
+async function runCommand() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    commands.help();
+  } else if (commands[command]) {
+    await commands[command]();
+  } else {
+    console.error(`❌ Unknown command: ${command}`);
+    console.log('Run "dory help" for usage information');
+    process.exit(1);
+  }
+}
+
+runCommand().catch((error) => {
+  console.error('❌ Command failed:', error.message);
   process.exit(1);
-}
+});

package/k8s/Dockerfile

@@ -8,7 +8,7 @@ RUN apk add --no-cache git
 COPY ./docs/logo/logo.svg /app/docs/logo/logo.svg
 COPY ./k8s/config/nginx-default.conf /app/k8s/config/nginx-default.conf
 
-RUN npm install -g @clidey/dory@0.21.0
+RUN npm install -g @clidey/dory@0.21.1
 EXPOSE 3000
 
 CMD ["dory", "preview"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "0.21.1",
+  "version": "0.21.2",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [
@@ -12,7 +12,7 @@
     "static-site"
   ],
   "bin": {
-    "dory": "./bin/dory.js"
+    "dory": "./bin/dory.ts"
   },
   "repository": {
     "type": "git",
@@ -39,6 +39,7 @@
     "@fortawesome/react-fontawesome": "^0.2.2",
     "@headlessui/react": "^2.2.4",
     "@heroicons/react": "^2.2.0",
+    "@mdx-js/mdx": "^3.1.0",
     "@mdx-js/preact": "^3.1.0",
     "@mdx-js/rollup": "^3.1.0",
     "@preact/preset-vite": "^2.10.1",
@@ -60,12 +61,15 @@
     "sass-embedded": "^1.89.2",
     "sirv": "^3.0.1",
     "tailwindcss": "^4.1.8",
+    "tsx": "^4.20.4",
     "typescript": "~5.8.3",
     "unist-util-visit": "^5.0.0",
     "vite": "^6.3.5",
     "vite-plugin-mdx": "^3.6.1",
-    "wouter-preact": "^3.7.1",
-    "@types/node": "^24.0.12"
+    "wouter-preact": "^3.7.1"
   },
-  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39",
+  "devDependencies": {
+    "@types/node": "^24.0.12"
+  }
 }

package/src/config/mdx.js

@@ -0,0 +1,12 @@
+import remarkGfm from 'remark-gfm';
+import { remarkSafeVars } from '../plugins/sanitize.ts';
+
+/**
+ * Shared MDX configuration used by both main build (vite.config.ts) 
+ * and CLI build:file command (bin/dory.js)
+ */
+export const getMdxConfig = (isDevelopment = false) => ({
+  providerImportSource: '@mdx-js/preact',
+  remarkPlugins: [remarkGfm, remarkSafeVars],
+  development: isDevelopment,
+});

package/src/config/mdx.ts

@@ -0,0 +1,12 @@
+import remarkGfm from 'remark-gfm';
+import { remarkSafeVars } from '../plugins/sanitize';
+
+/**
+ * Shared MDX configuration used by both main build (vite.config.ts) 
+ * and CLI build:file command (bin/dory.js)
+ */
+export const getMdxConfig = (isDevelopment: boolean = false) => ({
+  providerImportSource: '@mdx-js/preact',
+  remarkPlugins: [remarkGfm, remarkSafeVars],
+  development: isDevelopment,
+});

package/src/mdx/processor.ts

@@ -0,0 +1,174 @@
+import { compile } from '@mdx-js/mdx';
+import { preprocessMdxTags } from '../plugins/sanitize';
+import { getMdxConfig } from '../config/mdx';
+
+export interface ProcessMdxOptions {
+  isDevelopment?: boolean;
+  fileName?: string;
+}
+
+/**
+ * SINGLE SOURCE OF TRUTH for MDX preprocessing.
+ * 
+ * This processor is used by:
+ * - CLI verify:content command (bin/dory.ts) - full processing + compilation
+ * - Vite build via unified-mdx-plugin.ts - preprocessing only
+ * 
+ * ALL MDX processing steps should be added here to ensure consistency.
+ */
+export async function preprocessMdxContent(
+  content: string,
+  fileName: string = 'content.mdx'
+): Promise<{
+  success: boolean;
+  processedContent?: string;
+  error?: Error;
+}> {
+  try {
+    // Step 1: Apply preprocessor (handles MDX tags, code blocks, etc.)
+    const preprocessor = preprocessMdxTags();
+    let processedContent = content;
+    
+    if (preprocessor.transform) {
+      const result = preprocessor.transform(content, fileName);
+      if (result && typeof result === 'object' && result.code) {
+        processedContent = result.code;
+      } else if (typeof result === 'string') {
+        processedContent = result;
+      }
+    }
+    
+    // Step 2: Convert URLs in angle brackets to markdown links
+    // Handles cases like <https://example.com> which MDX would interpret as JSX
+    // But preserves them inside code blocks
+    
+    // Process line by line to handle code blocks correctly
+    const lines = processedContent.split('\n');
+    let inCodeBlock = false;
+    
+    processedContent = lines.map(line => {
+      // Check if we're entering or leaving a code block (with optional indentation)
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        return line;
+      }
+      
+      // Don't process lines inside code blocks
+      if (inCodeBlock) {
+        return line;
+      }
+      
+      // For lines outside code blocks, preserve inline code
+      // More robust regex that handles inline code with potential spaces
+      // Matches: `...` including multi-line content
+      let result = '';
+      let lastIndex = 0;
+      
+      // Find all inline code spans in the line
+      const inlineCodeRegex = /`([^`]+)`/g;
+      let match;
+      
+      while ((match = inlineCodeRegex.exec(line)) !== null) {
+        // Process text before the inline code
+        const beforeCode = line.substring(lastIndex, match.index);
+        result += beforeCode.replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
+        
+        // Keep inline code as-is
+        result += match[0];
+        
+        lastIndex = match.index + match[0].length;
+      }
+      
+      // Process remaining text after last inline code (or entire line if no inline code)
+      const remainingText = line.substring(lastIndex);
+      result += remainingText.replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
+      
+      return result;
+    }).join('\n');
+    
+    // Step 3: Add any future preprocessing steps here
+    // Example: processedContent = await yourNewPreprocessor(processedContent);
+    // Example: processedContent = removeHTMLComments(processedContent);
+    // Example: processedContent = expandCustomShortcodes(processedContent);
+    // ALL preprocessing added here will automatically apply to:
+    // - CLI commands (verify:content)
+    // - Vite build (pnpm run build)
+    // - Vite dev server (pnpm run dev)
+    
+    return {
+      success: true,
+      processedContent
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error as Error
+    };
+  }
+}
+
+/**
+ * Process and compile MDX content through the full pipeline.
+ * Used by CLI commands that need the compiled output.
+ */
+export async function processMdxContent(
+  content: string, 
+  options: ProcessMdxOptions = {}
+): Promise<{ 
+  success: boolean; 
+  compiled?: any; 
+  error?: Error;
+  processedContent?: string;
+}> {
+  const { isDevelopment = false, fileName = 'content.mdx' } = options;
+  
+  try {
+    // Step 1: Preprocess
+    const preprocessResult = await preprocessMdxContent(content, fileName);
+    if (!preprocessResult.success) {
+      return {
+        success: false,
+        error: preprocessResult.error
+      };
+    }
+    
+    const processedContent = preprocessResult.processedContent || content;
+    
+    // Step 2: Compile MDX with the same config as main build
+    const mdxConfig = getMdxConfig(isDevelopment);
+    const compiled = await compile(processedContent, {
+      ...mdxConfig,
+    });
+    
+    return {
+      success: true,
+      compiled,
+      processedContent
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error as Error
+    };
+  }
+}
+
+/**
+ * Verify MDX content can be compiled without errors.
+ * Uses the same processing pipeline as processMdxContent.
+ */
+export async function verifyMdxContent(
+  content: string,
+  fileName?: string
+): Promise<{ valid: boolean; error?: Error }> {
+  const result = await processMdxContent(content, { fileName });
+  
+  if (result.success) {
+    return { valid: true };
+  } else {
+    return { 
+      valid: false, 
+      error: result.error 
+    };
+  }
+}

package/src/plugins/sanitize.ts

@@ -83,9 +83,23 @@ export function preprocessMdxTags() {
       // Remove leading whitespace from code fence blocks
       let processed = code.replace(/^(\s+)(```\w*)/gm, '$2');
 
+      // Handle self-closing tags first (like <VideoPlayer />)
+      processed = processed.replace(/<([A-Za-z][A-Za-z0-9]*)[^>]*\/>/g, (match, tag, offset) => {
+        // If inside a code block, do not touch
+        if (isInsideCodeBlock(processed, offset)) {
+          return match;
+        }
+        
+        // If unknown component, treat as text
+        if (!KNOWN_COMPONENTS.includes(tag)) {
+          return `\`${match}\``;
+        }
+        return match;
+      });
+
       // Only replace unrecognized <someTag> with `"<someTag>"` if NOT inside a code block
-      // This regex finds all <tag> occurrences
-      processed = processed.replace(/<([a-z][a-z0-9]*)>/gi, (match, tag, offset) => {
+      // This regex finds all <tag> occurrences (fixed to handle uppercase)
+      processed = processed.replace(/<([A-Za-z][A-Za-z0-9]*)>/g, (match, tag, offset) => {
         // If inside a code block, do not touch
         if (isInsideCodeBlock(processed, offset)) {
           return match;
@@ -111,8 +125,8 @@ export function preprocessMdxTags() {
         return `\`<${tag}>\``;
       });
 
-      // This regex finds all <tag> and </tag> occurrences
-      processed = processed.replace(/<\/?([a-z][a-z0-9]*)>/gi, (match, tag, offset) => {
+      // This regex finds all <tag> and </tag> occurrences (fixed to handle uppercase)
+      processed = processed.replace(/<\/?([A-Za-z][A-Za-z0-9]*)>/g, (match, tag, offset) => {
         // If inside a code block, do not touch
         if (isInsideCodeBlock(processed, offset)) {
           return match;

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

@@ -0,0 +1,35 @@
+import type { Plugin } from 'vite';
+import { preprocessMdxContent } from '../mdx/processor';
+
+/**
+ * Unified MDX preprocessing plugin for Vite.
+ * This plugin ensures that ALL MDX preprocessing goes through the same pipeline
+ * as the CLI verify:content command.
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for MDX preprocessing.
+ * Any changes to MDX processing should be made in src/mdx/processor.ts
+ */
+export function unifiedMdxPreprocessor(): Plugin {
+  return {
+    name: 'unified-mdx-preprocessor',
+    enforce: 'pre', // Must run before the MDX plugin
+    async transform(code: string, id: string) {
+      if (!id.endsWith('.mdx')) return;
+      
+      // Process through the unified preprocessing pipeline
+      const result = await preprocessMdxContent(code, id);
+
+      if (!result.success) {
+        // Throw the error to stop the build
+        throw result.error;
+      }
+
+      // Return the preprocessed content
+      // The actual MDX compilation will be handled by @mdx-js/rollup plugin
+      return {
+        code: result.processedContent || code,
+        map: null
+      };
+    }
+  };
+}

package/tsconfig.bin.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": true,
+    "noImplicitAny": false,
+    "noImplicitReturns": false,
+    "noImplicitThis": false
+  },
+  "include": [
+    "bin/dory.ts"
+  ]
+}

package/vite.config.ts

@@ -2,21 +2,19 @@ import { defineConfig } from 'vite';
 import preact from '@preact/preset-vite';
 import mdx from '@mdx-js/rollup';
 import tailwindcss from '@tailwindcss/vite'
-import remarkGfm from 'remark-gfm';
-import { preprocessMdxTags, remarkSafeVars } from './src/plugins/sanitize';
+import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin';
 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';
+import { getMdxConfig } from './src/config/mdx';
 
-export default defineConfig({
+export default defineConfig(({ command }) => ({
   plugins: [
-    preprocessMdxTags(),
+    // SINGLE SOURCE OF TRUTH: All MDX preprocessing happens in src/mdx/processor.ts
+    unifiedMdxPreprocessor(),
     preact(),
-    mdx({
-      providerImportSource: '@mdx-js/preact',
-      remarkPlugins: [remarkGfm, remarkSafeVars],
-    }),
+    mdx(getMdxConfig(command === 'serve')),
     tailwindcss(),
     llmTxtGenerator(),
     llmTxtDevServer(),
@@ -33,4 +31,4 @@ export default defineConfig({
   server: {
     allowedHosts: true,
   },
-});
+}));