HTML to Markdown Extractor

Advanced HTML to Markdown converter with email-specific optimizations. Perfect for processing email content, newsletters, and complex HTML documents into clean, readable Markdown.

✨ Features

• 🎯 Email-optimized: Special handling for Outlook, Gmail, and other email clients
• 📧 Email signatures: Automatic detection and formatting of email signatures
• 📋 Table conversion: Smart table to Markdown conversion
• 🎨 Inline styles: Converts inline CSS styles to Markdown formatting
• 📝 Custom rules: Extensible rule system for custom HTML elements
• 🚀 TypeScript: Full TypeScript support with comprehensive type definitions
• ⚡ Performance: Optimized for large documents and batch processing
• 🔧 Configurable: Extensive options for customizing output format

🚀 Quick Start

1npm install @abdumajid/html-to-md-extractor

1const { emailToMarkdown } = require('@abdumajid/html-to-md-extractor');
2
3const emailHtml = `
4  <div class="email-content">
5    <h1>Welcome!</h1>
6    <p>Hello <strong>John</strong>,</p>
7    <p>Thanks for joining our <em>newsletter</em>!</p>
8    <div class="signature">
9      <p>Best regards,<br>The Team</p>
10    </div>
11  </div>
12`;
13
14const result = emailToMarkdown(emailHtml);
15console.log(result.markdown);

Output:

1# Welcome!
2
3Hello **John**,
4
5Thanks for joining our *newsletter*!
6
7---
8Best regards,
9The Team

📖 Documentation

Basic Usage

1const { htmlToMarkdown, emailToMarkdown } = require('@abdumajid/html-to-md-extractor');
2
3// For general HTML
4const result1 = htmlToMarkdown('<p>Hello <strong>world</strong>!</p>');
5
6// For email HTML (with email-specific optimizations)
7const result2 = emailToMarkdown(emailHtml, {
8  handleEmailSignatures: true,
9  convertInlineStyles: true,
10  tableHandling: 'convert'
11});

TypeScript Support

1import { 
2  emailToMarkdown, 
3  ConversionOptions, 
4  ConversionResult 
5} from '@abdumajid/html-to-md-extractor';
6
7const options: ConversionOptions = {
8  handleEmailSignatures: true,
9  preserveEmailQuotes: true,
10  tableHandling: 'convert'
11};
12
13const result: ConversionResult = emailToMarkdown(html, options);

📊 Real-World Examples

Outlook Email Processing

1const outlookEmail = `
2  <div class="WordSection1">
3    <p class="MsoNormal">PU today 2200, can likely be worked in earlier</p>
4    <p class="MsoNormal">Del Monday 9am in Joplin MO</p>
5    <p class="MsoNormal">Load of packaging material 9360lbs</p>
6    <p class="MsoNormal">Paying 1100</p>
7    <table class="MsoNormalTable" border="0">
8      <tr>
9        <td><b>Fallin Smith</b></td>
10      </tr>
11      <tr>
12        <td>Transportation Broker</td>
13      </tr>
14    </table>
15  </div>
16`;
17
18const result = emailToMarkdown(outlookEmail, {
19  handleOutlookSpecific: true,
20  handleEmailSignatures: true
21});

Newsletter/Marketing Email

1const newsletter = `
2  <div style="max-width: 600px;">
3    <h1>🎉 Special Offer!</h1>
4    <p>Hi <strong>Sarah</strong>,</p>
5    <p>Get <mark>50% off</mark> your next purchase!</p>
6    <table border="1">
7      <tr><th>Product</th><th>Price</th></tr>
8      <tr><td>Widget A</td><td>$25.00</td></tr>
9    </table>
10    <p><a href="https://shop.com/sale">Shop Now</a></p>
11  </div>
12`;
13
14const result = emailToMarkdown(newsletter);

Batch Processing

