@udx/md2html 1.1.0 → 1.2.1

package/README.md

@@ -6,9 +6,10 @@ A sophisticated tool for converting markdown files into a single, visually polis
 
 - **Markdown Consolidation**: Intelligently combines and sorts multiple markdown files into a single cohesive document
 - **Magazine-Quality Styling**: Applies high-end editorial styling with precise typography and spacing
-- **Code Block Enhancements**: Syntax highlighting with file type indicators and copy buttons
+- **Code Block Enhancements**: Syntax highlighting with file type indicators
 - **Responsive Images**: Handles high-resolution images with proper sizing and caption support
 - **Watch Mode**: Automatically rebuilds when source files change with intelligent debouncing
+- **Browser Preview**: Live preview server with automatic browser opening
 - **Print Optimization**: Carefully crafted print styling for document printing and PDF generation
 - **Table of Contents**: Auto-generates navigable table of contents from document structure
 - **Customizable**: External CSS, JavaScript, and HTML templates for easy customization
@@ -36,25 +37,33 @@ npm install --save-dev @udx/md2html
 
 ```bash
 # Convert a single markdown file to HTML
-md2html --src path/to/file.md --out output.html
+md2html -s path/to/file.md -o output.html
 
-# Convert all markdown files in a directory
-md2html --src path/to/markdown/dir --out documentation.html
+# Convert all markdown files in a directory  
+md2html -s path/to/markdown/dir -o documentation.html
 
 # Watch for changes and rebuild automatically
-md2html --src path/to/markdown/dir --out documentation.html --watch
+md2html -s path/to/markdown/dir -o documentation.html --watch
+
+# Open in browser with live preview
+md2html -s path/to/file.md --preview
+
+# Custom port for preview server
+md2html -s path/to/markdown/dir --preview --port 3000
 
 # Enable debug output
-md2html --src path/to/markdown/dir --out documentation.html --debug
+md2html -s path/to/markdown/dir -o documentation.html --debug
 ```
 
 ## CLI Options
 
 | Option | Description |
 |--------|-------------|
-| `-s, --src <path>` | Source markdown file or directory (required) |
-| `-o, --out <path>` | Output HTML file path (required) |
+| `-s, --src <file>` | Source markdown file or directory (required) |
+| `-o, --out <file>` | Output HTML file path (optional - defaults to ./output.html) |
 | `-w, --watch` | Watch for changes and rebuild automatically |
+| `-p, --preview` | Open generated HTML in browser with live preview server |
+| `--port <number>` | Port for preview server (default: random) |
 | `-d, --debug` | Enable debug logging |
 | `-h, --help` | Display help information |
 | `-v, --version` | Output the version number |
@@ -101,28 +110,6 @@ Add captions to images with this syntax:
 *This is the image caption*
 ```
 
-### Mermaid Diagrams
-
-Create professional diagrams using Mermaid syntax:
-
-````markdown
-```mermaid
-flowchart LR
-    A[Client] --> B[Load Balancer]
-    B --> C[Server1]
-    B --> D[Server2]
-```
-````
-
-Supported Mermaid diagram types:
-- **Flowcharts**: Process flows and workflows
-- **Sequence Diagrams**: System interactions over time
-- **Gantt Charts**: Project timelines and schedules
-- **Entity Relationship Diagrams**: Database schemas
-- **User Journey**: User experience flows
-- **Git Graphs**: Version control workflows
-
-The diagrams are automatically rendered when the HTML document loads, with professional styling that matches the document theme.
 
 ## Customization
 
@@ -170,17 +157,6 @@ gh repo clone owner/repo
 md2html --src ./repo/docs --out documentation.html
 ```
 
-## Command Line Options
-
-```
-Options:
-  -V, --version         output the version number
-  -s, --src <directory> Source directory containing markdown files
-  -o, --out <file>      Output HTML file path
-  -w, --watch           Watch for changes and rebuild automatically (default: false)
-  -d, --debug           Enable debug logging (default: false)
-  -h, --help            display help for command
-```
 
 ## Output Example
 
@@ -193,19 +169,6 @@ The generated HTML document includes:
 - Print-optimized layout with page breaks
 - Responsive design for various screen sizes
 
-## API Usage
-
-md2html can also be used programmatically:
-
-```javascript
-import { buildHtml, watchMarkdown } from '@udx/md2html';
-
-// Build HTML once
-await buildHtml('/path/to/markdown/dir', 'output.html');
-
-// Watch for changes
-watchMarkdown('/path/to/markdown/dir', 'output.html');
-```
 
 ## Best Practices
 

package/index.js

@@ -50,6 +50,9 @@ import { marked } from 'marked';
 import { program } from 'commander';
 import chokidar from 'chokidar';
 import Handlebars from 'handlebars';
+import express from 'express';
+import { createServer } from 'http';
+import open from 'open';
 
 // Custom renderer for handling math blocks
 const renderer = new marked.Renderer();
@@ -86,24 +89,41 @@ const CHAPTER_NAV_STYLES_PATH = path.join(path.dirname(new URL(import.meta.url).
 const SCRIPTS_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), 'static/scripts.js');
 
 program
