@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

``bash


Install globally

npm install -g @udx/md2html

Or install locally in your project

npm install --save-dev @udx/md2html
`

Usage Examples

`bash


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 | Source markdown file or directory (required) |
| -o, --out | 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 | Port for preview server (default: random) |
| -d, --debug | Enable debug logging |
| -h, --help | Display help information |
| -v, --version | Output the version number |

Markdown Features

$3

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

`markdown





`

$3

Add a table of contents anywhere in your document:

`markdown

`

$3

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

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

$3

Add captions to images with this syntax:

`markdown
!Alt text
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.

$3

`bash


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
`

$3

`bash


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

$3

- 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:
`markdown



`

$3

- Documentation Pipeline: Generate documentation from multiple sources
`bash
# 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
`bash
# 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