@udx/md2html - Magazine-Quality Markdown to HTML Converter

A sophisticated tool for converting markdown files into a single, visually polished HTML document with magazine-quality styling. Perfect for creating professional documentation, reports, and publications from markdown source files.

Key Features

• 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
• 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

Architecture

The tool has been refactored with a clean, modular architecture:

• Handlebars Templates: The HTML structure is defined in a Handlebars template (static/view.hbs)
• External CSS: All styling is maintained in a dedicated CSS file (static/styles.css)
• External JavaScript: All DOM post-processing in a separate JS file (static/scripts.js)
• Single Output File: Despite the modular development approach, the output is a self-contained HTML file with all CSS and JS embedded inline

Installation

# Install globally
npm install -g @udx/md2html

# Or install locally in your project
npm install --save-dev @udx/md2html

Usage Examples

# Convert a single markdown file to HTML
md2html -s path/to/file.md -o output.html

# Convert all markdown files in a directory  
md2html -s path/to/markdown/dir -o documentation.html

# Watch for changes and rebuild automatically
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 -s path/to/markdown/dir -o documentation.html --debug

CLI Options

| Option | Description | |--------|-------------| | -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 |

Markdown Features

Document Metadata

Add metadata at the top of your markdown files using HTML comments:

<!-- title: My Document Title -->
<!-- description: A detailed description of my document -->
<!-- author: Your Name -->
<!-- date: January 1, 2025 -->
<!-- version: v1.0 -->

Table of Contents

Add a table of contents anywhere in your document:

<!-- TOC -->

Code Blocks

Code blocks are beautifully formatted with syntax highlighting and file type indicators:

```javascript
const greeting = 'Hello, world!';
console.log(greeting);
```

Image Captions

Add captions to images with this syntax:

![Alt text](path/to/image.jpg)
*This is the image caption*

Customization

This tool is designed to be easily customizable:

• static/view.hbs - Edit the HTML template structure
• static/styles.css - Modify the styling
• static/scripts.js - Adjust the DOM post-processing

Architecture Details

The refactored architecture follows modern principles:

1. Modular Development: Template, styles, and scripts are maintained in separate files for easy editing
2. Self-Contained Output: The output is a single HTML file with all CSS and JS embedded inline
3. Template-Based: Uses Handlebars for cleaner template management
4. Efficient File Watching: Uses Chokidar with debouncing for reliable file watching

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Basic Usage

# Convert markdown files to a single HTML document
md2html --src /path/to/markdown/dir --out output.html

# Watch for changes and rebuild automatically
md2html --src /path/to/markdown/dir --out output.html --watch

# Enable debug logging
md2html --src /path/to/markdown/dir --out output.html --debug

Integration with Other UDX Tools

# Process content with mcurl, then convert to HTML
mcurl https://udx.io/guidance | mq --clean-content > content.md
md2html --src ./content.md --out guidance.html

# Create documentation from GitHub repository
gh repo clone owner/repo
md2html --src ./repo/docs --out documentation.html

Output Example

The generated HTML document includes:

• Document header with title, description, author, and date
• Table of contents with links to sections
• Content sections with proper heading hierarchy
• Google Docs-like styling for professional appearance
• Print-optimized layout with page breaks
• Responsive design for various screen sizes

Best Practices

Document Organization

• Organize markdown files with numeric prefixes (e.g., 01_introduction.md, 02_architecture.md)
• Use consistent heading levels across documents
• Include metadata in HTML comments for better document information:

  <!-- author: UDX Team -->
  <!-- date: April 30, 2025 -->
  <!-- version: 1.0 -->

Integration Patterns

• Documentation Pipeline: Generate documentation from multiple sources

  # Combine API docs and markdown files
  mcurl https://api.example.com/docs | mq --clean-content > api-docs.md
  cp api-docs.md ./docs/
  md2html --src ./docs --out complete-documentation.html

• Content Transformation: Convert between formats

  # Convert HTML to markdown, then to styled HTML
  mcurl https://udx.io/about > about.md
  md2html --src ./about.md --out about-styled.html

License

ISC