-  .version('1.1.0')
+  .version('1.2.0')
   .description('Convert markdown files to a single HTML document with Google Docs styling')
-  .option('-s, --src <directory>', 'Source directory containing markdown files')
-  .option('-o, --out <file>', 'Output HTML file path')
+  .option('-s, --src <file>', 'Source markdown file or directory')
+  .option('-o, --out <file>', 'Output HTML file path (optional - defaults to ./output.html)')
   .option('-w, --watch', 'Watch for changes and rebuild automatically', false)
   .option('-d, --debug', 'Enable debug logging', false)
+  .option('-p, --preview', 'Open generated HTML in browser with live preview server', false)
+  .option('--port <number>', 'Port for preview server (default: random)', parseInt)
+  .addHelpText('after', `
+Examples:
+  Basic conversion:
+    md2html -s content/docs
+    md2html --src=content/docs --out=output.html
+  
+  Watch mode:
+    md2html -s content/docs --watch
+  
+  Browser preview:
+    md2html -s content/docs --preview
+    md2html -s content/docs --preview --port 3000
+  
+  Single file:
+    md2html -s document.md --preview`)
   .parse(process.argv);
 
 const options = program.opts();
 
-if (!options.src || !options.out) {
-  console.error('Error: Source directory and output file are required');
+if (!options.src) {
+  console.error('Error: Source markdown file or directory is required');
   program.help();
   process.exit(1);
 }
 
 const srcPath = path.resolve(options.src);
-const outputFile = path.resolve(options.out);
+const outputFile = options.out ? path.resolve(options.out) : path.resolve('./output.html');
 
 const debug = (message) => {
   if (options.debug) {
@@ -647,6 +667,57 @@ async function buildHtml(srcDir, outputFile) {
   }
 }
 
+/**
+ * Gets a random port between 3000-9999
+ */
+function getRandomPort() {
+  return Math.floor(Math.random() * (9999 - 3000 + 1)) + 3000;
+}
+
+/**
+ * Starts a preview server for the generated HTML
+ * @param {string} outputFile - Path to the HTML file to serve
+ * @param {number|null} port - Port to use (null for random)
+ * @returns {Promise<number>} The port the server is running on
+ */
+function startPreviewServer(outputFile, port = null) {
+  return new Promise((resolve, reject) => {
+    const app = express();
+    const targetPort = port || getRandomPort();
+    
+    // Serve the generated HTML file at root
+    app.get('/', (req, res) => {
+      if (!fs.existsSync(outputFile)) {
+        res.status(404).send('<h1>HTML file not found</h1><p>Try rebuilding first</p>');
+        return;
+      }
+      res.sendFile(path.resolve(outputFile));
+    });
+    
+    // Serve any static assets if they exist
+    const staticDir = path.join(path.dirname(outputFile), 'assets');
+    if (fs.existsSync(staticDir)) {
+      app.use('/assets', express.static(staticDir));
+    }
+    
+    const server = createServer(app);
+    
+    server.listen(targetPort, () => {
+      console.log(`🚀 Preview server running at http://localhost:${targetPort}`);
+      resolve(targetPort);
+    });
+    
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE' && !port) {
+        // If random port is in use, try another random port
+        startPreviewServer(outputFile, null).then(resolve).catch(reject);
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
 /**
  * Watches for changes in markdown files and rebuilds HTML
  * @param {string} srcDir - Source directory containing markdown files
@@ -730,8 +801,28 @@ function watchMarkdown(srcDir, outputFile) {
   });
 }
 
-// Watch for changes if enabled
-if (options.watch) {
+// Handle different execution modes
+if (options.preview) {
+  // Preview mode: build HTML, start server, and optionally watch
+  buildHtml(srcPath, outputFile).then((success) => {
+    if (success) {
+      startPreviewServer(outputFile, options.port).then((port) => {
+        // Open browser
+        open(`http://localhost:${port}`);
+        
+        if (options.watch) {
+          console.log('\n👀 Watching for file changes...');
+          watchMarkdown(srcPath, outputFile);
+        } else {
+          console.log('\n💡 Use --watch flag to auto-rebuild on file changes');
+          console.log('Press Ctrl+C to stop the server');
+        }
+      }).catch((err) => {
+        console.error('Failed to start preview server:', err);
+      });
+    }
+  });
+} else if (options.watch) {
   watchMarkdown(srcPath, outputFile);
 } else {
   buildHtml(srcPath, outputFile);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udx/md2html",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Magazine-quality Markdown to HTML converter with professional styling",
   "main": "index.js",
   "type": "module",
@@ -34,8 +34,10 @@
   "dependencies": {
     "chokidar": "^3.5.3",
     "commander": "^11.0.0",
+    "express": "^4.18.2",
     "handlebars": "^4.7.8",
-    "marked": "^9.1.0"
+    "marked": "^9.1.0",
+    "open": "^9.1.0"
   },
   "engines": {
     "node": ">=14.16"