Magazine-quality Markdown to HTML converter with professional styling
npm install @udx/md2htmlA 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.
- 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
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
``bashInstall globally
npm install -g @udx/md2html
Usage Examples
`bash
Convert a single markdown file to HTML
md2html -s path/to/file.md -o output.htmlConvert all markdown files in a directory
md2html -s path/to/markdown/dir -o documentation.htmlWatch for changes and rebuild automatically
md2html -s path/to/markdown/dir -o documentation.html --watchOpen in browser with live preview
md2html -s path/to/file.md --previewCustom port for preview server
md2html -s path/to/markdown/dir --preview --port 3000Enable 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-processingArchitecture 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.htmlWatch for changes and rebuild automatically
md2html --src /path/to/markdown/dir --out output.html --watchEnable 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.htmlCreate 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
``ISC