1const { HTMLToMarkdownExtractor } = require('@abdumajid/html-to-md-extractor');
2
3const extractor = new HTMLToMarkdownExtractor({
4  handleEmailSignatures: true
5});
6
7// Process multiple emails efficiently
8const emailBatch = [email1, email2, email3, /* ... */];
9const results = await extractor.convertBatch(emailBatch);
10
11extractor.dispose(); // Clean up resources

⚙️ Configuration Options

1interface ConversionOptions {
2  // Basic formatting
3  preserveWhitespace?: boolean;        // Default: false
4  trimWhitespace?: boolean;            // Default: true
5  bulletListMarker?: string;           // Default: '-'
6  codeBlockStyle?: 'indented' | 'fenced'; // Default: 'fenced'
7  strongDelimiter?: string;           // Default: '**'
8  emDelimiter?: string;               // Default: '*'
9  linkStyle?: 'inlined' | 'referenced'; // Default: 'inlined'
10  
11  // Email-specific options
12  preserveEmailHeaders?: boolean;      // Default: true
13  handleEmailSignatures?: boolean;     // Default: true
14  convertInlineStyles?: boolean;       // Default: true
15  preserveEmailQuotes?: boolean;       // Default: true
16  handleOutlookSpecific?: boolean;     // Default: true
17  
18  // Table handling
19  tableHandling?: 'preserve' | 'convert' | 'remove'; // Default: 'convert'
20  
21  // Advanced customization
22  customRules?: ConversionRule[];
23  ignoreElements?: string[];
24  keepElements?: string[];
25}

🔧 Advanced Usage

Custom Rules

1const { RuleBuilder } = require('@abdumajid/html-to-md-extractor');
2
3const customRule = RuleBuilder.create()
4  .forSelector('mark')
5  .withReplacement('==${content}==')
6  .withPriority(2)
7  .build();
8
9const result = htmlToMarkdown(html, {
10  customRules: [customRule]
11});

Email Context Detection

1const { EmailUtils } = require('@abdumajid/html-to-md-extractor');
2
3const emailUtils = new EmailUtils();
4const context = emailUtils.detectEmailContext(document);
5
6console.log({
7  isEmail: context.isEmailContent,
8  hasSignature: context.hasSignature,
9  clientType: context.clientType // 'outlook', 'gmail', etc.
10});

🌐 Browser Support

Works in both Node.js and browsers:

1<script type="module">
2  import { emailToMarkdown } from 'https://unpkg.com/@abdumajid/html-to-md-extractor@latest/dist/index.esm.js';
3  
4  const result = emailToMarkdown(html);
5  console.log(result.markdown);
6</script>

📦 API Reference

Main Functions

• htmlToMarkdown(html, options?) - Convert general HTML to Markdown
• emailToMarkdown(html, options?) - Convert email HTML with optimizations

Classes

• HTMLToMarkdownExtractor - Main converter class for advanced usage
• EmailUtils - Email-specific utilities
• RuleBuilder - Builder for custom conversion rules

Types

• ConversionOptions - Configuration interface
• ConversionResult - Result with markdown and metadata
• EmailHeaders - Extracted email header information

🔄 Migration Guide

From v0.x to v1.x

1// Old way
2const converter = require('html-to-md-extractor');
3const result = converter.convert(html);
4
5// New way
6const { emailToMarkdown } = require('@abdumajid/html-to-md-extractor');
7const result = emailToMarkdown(html);

🚀 Performance

• Fast: Processes typical emails in < 10ms
• Memory efficient: Optimized for large documents
• Batch processing: Handle thousands of emails efficiently
• Caching: Intelligent rule and regex caching

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1git clone https://github.com/abdumajidRashidov/html-to-md-extractor.git
2cd html-to-md-extractor
3npm install
4npm test
5npm run build

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• turndown - General HTML to Markdown converter
• node-html-markdown - Another HTML to Markdown library
• html2md - Simple HTML to Markdown converter

🆘 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

---

Made with ❤️ for better email and HTML processing