@udx/md2html 1.0.0

package/README.md

@@ -0,0 +1,219 @@
+# @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 and copy buttons
+- **Responsive Images**: Handles high-resolution images with proper sizing and caption support
+- **Watch Mode**: Automatically rebuilds when source files change with intelligent debouncing
+- **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 --src path/to/file.md --out output.html
+
+# Convert all markdown files in a directory
+md2html --src path/to/markdown/dir --out documentation.html
+
+# Watch for changes and rebuild automatically
+md2html --src path/to/markdown/dir --out documentation.html --watch
+
+# Enable debug output
+md2html --src path/to/markdown/dir --out documentation.html --debug
+```
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-s, --src <path>` | Source markdown file or directory (required) |
+| `-o, --out <path>` | Output HTML file path (required) |
+| `-w, --watch` | Watch for changes and rebuild automatically |
+| `-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
+<!-- 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:
+
+```markdown
+<!-- TOC -->
+```
+
+### 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
+```
+
+## 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
+
+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
+
+## 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
+
+### 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
+  <!-- author: UDX Team -->
+  <!-- date: April 30, 2025 -->
+  <!-- version: 1.0 -->
+  ```
+
+### 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