# @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 ### Document Metadata Add metadata at the top of your markdown files using HTML comments: ```markdown ``` ### Table of Contents Add a table of contents anywhere in your document: ```markdown ``` ### Code Blocks Code blocks are beautifully formatted with syntax highlighting and file type indicators: ````markdown ```javascript const greeting = 'Hello, world!'; console.log(greeting); ``` ```` ### Image Captions Add captions to images with this syntax: ```markdown ![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 ```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 ``` ### Integration with Other UDX Tools ```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 ### 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: ```markdown ``` ### Integration Patterns - **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